> For the complete documentation index, see [llms.txt](https://docs.fonbnk.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fonbnk.com/server-to-server/integration-guide.md).

# 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](/server-to-server/api-endpoints/get-available-currencies.md) to list the currencies, channels and legal pairs.
2. Call [Get order limits](/server-to-server/api-endpoints/get-order-limits.md) for the deposit/payout pair the user picked. Use `step` and `supportsDecimals` to drive your amount input.
3. Call [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) — 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](/server-to-server/api-endpoints/submit-user-kyc.md) and wait for `passedKycType` to reach the tier.
   * The full decision flow, including the Nigerian BVN gate, is on [KYC flow](/server-to-server/kyc-flow.md).
4. Call [Create quote](/server-to-server/api-endpoints/create-quote.md) with the deposit/payout configuration.
   * Use `deposit.fieldsToCreateOrder` and `payout.fieldsToCreateOrder` to build your form and collect every required field.
5. Call [Create order](/server-to-server/api-endpoints/create-order.md) 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](/server-to-server/api-endpoints/trigger-order-intermediate-action.md).
   * On `redirect`, send the user to `transferInstructions.paymentUrl`.
   * On `manual`, show `transferDetails` and let them pay from their own app.
7. Call [Confirm order](/server-to-server/api-endpoints/confirm-order.md), including any `fieldsToConfirmOrder`.
8. Handle the `order-status-change` [webhook](/server-to-server/webhooks.md). Use [Get order](/server-to-server/api-endpoints/get-order.md) to read state at any point.

{% hint style="warning" %}
**Creating orders needs a capability on your account.** [Create order](/server-to-server/api-endpoints/create-order.md), [Confirm order](/server-to-server/api-endpoints/confirm-order.md), [Cancel order](/server-to-server/api-endpoints/cancel-order.md), [Trigger order intermediate action](/server-to-server/api-endpoints/trigger-order-intermediate-action.md) 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](/server-to-server/api-endpoints/create-quote.md) 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.
{% endhint %}

{% hint style="info" %}
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](broken://pages/ZVgb29BOl4YDGtkn1scf).
{% endhint %}

Worked end-to-end examples for each order shape are on [Flow examples](/server-to-server/integration-guide/flow-examples.md).

```mermaid
sequenceDiagram
  autonumber
  actor User
  participant Merchant as Merchant System
  participant Fonbnk as Fonbnk API
  participant Agent as Fonbnk Agent
  Note over User,Merchant: Phase 1 - discovery
  User->>Merchant: Opens "Buy Crypto"
  Merchant->>Fonbnk: Get available currencies
  Fonbnk-->>Merchant: Supported pairs (NGN, KES, POLYGON_USDT)
  Merchant-->>User: Populates dropdowns
  User->>Merchant: Selects NGN (bank) to POLYGON_USDT
  Merchant->>Fonbnk: Get order limits
  Fonbnk-->>Merchant: Min and max for that pair
  Note over User,Merchant: Phase 2 - KYC
  User->>Merchant: Enters amount (50000 NGN)
  Merchant->>Fonbnk: Get user KYC state with the amounts
  Fonbnk-->>Merchant: requiredKycType
  opt Upgrade required
    Merchant-->>User: Prompt for ID documents
    User->>Merchant: Uploads ID
    Merchant->>Fonbnk: Submit user KYC
    loop Until passedKycType reaches the tier
      Merchant->>Fonbnk: Get user KYC state
      Fonbnk-->>Merchant: passedKycType
    end
  end
  Note over User,Merchant: Phase 3 - quote
  Merchant->>Fonbnk: Create quote
  Fonbnk-->>Merchant: Quote plus fieldsToCreateOrder
  Merchant-->>User: Shows price, asks for wallet address
  User->>Merchant: Confirms and enters address
  Note over User,Agent: Phase 4 - order and payment
  Merchant->>Fonbnk: Create order
  Fonbnk-->>Merchant: Order (deposit_awaiting) with transferInstructions
  Merchant-->>User: Shows payment instructions
  User->>Agent: Transfers NGN with the narration
  Merchant->>Fonbnk: Confirm order
  Fonbnk-->>Merchant: Updated order
  Fonbnk->>Agent: Verify incoming transaction
  Agent-->>Fonbnk: Funds received
  Note over Merchant,Fonbnk: Phase 5 - completion
  Fonbnk-)Merchant: POST webhook (payout_successful)
  Merchant->>User: Notify "USDT sent"
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fonbnk.com/server-to-server/integration-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.