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):

Example response for GET /merchants/{id}

{
  "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):

Example response for GET /merchants/{id}/mrr

{
  "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):

Example response for GET /merchants/{id}/arr

{
  "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):

Example response for GET /merchants/{id}/balance

{
  "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.

Payment providers Customers