# Integration guide

Here's a typical flow of the order using our API:

1. Call [Get available currencies](/server-to-server/api-endpoints/get-available-currencies.md) to list supported currencies, channels, and pairs.
2. Call [Get order limits](/server-to-server/api-endpoints/get-order-limits.md) for the selected deposit/payout configuration.
3. Call [Get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) to determine if KYC is required for the intended amounts and currency types.
   * If KYC is required, call [Submit user KYC](https://github.com/fonbnk/docs/blob/main/api-v2.md#submit-user-kyc) and wait until the status is approved by polling the [get user KYC state](/server-to-server/api-endpoints/get-user-kyc-state.md) endpoint.
   * See KYC requirements for a detailed checklist of the decision flow.
4. Call [Create a quote](/server-to-server/api-endpoints/create-quote.md) with the deposit/payout configuration.
   * Use deposit.fieldsToCreateOrder and payout.fieldsToCreateOrder to collect all required fields from the user.
5. Call [Create an order](/server-to-server/api-endpoints/create-order.md) with quoteId and the collected fields.
6. The user completes the deposit per the transfer instructions on the order.
7. If the transfer requires an intermediate action (stk\_push / otp\_stk\_push), call [Trigger intermediate action](https://github.com/fonbnk/docs/blob/main/api-v2.md#trigger-intermediate-action).
8. Call [Confirm order](/server-to-server/api-endpoints/confirm-order.md).
9. Use [Get order](/server-to-server/api-endpoints/get-order.md) to poll for status and details at any time.

{% @mermaid/diagram content="sequenceDiagram
autonumber
actor User as User
participant Merchant as Merchant System
participant Fonbnk as Fonbnk API
participant Agent as Fonbnk Agent<br/>(Liquidity Provider)

```
Note over User, Merchant: Phase 1: Initialization & Discovery

User->>Merchant: Opens "Buy Crypto" Interface

Merchant->>Fonbnk: Call "Get available currencies"
Fonbnk-->>Merchant: Returns supported Pairs<br/>(e.g. NGN, KES, POLYGON_USDT)

Merchant-->>User: Populates Dropdowns

User->>Merchant: Selects Deposit: NGN (Bank) -> Payout: POLYGON_USDT

Merchant->>Fonbnk: Call "Get order limits"
Fonbnk-->>Merchant: Returns Min/Max Limits for NGN -> POLYGON_USDT

Note over User, Merchant: Phase 2: Input & Validation

User->>Merchant: Enters Amount (e.g. 50,000 NGN)

Merchant->>Fonbnk: Call "Get user KYC state"
Fonbnk-->>Merchant: Returns User's Current Tier

Note right of Merchant: Checks if Amount > Tier Limit

opt Upgrade Required
    Merchant-->>User: Prompt for ID Documents
    User->>Merchant: Uploads ID
    Merchant->>Fonbnk: Call "Submit user KYC"
    loop Verification
        Merchant->>Fonbnk: Call "Get user KYC state"
        Fonbnk-->>Merchant: Status: APPROVED
    end
end

Note over User, Merchant: Phase 3: Quote & Data Collection

Merchant->>Fonbnk: Call "Create a quote"
Note right of Merchant: Request: NGN -> POLYGON_USDT
Fonbnk-->>Merchant: Returns Quote & **fieldsToCreateOrder**
Note left of Fonbnk: Requires: "blockchainWalletAddress"

Merchant-->>User: Displays Price + Requests Wallet Address
User->>Merchant: Confirms Price & Enters Wallet Address

Note over User, Agent: Phase 4: Order & Payment

Merchant->>Fonbnk: Call "Create an order"
Fonbnk-->>Merchant: Returns Order (Status: deposit_awaiting)
Note left of Fonbnk: Includes **transferInstructions**<br/>(Agent Bank Details & Ref Code)

Merchant-->>User: Displays Payment Instructions
Note right of User: "Send 50,000 NGN to Agent.<br/>Use Ref Code: ORDER-123"

User->>Agent: Transfers NGN (Manual Bank Transfer)
Note right of User: **MUST** include Ref Code

Merchant->>Fonbnk: Call "Confirm order"
Fonbnk-->>Merchant: Returns updated Order

Fonbnk->>Agent: Verify incoming transaction
Agent-->>Fonbnk: Confirms Funds Received

Note over Merchant, Fonbnk: Phase 5: Completion

Fonbnk-)Merchant: POST Webhook (order-status-change)
Note right of Fonbnk: Status: payout_successful

Merchant->>User: Notify "USDT Sent!"" %}
```


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.