Skip to main content
POST
/
wallet
/
withdraw
Withdraw Funds
curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/wallet/withdraw \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": 5000,
  "currency": "NGN",
  "description": "<string>",
  "externalReference": "<string>",
  "beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "inlineBeneficiary": {
    "withdrawal_method": "local_transfer",
    "account_name": "John Doe",
    "account_number": "0123456789",
    "bank_name": "Access Bank",
    "bank_code": "000014",
    "routing_number": "<string>",
    "swift_code": "<string>",
    "sort_code": "400515",
    "iban": "DE89370400440532013000",
    "bic": "COBADEFFXXX",
    "bank_address": {
      "street": "456 Bank Avenue",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "beneficiary_address": {
      "street": "123 Main Street",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    },
    "wallet_address": "TXyZ1234abcd5678efgh9012ijkl3456mnop",
    "wallet_chain": "tron",
    "intermediary_bank_name": "<string>",
    "intermediary_bank_routing_number": "<string>",
    "email": "jsmith@example.com",
    "contact_person": "<string>"
  },
  "saveBeneficiary": false,
  "deductFeesFromBalance": false
}
'
{
  "status": 200,
  "success": true,
  "message": "Withdrawal initiated successfully",
  "transaction": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "transaction_type": "withdrawal",
    "status": "pending",
    "description": "<string>",
    "external_reference": "<string>",
    "fee_amount": 25,
    "source_amount": 5000,
    "destination_amount": 4975,
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "beneficiary": {
      "bank_name": "<string>",
      "bank_code": "<string>",
      "account_name": "<string>",
      "account_number": "<string>"
    }
  }
}
Initiate a withdrawal from your wallet to a beneficiary. You can reference a saved beneficiary by ID or provide inline beneficiary details for a one-time transfer. Either beneficiaryId or inlineBeneficiary must be provided. The required fields inside inlineBeneficiary depend on the currency and withdrawal_method.

​
Top-level Parameters

ParameterTypeRequiredDescription
amountnumberYesAmount in the smallest unit (e.g. kobo for NGN, cents for USD)
currencystringYes3-letter currency code — NGN, USD, or XAF
descriptionstringNoNarration for the transaction
externalReferencestringNoYour own unique reference for this transaction
beneficiaryIdstring (UUID)No*ID of a saved beneficiary
inlineBeneficiaryobjectNo*One-time beneficiary details (see per-currency fields below)
saveBeneficiarybooleanNoSave the inline beneficiary for future use
deductFeesFromBalancebooleanNoIf true, fees are deducted from your wallet; beneficiary receives the exact amount
* One of beneficiaryId or inlineBeneficiary is required.

​
inlineBeneficiary — Required Fields by Currency

​
NGN

FieldRequired
account_numberYes
bank_nameYes
bank_codeYes
account_nameNo (auto-resolved from bank lookup)
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": 5000,
    "currency": "NGN",
    "description": "Vendor payment",
    "inlineBeneficiary": {
      "account_number": "0123456789",
      "bank_name": "Access Bank",
      "bank_code": "000014"
    },
    "saveBeneficiary": true
  }'

​
USD — Domestic Wire

FieldRequired
withdrawal_methodYes — "domestic_wire"
account_nameYes
bank_nameYes
account_numberYes
routing_numberYes
beneficiary_addressYes — { street, city, state, postalCode, country }
bank_addressYes — { street, city, state, postalCode, country }
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": 1000,
    "currency": "USD",
    "inlineBeneficiary": {
      "withdrawal_method": "domestic_wire",
      "account_name": "Jane Smith",
      "bank_name": "Chase Bank",
      "account_number": "123456789",
      "routing_number": "021000021",
      "beneficiary_address": { "street": "123 Main St", "city": "New York", "state": "NY", "postalCode": "10001", "country": "US" },
      "bank_address": { "street": "270 Park Ave", "city": "New York", "state": "NY", "postalCode": "10017", "country": "US" }
    }
  }'

​
USD — International Wire

FieldRequired
withdrawal_methodYes — "international_wire"
account_nameYes
bank_nameYes
account_numberYes
swift_codeYes
beneficiary_addressYes — { street, city, state, postalCode, country }
bank_addressYes — { street, city, state, postalCode, country }
intermediary_bank_nameNo
intermediary_bank_routing_numberNo
USD international wire requires reference documents/invoices to be attached. Send the request as multipart/form-data and include one or more files under the documents field alongside your other fields.
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/withdraw" \
  -H "X-API-Key: your_api_key_here" \
  -F "amount=1000" \
  -F "currency=USD" \
  -F "inlineBeneficiary[withdrawal_method]=international_wire" \
  -F "inlineBeneficiary[account_name]=Jane Smith" \
  -F "inlineBeneficiary[bank_name]=Barclays Bank" \
  -F "inlineBeneficiary[account_number]=12345678" \
  -F "inlineBeneficiary[swift_code]=BARCGB22" \
  -F "inlineBeneficiary[beneficiary_address][street]=123 Main Street" \
  -F "inlineBeneficiary[beneficiary_address][city]=New York" \
  -F "inlineBeneficiary[beneficiary_address][state]=NY" \
  -F "inlineBeneficiary[beneficiary_address][postalCode]=10001" \
  -F "inlineBeneficiary[beneficiary_address][country]=US" \
  -F "inlineBeneficiary[bank_address][street]=456 Bank Avenue" \
  -F "inlineBeneficiary[bank_address][city]=New York" \
  -F "inlineBeneficiary[bank_address][state]=NY" \
  -F "inlineBeneficiary[bank_address][postalCode]=10001" \
  -F "inlineBeneficiary[bank_address][country]=US" \
  -F "documents=@/path/to/invoice.pdf"

​
USD — Crypto (USDT / USDC)

Crypto withdrawals are sent from your USD wallet. Set withdrawal_method to "crypto_usdt" or "crypto_usdc" to send the USD value as a stablecoin to a crypto wallet address.
FieldRequired
withdrawal_methodYes — "crypto_usdt" or "crypto_usdc"
account_nameYes — used as a display nickname
wallet_addressYes — 26–64 alphanumeric characters
wallet_chainYes — e.g. "ethereum", "tron"
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": 100,
    "currency": "USD",
    "inlineBeneficiary": {
      "withdrawal_method": "crypto_usdt",
      "account_name": "My USDT Wallet",
      "wallet_address": "TXyZ1234abcd5678efgh9012ijkl3456mnop",
      "wallet_chain": "tron"
    }
  }'

​
XAF

FieldRequired
account_nameYes
bank_nameYes
account_numberYes
swift_codeYes
bank_addressYes — { street, city, state, country }

​
Example Response

{
  "status": 200,
  "success": true,
  "message": "Withdrawal initiated successfully",
  "data": {
    "transaction": {
      "id": "866b7abd-6cac-40f2-a04f-d6e58bf47d04",
      "transaction_type": "withdrawal",
      "status": "pending",
      "description": "Vendor payment",
      "external_reference": "NG-NFNUJTUW",
      "fee_amount": 25,
      "source_amount": 5000,
      "destination_amount": 4975,
      "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"
      }
    }
  }
}
Use beneficiaryId to pay a saved beneficiary. Use inlineBeneficiary for one-time transfers. Set saveBeneficiary: true to save the inline beneficiary automatically for reuse.
Fees: By default, fees are deducted from the withdrawal amount (beneficiary receives less). Set deductFeesFromBalance: true so fees come out of your wallet balance and the beneficiary receives the exact amount specified.

Authorizations

​
X-API-Key
string
header
required

Your Rolla API key

Body

application/json

Either beneficiaryId or inlineBeneficiary must be provided.

​
amount
number
required

Amount in the smallest unit (e.g. kobo for NGN, cents for USD)

Example:

5000

​
currency
string
required

3-letter currency code

Required string length: 3
Example:

"NGN"

​
description
string

Narration for the transaction

Maximum string length: 500
​
externalReference
string

Your own unique reference for this transaction

Maximum string length: 255
​
beneficiaryId
string<uuid>

ID of a saved beneficiary. Use this OR inlineBeneficiary.

​
inlineBeneficiary
object

One-time beneficiary details (use instead of beneficiaryId)

​
saveBeneficiary
boolean
default:false

Save the inline beneficiary for future use

​
deductFeesFromBalance
boolean
default:false

If true, fees are taken from your wallet balance so the beneficiary receives the exact amount

Response

Withdrawal initiated successfully

​
status
number
Example:

200

​
success
boolean
Example:

true

​
message
string
Example:

"Withdrawal initiated successfully"

​
transaction
object