Merchants
The Merchants API allows you to retrieve information about merchant accounts, including details, recurring revenue metrics, and balances.
Authentication
Requests require authentication using your API key in the `X-API-Key` header. See the Authentication guide.
Endpoints
Get merchant details
Retrieves detailed information about a specific merchant account.
Endpoint: `GET /merchants/{id}`
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
`id` | `string` | Yes | The unique identifier of the merchant. |
Example response (200 OK):
{
"data": {
"merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
"name": "Test Merchant",
"email": "merchant@example.com",
"phone_number": "+123456789",
"country": "SN",
"mrr": 50000, // In smallest currency unit
"arr": 600000, // In smallest currency unit
"merchant_lifetime_value": 1200000, // In smallest currency unit
"retry_payment_every": 3,
"total_retries": 5,
"metadata": {
"industry": "e-commerce"
},
"created_at": "2023-01-15T10:30:00Z",
"updated_at": "2023-02-20T14:45:00Z"
}
}(See Data Models for property descriptions)
Possible error responses:
| Status Code | Error Code | Description |
|---|---|---|
`401` | `UNAUTHORIZED` | Authentication failed or API key is invalid. |
`404` | `MERCHANT_NOT_FOUND` | No merchant found with the provided ID. |
`500` | `DATABASE_ERROR` | Error retrieving merchant details. |
`500` | `INTERNAL_ERROR` | Internal server error. |
Get merchant monthly recurring revenue (MRR)
Retrieves the current MRR for a merchant.
Endpoint: `GET /merchants/{id}/mrr`
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
`id` | `string` | Yes | The unique identifier of the merchant. |
Example response (200 OK):
{
"data": {
"merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
"mrr": 50000, // In smallest currency unit
"currency_code": "XOF",
"as_of_date": "2023-04-01T00:00:00Z"
}
}Possible error responses:
| Status Code | Error Code | Description |
|---|---|---|
`401` | `UNAUTHORIZED` | Authentication failed or API key is invalid. |
`404` | `MERCHANT_NOT_FOUND` | No merchant found with the provided ID. |
`404` | `NOT_FOUND` | No MRR data found for the merchant. |
`500` | `DATABASE_ERROR` | Error retrieving merchant MRR. |
`500` | `INTERNAL_ERROR` | Internal server error. |
Get merchant annual recurring revenue (ARR)
Retrieves the current ARR for a merchant.
Endpoint: `GET /merchants/{id}/arr`
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
`id` | `string` | Yes | The unique identifier of the merchant. |
Example response (200 OK):
{
"data": {
"merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
"arr": 600000, // In smallest currency unit
"currency_code": "XOF",
"as_of_date": "2023-04-01T00:00:00Z"
}
}Possible error responses:
| Status Code | Error Code | Description |
|---|---|---|
`401` | `UNAUTHORIZED` | Authentication failed or API key is invalid. |
`404` | `MERCHANT_NOT_FOUND` | No merchant found with the provided ID. |
`404` | `NOT_FOUND` | No ARR data found for the merchant. |
`500` | `DATABASE_ERROR` | Error retrieving merchant ARR. |
`500` | `INTERNAL_ERROR` | Internal server error. |
Get merchant account balance
Retrieves the current account balance for a merchant in a specific currency.
Endpoint: `GET /merchants/{id}/balance`
Path parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
`id` | `string` | Yes | The unique identifier of the merchant. |
Query parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
`currency_code` | `string` | Yes | Currency code for the balance (e.g., `XOF`, `USD`). |
Example response (200 OK):
{
"data": {
"merchant_id": "904d003c-3736-41d4-90a5-9de74d404fd7",
"currency_code": "XOF",
"balance": 250000, // In smallest currency unit
"as_of_date": "2023-04-01T12:30:45Z"
}
}Possible error responses:
| Status Code | Error Code | Description |
|---|---|---|
`400` | `MISSING_PARAMETER` | The `currency_code` query parameter is missing. |
`401` | `UNAUTHORIZED` | Authentication failed or API key is invalid. |
`500` | `DATABASE_ERROR` | Error retrieving merchant balance. |
`500` | `INTERNAL_ERROR` | Internal server error. |
Implementation notes
- All monetary values (
`mrr`,`arr`,`merchant_lifetime_value`,`balance`) are returned in the smallest currency unit (e.g., cents for USD, XOF represents the base unit directly). - Dates and times are returned in ISO 8601 format (
`YYYY-MM-DDTHH:mm:ssZ`). - See the Errors guide for general error handling information.
Last updated on
Customers
The Customers API allows you to create, retrieve, update, list, and delete customer profiles associated with your merchant account.
Providers
The Providers API allows merchants to retrieve information about available payment providers connected to their account. This information can be used to determine which payment methods to offer to customers.