Skip to main content
Rolla’s API is a REST API: JSON in, JSON out, predictable resource-based paths. This page covers the conventions every endpoint shares. Base URL: https://api.rolla.xyz/api/v1/external

​
Authentication

Every request must carry your API key in the X-API-Key header:
Keys are created in the Rolla Dashboard under Settings → API Keys. A key needs at least one allowlisted IP address before it can send payouts or transfers, and once a key has an allowlist it is enforced across the board, not just on the money-moving endpoints. See Authentication for key management and security guidance.
Keep your API key secure. Do not expose it in client-side code or public repositories.

​
Acting on a tenant account (X-Account-Id)

If your business uses the Platform product (a white-label tenant), a single API key can act on any account inside your tenancy — your own account, or any account you’ve onboarded under it. Add the optional X-Account-Id header naming the target account, and the entire request is scoped to that account: onboarding, documents, wallets, funding instructions, payouts, beneficiaries — everything runs as that account.
Accounts you create with a tenant API key (via POST /accounts) are automatically added to your tenancy, so you can immediately address them with X-Account-Id afterwards. Accounts that onboard themselves through your white-label app are part of your tenancy too.

​
Response format

Successful responses open with status, message and success: true, in that order, and most then nest the payload under data — check the endpoint’s own page, since a few return it at the top level instead. Errors carry the HTTP code and a message, and never a success field:
status is the HTTP status code as a number in both cases. Some errors add a machine-readable code — the full taxonomy is in Errors.

​
Amounts

Unless a route documents otherwise, numeric amount fields use each currency’s smallest unit in requests and responses — NGN kobo, USD cents (100 = $1.00), etc. Fractional amounts are rejected. See Amounts & Currencies.

​
Pagination

List endpoints that paginate take page and pageSize (max 100 on most endpoints). The counters come back in one of two shapes — flat inside data as totalCount/page/pageSize/totalPages, or nested under a pagination object that names the total total. Only the two account listings also return hasMore. See Pagination.

​
Idempotency

There is no global idempotency header; money-moving requests should follow the lookup-before-retry pattern with your own externalReference — except on NGN and mobile money payouts, where Rolla mints the reference instead. See Idempotency & Retries.

​
Webhooks

Instead of polling for status changes, register a webhook endpoint and receive signed events for every deposit, payout, fee, and account update.