Skip to main content

​
Create Payment Intent

Initializes a payment session for course enrollment. Automatically selects the appropriate payment gateway (Stripe or Flutterwave) based on user currency.

​
Request Body

​
courseId
number
required
Course ID to purchase
​
enrollmentMode
string
Enrollment mode (informational)
​
courseTitle
string
Course title (used for payment description)
​
referrer
string
Redirect context: “course-detail” or “courses-list”

​
Response

Response varies by payment gateway:

​
Stripe Response

​
checkoutUrl
string
Stripe Checkout session URL
​
gateway
string
“stripe”
​
amount
number
Payment amount in user’s currency
​
currency
string
User’s preferred currency
​
originalAmount
number
Original course price in platform currency
​
originalCurrency
string
Platform’s default currency

​
Flutterwave Response

​
paymentLink
string
Flutterwave payment page URL
​
gateway
string
“flutterwave”
​
txRef
string
Transaction reference ID
​
amount
number
Payment amount
​
currency
string
Payment currency

​
Example Request

curl -X POST https://your-domain.com/api/payments/create-intent \
  -H "Content-Type: application/json" \
  -d '{
    "courseId": 42,
    "enrollmentMode": "paid",
    "courseTitle": "Advanced JavaScript",
    "referrer": "course-detail"
  }'

​
Example Response (Stripe)

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
  "gateway": "stripe",
  "amount": 99.99,
  "currency": "USD",
  "originalAmount": 99.99,
  "originalCurrency": "USD"
}

​
Example Response (Flutterwave)

{
  "paymentLink": "https://checkout.flutterwave.com/v3/...",
  "gateway": "flutterwave",
  "txRef": "tx_1234567890_uuid_42",
  "amount": 41650.00,
  "currency": "NGN",
  "originalAmount": 99.99,
  "originalCurrency": "USD"
}

​
Record Payment

Records a completed payment in the database. Called after successful payment via gateway callback.

​
Request Body

​
courseId
number
required
Course ID
​
amount
number
required
Payment amount
​
gateway
string
required
Payment gateway: “stripe” or “flutterwave”

​
Response

​
success
boolean
Payment recording status
​
payment
object
Created payment record

​
Example Request

curl -X POST https://your-domain.com/api/payments/record-payment \
  -H "Content-Type: application/json" \
  -d '{
    "courseId": 42,
    "amount": 99.99,
    "gateway": "stripe"
  }'

​
Payment Gateway Selection

The API automatically selects the payment gateway based on the user’s currency preference:
CurrencyGatewayNotes
NGN (Nigerian Naira)FlutterwaveOptimized for African markets
All others (USD, EUR, etc.)StripeGlobal payment processing

​
Currency Conversion

Course prices are stored in the platform’s default currency (configurable in platform_settings). The API:
  1. Fetches the course price in platform currency
  2. Gets the user’s preferred currency from their profile
  3. Converts the amount using real-time exchange rates
  4. Creates a payment session in the user’s currency
  5. Stores both original and payment amounts for reporting

​
Currency Fields

  • original_amount: Course price in platform currency
  • original_currency: Platform’s default currency (e.g., “USD”)
  • payment_amount: Amount charged to user (after conversion)
  • payment_currency: User’s payment currency
  • exchange_rate: Rate used for conversion (amountUSD / originalAmount)

​
Payment Callbacks

​
Stripe Callback

Handles Stripe Checkout session completion. Query Parameters:
  • success: “true” for successful payment
  • courseId: Course ID
  • referrer: Redirect context

​
Flutterwave Callback

Handles Flutterwave payment completion. Query Parameters:
  • status: Payment status
  • tx_ref: Transaction reference
  • transaction_id: Flutterwave transaction ID
  • courseId: Course ID
  • referrer: Redirect context

​
Payment Webhooks

​
Stripe Webhook

Receives and processes Stripe webhook events for payment confirmations and updates.

​
Payment Flow

  1. User initiates payment: POST to /api/payments/create-intent
  2. API creates payment session:
    • Converts price to user’s currency
    • Selects appropriate gateway (Stripe or Flutterwave)
    • Returns checkout/payment URL
  3. User completes payment: On gateway-hosted page
  4. Gateway redirects to callback: /api/payments/callback/{gateway}
  5. Callback records payment: Calls /api/payments/record-payment
  6. User enrolled automatically: Callback creates enrollment record
  7. User redirected: To course page or courses list

​
Error Codes

Status CodeDescription
200Success
400Bad Request - Invalid course ID or parameters
401Unauthorized - Authentication required
404Not Found - Course not found
500Internal Server Error - Payment gateway error