Getting Started

This documentation covers the APIs available for client integration.

Base URL

All API requests are made to your assigned base URL, provided during onboarding.

Webhook Versions

The API endpoints (checkout, direct payment, payout, check status) do not have versions. Versioning applies only to webhooks:

New integrations should use Webhook V2. If you are on V1, see the V1 → V2 Migration Guide.

Parse responses and webhooks in a non-strict way, so a newly added field doesn't cause an error. Breaking changes are announced in advance. See the Changelog for changes to the API.

Authentication

All requests require three headers. See Authentication for the full reference and Signature Generation for how to generate the X-SIGNATURE header.

Error Responses

Use the HTTP status code as the success signal. Any non-2xx response is a failure. Do not rely on the shape of the body to detect a failure: error bodies have different shapes depending on where the request was rejected (see below).

One exception: the payout endpoints (Inquiry, Transfer Fund, Check Balance) can return HTTP 200 with "status": false. On these endpoints, check status (and data.status for inquiries) even when the HTTP status is 200.

Common HTTP status codes:

Error body shapes

The body of an error response has one of the following shapes.

Authentication header errors (400) — missing or invalid X-PARTNER-ID, X-TIMESTAMP or X-SIGNATURE. See Authentication for the full list of messages.

{
    "error": {
        "code": 40001001,
        "message": "Invalid X-SIGNATURE value"
    }
}

IP whitelist errors (400 or 403) — see IP Whitelisting below.

{
    "error": "Your IP address is not API whitelisted.",
    "ip": "203.0.113.42"
}

Checkout validation errors (422) — only Checkout uses this shape. errors lists the messages per field.

{
    "success": false,
    "message": "Validation errors occurred.",
    "errors": {
        "amount": ["The amount field is required."]
    }
}

Direct Payment validation errors (422) — the Generate Direct Payment endpoints use this shape. message summarizes the errors and errors lists the messages per field.

{
    "status": false,
    "message": "The amount field is required.",
    "errors": {
        "amount": ["The amount field is required."]
    }
}

Endpoint errors (4xx / 5xx, and 200 on payout endpoints) — all other failures, including validation failures on endpoints other than Checkout and Direct Payment.

{
    "status": false,
    "data": null,
    "message": "Error description"
}

Some endpoints omit data, and some add a machine-readable code (for example the payout endpoints). See each endpoint's page for its exact responses.

Don't build logic on message text; it can change. Where a page lists a code, use the code.

IP Whitelisting

In production, API requests are restricted to whitelisted IP addresses. Requests from non-whitelisted IPs will receive a 403 response:

{
    "error": "Your IP address is not API whitelisted.",
    "ip": "203.0.113.42"
}

ip is the address the API saw for your request. Compare it with the addresses you registered.

The IP check runs before signature verification. In production, a request without the X-PARTNER-ID header is rejected at this step with a 400 response:

{
    "error": "Missing X-PARTNER-ID header."
}

Register your server IP addresses during onboarding or contact support to update your whitelist. This restriction does not apply in the sandbox environment, or when IP whitelisting is disabled for your account.

Rate Limits

API requests are rate-limited at two layers. Both apply at the same time, and whichever limit you reach first returns 429 Too Many Requests.

Rate-limit headers. Responses from rate-limited endpoints include:

When both layers apply to an endpoint, the headers describe the layer with the fewest requests remaining.

429 response body. The body depends on which layer rejected the request:

{
    "message": "Too many requests. Please slow down."
}

{
    "status": false,
    "message": "Too many requests."
}

The first body is the per-IP limit and the second is the per-X-PARTNER-ID limit. On a 429, wait for the number of seconds in Retry-After before retrying, and do not retry immediately in a loop.

Testing & Sandbox

Use the sandbox environment provided during onboarding to test your integration before going live.

Sandbox behavior:

• Payout testing: Use account number 00000000 to simulate a successful disbursement callback. All other account numbers will result in a failed callback.
• Payment testing: Create payments normally — the sandbox processes them without real fund movement.
• Webhooks: Sandbox webhooks are sent to your registered endpoints, identical in structure to production webhooks.