Platform Quickstart

This walkthrough takes a tenant API key from zero to a payout made on behalf of a customer. Run it in your sandbox environment, where you can self-approve accounts and simulate deposits instead of waiting on real compliance review and real money.

Prerequisites

Your business activated as a white-label tenant (contact support if /accounts returns 403)
A sandbox API key with at least one allowlisted IP — required before the key can reach Step 6

Step 1: Create a customer account

curl -X POST "https://api.rolla.xyz/api/v1/external/accounts" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "business",
    "name": "Beta Logistics LLC",
    "email": "ops@betalogistics.com"
  }'

{
  "status": 201,
  "message": "Account created successfully",
  "success": true,
  "data": {
    "account": {
      "id": "eec3cbed-79d8-4370-87a0-b6be9e287337",
      "name": "Beta Logistics LLC",
      "email": "ops@betalogistics.com",
      "status": "created",
      "entityType": "business"
    },
    "applicationId": "fbb45236-881a-4c58-8954-22759499eab4",
    "applicationStatus": "draft"
  }
}

data.account.id is the account id — there is no accountId field. Save it: it’s the value you’ll put in X-Account-Id for the rest of this guide, and in the {accountId} path segments below. email is required and must be unique across your accounts (409 with code: "ACCOUNT_EMAIL_EXISTS" otherwise).

Step 2: Complete and submit the application

A real onboarding fills in business details, uploads documents, and verifies related persons — the onboarding guide covers every step. The short version:

# What's still missing?
curl "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/requirements" \
  -H "X-API-Key: your_tenant_api_key"

# ...fill details, upload documents, complete KYC...

# Then submit
curl -X POST "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/submit" \
  -H "X-API-Key: your_tenant_api_key"

Get Requirements reports readyToSubmit: true once everything is in place.

Step 3: Approve it (sandbox only)

In production, submitted applications are reviewed by Rolla’s compliance team. In sandbox, approve it yourself — note the staging host: this endpoint does not exist in production and returns 404 there.

curl -X POST "https://api-staging.rolla.xyz/api/v1/external/accounts/{accountId}/approve" \
  -H "X-API-Key: your_tenant_api_key"

This runs the real approval path — wallets are provisioned and the account.approved webhook fires, exactly like a live approval.

Step 4: Issue a deposit account

curl -X POST "https://api.rolla.xyz/api/v1/external/accounts/{accountId}/bank-accounts" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "NGN" }'

NGN accounts are issued instantly; USD accounts go through provider review first (202). If the provider needs details the application didn’t capture, Get Issuance Requirements lists what to pass in accountData. Share the returned account number with your customer — or fetch complete payment details any time with Funding Instructions.

Step 5: Fund it (simulated)

Simulate an NGN deposit into the account you just issued — note the staging host (this endpoint is sandbox-only too), the X-Account-Id header scoping the request to your customer, and that simulate endpoints take the amount in major units as a string:

curl -X POST "https://api-staging.rolla.xyz/api/v1/external/wallet/virtual-accounts/simulate-deposit" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "X-Account-Id: {accountId}" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "ACCOUNT_NUMBER_FROM_STEP_4",
    "amount": "5000",
    "sender_name": "Test Sender"
  }'

For USD, issue a USD account and use Simulate an Account Deposit instead. Either way the simulated deposit fires the same transaction.* webhooks a real one would — and as the tenant, you receive events for all your customers’ transactions.

Step 6: Pay out on the customer’s behalf

Now the key move: the same Withdraw Funds endpoint every Business user calls, scoped to your customer with X-Account-Id. The payout comes out of their wallet:

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
  -H "X-API-Key: your_tenant_api_key" \
  -H "X-Account-Id: {accountId}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "NGN",
    "inlineBeneficiary": {
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "bank_code": "000014"
    },
    "description": "Customer payout",
    "metadata": { "your_payout_id": "cust-A-payout-001" }
  }'

100000 kobo = ₦1,000, in minor units as everywhere, and description is required. The fee comes out of the customer’s wallet on top of amount by default, so the beneficiary receives the full ₦1,000. There’s no externalReference here on purpose: NGN payouts always get a Rolla-generated reference (NG-XXXXXXXX), so tie the payout to your own record with metadata, which is returned verbatim on the transaction and on every webhook for it. The same header works on any endpoint — check the customer’s balance with GET /wallet/wallets + X-Account-Id, list their transactions, manage their beneficiaries.

Step 7: Reconcile

One call returns every transaction across your whole tenancy, each row naming its account:

curl "https://api.rolla.xyz/api/v1/external/accounts/transactions?page=1&pageSize=50" \
  -H "X-API-Key: your_tenant_api_key"

Add format=csv for a file. See List Transactions Across Accounts.

Next steps

Onboard your customers

The full production onboarding journey — details, documents, related persons, KYC options.

Operate customer accounts

Everything about X-Account-Id scoping, funding, payouts, and reconciliation.

Webhooks

Account lifecycle and transaction events for your whole tenancy.

Account Onboarding reference

Every /accounts endpoint, field by field.

Banking For Your Customers

Guides

Platform Quickstart

Prerequisites

Step 1: Create a customer account

Step 2: Complete and submit the application

Step 3: Approve it (sandbox only)

Step 4: Issue a deposit account

Step 5: Fund it (simulated)

Step 6: Pay out on the customer’s behalf

Step 7: Reconcile

Next steps

Onboard your customers

Operate customer accounts

Webhooks

Account Onboarding reference

​Prerequisites

​Step 1: Create a customer account

​Step 2: Complete and submit the application

​Step 3: Approve it (sandbox only)

​Step 4: Issue a deposit account

​Step 5: Fund it (simulated)

​Step 6: Pay out on the customer’s behalf

​Step 7: Reconcile

​Next steps

Onboard your customers

Operate customer accounts

Webhooks

Account Onboarding reference

Prerequisites

Step 1: Create a customer account

Step 2: Complete and submit the application

Step 3: Approve it (sandbox only)

Step 4: Issue a deposit account

Step 5: Fund it (simulated)

Step 6: Pay out on the customer’s behalf

Step 7: Reconcile

Next steps