Quickstart

This guide takes you from zero to a completed NGN payout on your own account. Along the way you’ll touch the four things almost every integration uses: wallets, virtual accounts, beneficiaries, and withdrawals.

Building banking for your own customers as an MSB or FI? Do this quickstart first — then the Platform Quickstart adds customer onboarding and per-customer scoping on top of everything here.

Prerequisites

A verified Rolla business account at app.rolla.xyz
Funds — or a plan to deposit some in Step 3

Step 1: Create an API key

Open the dashboard

Create a key

Click Create API Key, name it, and copy the key. It is shown once — store it securely.

Allowlist your server IPs

Add your server’s IP addresses to the key’s allowlist. A key needs at least one before it can call Withdraw Funds or Rolla Transfer, and once a key has an allowlist it is enforced on every endpoint, not just the money-moving ones.

Keep your API key secret. Never expose it in frontend code or public repositories.

Step 2: Make your first request

Send the key in the X-API-Key header. List your wallets to confirm everything works:

curl "https://api.rolla.xyz/api/v1/external/wallet/wallets" \
  -H "X-API-Key: your_api_key_here"

{
  "status": 200,
  "message": "Business wallets retrieved successfully",
  "success": true,
  "data": {
    "wallets": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "name": "NGN Wallet",
        "currency": "NGN",
        "balance": {
          "availableBalance": 950000,
          "postedBalance": 1000000,
          "pendingBalance": 50000,
          "lienAmount": 0
        }
      }
    ]
  }
}

Every successful response carries status (the HTTP code as a number), a human-readable message, and success: true, in that order. Most endpoints then nest the payload under data, but not all of them do — each endpoint’s reference page shows its exact shape. All amounts are in the currency’s smallest unit — kobo for NGN, cents for USD. See Amounts & Currencies.

Step 3: Fund your wallet

Generate a dynamic virtual account and transfer money to it from any Nigerian bank. Rolla credits your NGN wallet when the deposit lands:

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/dynamic" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500000 }'

The response contains a bank_name and account_number to pay into. 500000 kobo = ₦5,000.

Testing without real money? Sandbox environments expose Simulate a Deposit to credit your wallet instantly.

Step 4: Create a beneficiary

First resolve the recipient’s account so you know the name matches:

curl -X POST "https://api.rolla.xyz/api/v1/external/lookup" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "bankCode": "000014", "accountNumber": "0123456789" }'

Then save them as a beneficiary (get bank codes from List Banks):

curl -X POST "https://api.rolla.xyz/api/v1/external/beneficiaries" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "currency": "NGN",
    "label": "Test beneficiary",
    "account_name": "JOHN DOE",
    "account_number": "0123456789",
    "bank_name": "Access Bank",
    "bank_code": "000014"
  }'

Copy the id from the response.

In a hurry? Withdraw Funds also accepts inlineBeneficiary details directly, so you can skip this step for one-off payouts.

Step 5: Send the payout

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "currency": "NGN",
    "beneficiaryId": "BENEFICIARY_ID_FROM_STEP_4",
    "description": "Test payout"
  }'

100000 kobo = ₦1,000, and description is required. By default the fee comes out of your wallet balance on top of amount, so the beneficiary receives the full ₦1,000; pass deductFeesFromBalance: false to take it out of the amount sent instead. Want a fee quote first? Call Get Transaction Fee.

This request must come from an IP on your key’s allowlist (Step 1), or it is rejected with 403.

{
  "status": 200,
  "message": "Withdrawal initiated successfully",
  "success": true,
  "data": {
    "transaction": {
      "id": "866b7abd-6cac-40f2-a04f-d6e58bf47d04",
      "transaction_type": "withdrawal",
      "status": "pending",
      "description": "Test payout",
      "external_reference": "NG-NFNUJTUW",
      "fee_amount": 2500,
      "source_amount": 102500,
      "destination_amount": 100000,
      "source_currency": "NGN",
      "destination_currency": "NGN",
      "created_at": "2026-03-23T13:45:28.138Z",
      "updated_at": "2026-03-23T13:45:28.263Z",
      "beneficiary": {
        "bank_name": "Access Bank",
        "bank_code": "000014",
        "account_name": "JOHN DOE",
        "account_number": "0123456789"
      }
    }
  }
}

Keep the transaction id. source_amount is what left your wallet (amount plus the fee) and destination_amount is what the beneficiary gets. On USD and other non-NGN bank rails you can also send your own externalReference and fetch the transaction by it later — but NGN and mobile money payouts always get a Rolla-generated reference like NG-NFNUJTUW instead, because the provider imposes its own format. See Idempotency & Retries before retrying failed requests.

Step 6: Track it

Poll the transaction:

curl "https://api.rolla.xyz/api/v1/external/wallet/transaction/866b7abd-6cac-40f2-a04f-d6e58bf47d04" \
  -H "X-API-Key: your_api_key_here"

Or — better — configure a webhook endpoint in the dashboard and receive transaction.completed / transaction.failed events the moment the payout settles, instead of polling.

Next steps

Accept deposits

Static and per-customer virtual accounts for collections at scale.

Send payouts

All rails: local transfers, USD wires, SWIFT, mobile money, stablecoins.

Set up webhooks

Stop polling — get pushed every status change.

API Reference

Every endpoint, field by field.

Manage Your Own Money

Guides

Prerequisites

Step 1: Create an API key

Step 2: Make your first request

Step 3: Fund your wallet

Step 4: Create a beneficiary

Step 5: Send the payout

Step 6: Track it

Next steps

Accept deposits

Send payouts

Set up webhooks

API Reference

​Prerequisites

​Step 1: Create an API key

​Step 2: Make your first request

​Step 3: Fund your wallet

​Step 4: Create a beneficiary

​Step 5: Send the payout

​Step 6: Track it

​Next steps

Accept deposits

Send payouts

Set up webhooks

API Reference

Prerequisites

Step 1: Create an API key

Step 2: Make your first request

Step 3: Fund your wallet

Step 4: Create a beneficiary

Step 5: Send the payout

Step 6: Track it

Next steps