Accept Deposits

Rolla credits your wallet whenever money arrives at one of your deposit accounts. The details differ by currency — a USD deposit account is provisioned on your wallet automatically, while local-currency deposits go through virtual accounts you generate — but the notification pattern is the same either way.

Don’t poll. Configure a webhook endpoint subscribed to transaction.completed and you’ll hear about every deposit the moment it lands, whichever currency it’s in.

Accept a USD deposit

Your USD deposit account is issued to you automatically — there’s no account to generate. Fetch its details from List Wallets:

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

The USD wallet’s virtualAccounts entry carries everything a sender needs to wire you money:

{
  "bank_name": "Bank of America",
  "account_number": "9876543210",
  "account_name": "Rolla / Your Business Name",
  "routing_number": "101019644",
  "swift_code": "LEADUS44",
  "bank_address": {
    "street": "1801 Main St",
    "city": "Kansas City",
    "state": "MO",
    "postalCode": "64108",
    "country": "US"
  }
}

Share these details with whoever is paying you — a domestic ACH/wire sender uses the routing_number, an international sender uses the swift_code. Deposits are credited to your USD wallet automatically.

Platforms: issuing USD deposit accounts for your customers works differently — see Issue Bank Account and Funding Instructions.

Once a deposit lands, you’ll get a webhook like this:

{
  "event": "transaction.completed",
  "data": {
    "type": "deposit",
    "status": "completed",
    "currency": "USD",
    "amount": 500000
  }
}

amount is in cents, so 500000 = $5,000.00.

Testing without a real wire? Simulate a USD Deposit credits your USD wallet through the same webhook path. Pass sender_name and payment_rail (ach, fedwire or swift) to test payer and per-rail reconciliation. It exists in sandbox only — call it against https://api-staging.rolla.xyz; in production it returns 404.

Accept a local currency deposit (e.g. NGN)

Local-currency collections go through virtual accounts you generate through the API:

Type	Lives for	Best for
Dynamic	One payment (expires)	Checkout flows — one account per expected payment, optionally pinned to an exact `amount`
Static	Forever	A permanent top-up account for your business
Customer	Forever, per end user	Giving each of your users their own dedicated account number

Example: a dedicated account per customer

Customer virtual accounts are keyed on your customer_identifier, so the call is idempotent — repeat it and you get the same account back (200) instead of a duplicate (201 on first creation):

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/virtual-accounts/generate/customer" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_identifier": "user_8412",
    "first_name": "Ada",
    "last_name": "Obi",
    "email": "ada@example.com",
    "phone": "08012345678",
    "bvn": "22222222222",
    "date_of_birth": "04/02/1995",
    "address": "12 Marina Road, Lagos",
    "gender": "2"
  }'

Show the returned account_number and bank_name to your user. Every transfer they make to it lands in your wallet, tagged with their customer_identifier so you can credit the right user. List them any time with List Customer Virtual Accounts.

Customer virtual accounts require the end user’s BVN for KYC, along with their name, date of birth (mm/dd/yyyy), address and gender. The raw BVN is never echoed back — responses carry only bvn_last4. In sandbox, use the test BVN 22222222222.

Deposits to customer virtual accounts land in your wallet, tagged by customer — you keep the ledger. If each customer should instead hold their own verified account and wallet, that’s the Platform product.

Once a deposit lands, match it by virtual_account and customer_identifier in the webhook payload:

{
  "event": "transaction.completed",
  "data": {
    "type": "deposit",
    "status": "completed",
    "currency": "NGN",
    "amount": 500000,
    "customer_identifier": "user_8412",
    "virtual_account": { "account_number": "1234567890" }
  }
}

A deposit can arrive as transaction.pending first and complete moments later — treat transaction.completed as the signal that funds are spendable.

Testing without a real transfer? Simulate a Deposit credits an account by account_number or customer_identifier and fires the same webhook. It exists in sandbox only — call it against https://api-staging.rolla.xyz; in production it returns 404.

Stablecoin deposits

Crypto deposit addresses are provisioned on your wallet the same way USD deposit accounts are — find them on List Wallets. Deposit webhooks fire exactly as above, with rail: "stablecoin" and a network block (chain, tx hash, addresses).

Manage Your Own Money

Guides

Accept a USD deposit

Accept a local currency deposit (e.g. NGN)

Example: a dedicated account per customer

Stablecoin deposits

​Accept a USD deposit

​Accept a local currency deposit (e.g. NGN)

​Example: a dedicated account per customer

​Stablecoin deposits

Accept a USD deposit

Accept a local currency deposit (e.g. NGN)

Example: a dedicated account per customer

Stablecoin deposits