Create a browser pay link

Headers

Idempotency-Key required string

Required for money-moving and session/mandate creates; replays must use the same body.

Body parameters

amount_mode optional string

fixed (default) requires amount at create time. open lets the customer enter the amount on the hosted pay page. open is not available while the merchant is in Testing mode (use fixed at or below the country testing max, or Go Live). See testing mode.

One of fixed open

amount optional string

Required when amount_mode is fixed (or omitted). Omit for open. In Testing mode, fixed amounts must be at or below the country testing max.

currency required string

merchant_reference required string

payment_rail optional string, nullable

mobile_money locks the session to mobile money; mobile is then required at create unless pre-filled later on the hosted page. When the key is omitted, the session stores null and the customer chooses the rail on /pay/{id} (portal pay links send explicit JSON null). card is accepted only when MojoPay has enabled card checkout for your merchant; otherwise it is rejected with 400 invalid_parameter. bank_transfer is accepted only when bank transfer checkout is enabled for your merchant; the hosted page issues a dynamic virtual account.

One of mobile_money card bank_transfer

mobile optional string

Required when payment_rail is mobile_money at create time. Omit when the customer will enter wallet details on the hosted page.

provider optional string

Mobile money provider code when required for the chosen rail (metadata mobile_providers).

success_url required string (uri)

cancel_url required string (uri)

description optional string

Webhook events

checkout_session.processing checkout_session.succeeded checkout_session.failed

{
    "amount_mode": "fixed",
    "currency": "GHS",
    "amount": "1.00",
    "merchant_reference": "KLCTMXOAIS",
    "success_url": "https://merchant.example.com/pay/return?ref=KLCTMXOAIS",
    "cancel_url": "https://merchant.example.com/pay/cancel?ref=KLCTMXOAIS"
}

{
    "amount_mode": "fixed",
    "currency": "GHS",
    "amount": "1.00",
    "merchant_reference": "KLCTMXOAIS",
    "description": "Goods payment",
    "success_url": "https://merchant.example.com/pay/return?ref=KLCTMXOAIS",
    "cancel_url": "https://merchant.example.com/pay/cancel?ref=KLCTMXOAIS",
    "mobile": "233555515326",
    "payment_rail": "mobile_money",
    "provider": "MTN"
}

{
    "amount_mode": "fixed",
    "currency": "GHS",
    "amount": "2.56",
    "merchant_reference": "SLUG-RANDOMTOKEN",
    "description": "Pay link",
    "success_url": "https://merchant.example.com/pay/ok",
    "cancel_url": "https://merchant.example.com/pay/cancel",
    "payment_rail": null,
    "mobile": null,
    "provider": null
}

{
    "amount_mode": "open",
    "currency": "GHS",
    "merchant_reference": "DONATION-2026-001",
    "description": "Pay what you want",
    "success_url": "https://merchant.example.com/pay/return",
    "cancel_url": "https://merchant.example.com/pay/cancel"
}

{
    "amount_mode": "fixed",
    "currency": "GHS",
    "amount": "1.00",
    "merchant_reference": "ORD-BT-LINK-001",
    "description": "Invoice bank transfer",
    "success_url": "https://merchant.example.com/pay/return",
    "cancel_url": "https://merchant.example.com/pay/cancel",
    "payment_rail": "bank_transfer"
}

curl -X POST "https://omni.mojo-pay.com/v1/checkout/sessions" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_mode": "fixed",
    "currency": "GHS",
    "amount": "1.00",
    "merchant_reference": "KLCTMXOAIS",
    "success_url": "https://merchant.example.com/pay/return?ref=KLCTMXOAIS",
    "cancel_url": "https://merchant.example.com/pay/cancel?ref=KLCTMXOAIS"
}'

{
    "id": "CS_4NQP81ABCDEF",
    "object": "checkout_session",
    "status": "processing",
    "url": "https://checkout.example.com/pay/CS_4NQP81ABCDEF",
    "expires_at": "2026-04-15T11:00:00Z"
}