> 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/api-endpoints.md).

# API Endpoints

Every endpoint of the Fonbnk Merchant API, grouped by what it does.

Every endpoint lives on the hosts listed in [Servers](/server-to-server/servers.md) and needs the signed headers described in [Signing requests](/server-to-server/signing-requests.md).

### Discovery

Call these before you show a price to a user. They tell you what you can sell and inside which bounds.

| Endpoint                                                                          | Method | What it returns                                                                                 |
| --------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| [/api/v2/currencies](/server-to-server/api-endpoints/get-available-currencies.md) | GET    | Every currency you can use, its payment channels, and which currency types it pairs with.       |
| [/api/v2/order-limits](/server-to-server/api-endpoints/get-order-limits.md)       | GET    | The min and max order amount for one deposit/payout pair.                                       |
| [/api/v2/limits](broken://pages/ZVgb29BOl4YDGtkn1scf)                             | GET    | The platform and per-user volume rules behind those amounts, with how much is already consumed. |

### Orders

| Endpoint                                                                                                  | Method | What it does                                                             |
| --------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------ |
| [/api/v2/quote](/server-to-server/api-endpoints/create-quote.md)                                          | POST   | Locks a price and returns the fields you must collect from the user.     |
| [/api/v2/order](/server-to-server/api-endpoints/create-order.md)                                          | POST   | Creates the order and returns its transfer instructions.                 |
| [/api/v2/order/intermediate-action](/server-to-server/api-endpoints/trigger-order-intermediate-action.md) | POST   | Starts or retries an STK push, or submits the OTP code that unlocks one. |
| [/api/v2/order/confirm](/server-to-server/api-endpoints/confirm-order.md)                                 | POST   | Tells us the user has paid.                                              |
| [/api/v2/order/cancel](/server-to-server/api-endpoints/cancel-order.md)                                   | POST   | Cancels an order that has not been paid yet.                             |
| [/api/v2/order](/server-to-server/api-endpoints/get-order.md)                                             | GET    | Reads one order by its ID or by your own reference.                      |
| [/api/v2/orders](/server-to-server/api-endpoints/get-orders.md)                                           | GET    | Lists your orders, with cursor pagination and filters.                   |

### KYC

| Endpoint                                                                  | Method | What it does                                                                                  |
| ------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------- |
| [/api/v2/user/kyc](/server-to-server/api-endpoints/get-user-kyc-state.md) | GET    | Returns the user's KYC state, the rules for their country, and the documents they can submit. |
| [/api/v2/user/kyc](/server-to-server/api-endpoints/submit-user-kyc.md)    | POST   | Submits a KYC document for a user.                                                            |

The decision flow that ties those two together is on [KYC flow](/server-to-server/kyc-flow.md).

### Merchant balance

| Endpoint                                                                                                                         | Method | What it does                                                     |
| -------------------------------------------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------------------------- |
| [/api/v2/merchant-balance](/server-to-server/api-endpoints/merchant-balance/get-merchant-balances.md)                            | GET    | Your current balance per currency.                               |
| [/api/v2/merchant-balance/deposit/options](/server-to-server/api-endpoints/merchant-balance/get-crypto-deposit-options.md)       | GET    | The `(network, asset)` pairs you can top up with.                |
| [/api/v2/merchant-balance/deposit/limits](/server-to-server/api-endpoints/merchant-balance/get-crypto-deposit-limits.md)         | GET    | The min and max for one deposit pair.                            |
| [/api/v2/merchant-balance/deposit](/server-to-server/api-endpoints/merchant-balance/create-crypto-deposit.md)                    | POST   | Creates a crypto deposit and returns the address to send to.     |
| [/api/v2/merchant-balance/deposit/confirm](/server-to-server/api-endpoints/merchant-balance/confirm-crypto-deposit.md)           | POST   | Submits the transaction hash of your deposit.                    |
| [/api/v2/merchant-balance/deposit/cancel](/server-to-server/api-endpoints/merchant-balance/cancel-crypto-deposit.md)             | POST   | Cancels a deposit that is still awaiting funds.                  |
| [/api/v2/merchant-balance/deposit](/server-to-server/api-endpoints/merchant-balance/get-crypto-deposit.md)                       | GET    | Reads one deposit.                                               |
| [/api/v2/merchant-balance/deposits](/server-to-server/api-endpoints/merchant-balance/get-crypto-deposits.md)                     | GET    | Lists your deposits.                                             |
| [/api/v2/merchant-balance/withdrawal/options](/server-to-server/api-endpoints/merchant-balance/get-crypto-withdrawal-options.md) | GET    | The `(network, asset)` pairs you can withdraw to.                |
| [/api/v2/merchant-balance/withdrawal/limits](/server-to-server/api-endpoints/merchant-balance/get-crypto-withdrawal-limits.md)   | GET    | The min and max for one withdrawal pair.                         |
| [/api/v2/merchant-balance/withdrawal](/server-to-server/api-endpoints/merchant-balance/create-crypto-withdrawal.md)              | POST   | Creates a withdrawal. Deducts the amount and waits for approval. |
| [/api/v2/merchant-balance/withdrawal/cancel](/server-to-server/api-endpoints/merchant-balance/cancel-crypto-withdrawal.md)       | POST   | Cancels a withdrawal that is still awaiting approval.            |
| [/api/v2/merchant-balance/withdrawal](/server-to-server/api-endpoints/merchant-balance/get-crypto-withdrawal.md)                 | GET    | Reads one withdrawal.                                            |
| [/api/v2/merchant-balance/withdrawals](/server-to-server/api-endpoints/merchant-balance/get-crypto-withdrawals.md)               | GET    | Lists your withdrawals.                                          |

These are gated per account. See [Merchant balance](/server-to-server/api-endpoints/merchant-balance.md) for the lifecycle and the error codes.

### Pay Widget helpers

| Endpoint                                                                            | Method | What it does                                                          |
| ----------------------------------------------------------------------------------- | ------ | --------------------------------------------------------------------- |
| [/api/v2/user/tokens](/server-to-server/api-endpoints/generate-user-auth-tokens.md) | POST   | Logs a user in on your behalf so the widget can skip its auth screen. |

{% hint style="info" %}
The shared enums and object types every endpoint here refers to live on one page: [Types](/server-to-server/types.md).
{% endhint %}


---

# 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/api-endpoints.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.