Payment API

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

number

required

Course ID to purchase

string

Enrollment mode (informational)

string

Course title (used for payment description)

string

Redirect context: “course-detail” or “courses-list”

Response

Response varies by payment gateway:

Stripe Response

string

Stripe Checkout session URL

string

“stripe”

number

Payment amount in user’s currency

string

User’s preferred currency

number

Original course price in platform currency

string

Platform’s default currency

Flutterwave Response

string

Flutterwave payment page URL

string

“flutterwave”

string

Transaction reference ID

number

Payment amount

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

number

required

Course ID

number

required

Payment amount

string

required

Payment gateway: “stripe” or “flutterwave”

Response

boolean

Payment recording status

object

Created payment record

Show Payment Object

number

Payment ID

string

User UUID

number

Course ID

number

Course price in platform currency

string

Platform currency

number

Amount charged to user

string

User’s payment currency

number

Exchange rate applied

string

Payment gateway used

string

Payment status (“completed”)

string

Unique transaction identifier

string

Completion timestamp

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:

Currency	Gateway	Notes
NGN (Nigerian Naira)	Flutterwave	Optimized for African markets
All others (USD, EUR, etc.)	Stripe	Global payment processing

Currency Conversion

Course prices are stored in the platform’s default currency (configurable in platform_settings). The API:

Fetches the course price in platform currency
Gets the user’s preferred currency from their profile
Converts the amount using real-time exchange rates
Creates a payment session in the user’s currency
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

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

Error Codes

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

Overview

Resources

Create Payment Intent

Request Body

Response

Stripe Response

Flutterwave Response

Example Request

Example Response (Stripe)

Example Response (Flutterwave)

Record Payment

Request Body

Response

Example Request

Payment Gateway Selection

Currency Conversion

Currency Fields

Payment Callbacks

Stripe Callback

Flutterwave Callback

Payment Webhooks

Stripe Webhook

Payment Flow

Error Codes

​Create Payment Intent

​Request Body

​Response

​Stripe Response

​Flutterwave Response

​Example Request

​Example Response (Stripe)

​Example Response (Flutterwave)

​Record Payment

​Request Body

​Response

​Example Request

​Payment Gateway Selection

​Currency Conversion

​Currency Fields

​Payment Callbacks

​Stripe Callback

​Flutterwave Callback

​Payment Webhooks

​Stripe Webhook

​Payment Flow

​Error Codes

Create Payment Intent

Request Body

Response

Stripe Response

Flutterwave Response

Example Request

Example Response (Stripe)

Example Response (Flutterwave)

Record Payment

Request Body

Response

Example Request

Payment Gateway Selection

Currency Conversion

Currency Fields

Payment Callbacks

Stripe Callback

Flutterwave Callback

Payment Webhooks

Stripe Webhook

Payment Flow

Error Codes