Integration guide

The call sequence for a server-to-server order, start to finish.

A typical order takes six calls. The rest is watching it settle.

1. Call Get available currencies to list the currencies, channels and legal pairs.

2. Call Get order limits for the deposit/payout pair the user picked. Use step and supportsDecimals to drive your amount input.

3. Call Get user KYC state — with the order's USD amounts, so the answer accounts for this order and not just the user's history.

   • If requiredKycType exceeds passedKycType, call Submit user KYC and wait for passedKycType to reach the tier.

   • The full decision flow, including the Nigerian BVN gate, is on KYC flow.

4. Call Create quote with the deposit/payout configuration.

   • Use deposit.fieldsToCreateOrder and payout.fieldsToCreateOrder to build your form and collect every required field.

5. Call Create order with the quoteId and those fields.

6. Show order.deposit.transferInstructions and let the user pay.

   • On stk_push or otp_stk_push, drive the prompt with Trigger order intermediate action.

   • On redirect, send the user to transferInstructions.paymentUrl.

   • On manual, show transferDetails and let them pay from their own app.

7. Call Confirm order, including any fieldsToConfirmOrder.

8. Handle the order-status-change webhook. Use Get order to read state at any point.

Creating orders needs a capability on your account. Create order, Confirm order, Cancel order, Trigger order intermediate action and both KYC endpoints require the end-user-creation capability. Without it they return 403 with the message "This feature is not available for this merchant, please contact support". The discovery calls and Create quote are not gated, so you can get all the way to a price before you find out. Ask support to enable it before you start building.

Steps 1 and 2 tell you the bounds. If you also want the rules behind them — the per-user and platform volume caps and how much is already used — call Get limits.

Worked end-to-end examples for each order shape are on Flow examples.