Skip to main content
POST
/
wallet
/
transfer
Rolla Transfer
curl --request POST \
  --url https://api.rolla.xyz/api/v1/external/wallet/transfer \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "amount": 100,
  "currency": "USD",
  "destinationCurrency": "USD",
  "recipient": "partner@example.com",
  "beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "description": "Invoice payment",
  "saveBeneficiary": true,
  "rateToken": "<string>"
}
'
{
  "status": 200,
  "success": true,
  "message": "Transfer initiated successfully",
  "data": {
    "transfer_reference": "TRANSFER-1712345678-abc12345",
    "sender_transaction": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "<string>",
      "external_reference": "<string>",
      "fee_amount": 123,
      "source_amount": 123,
      "destination_amount": 123,
      "source_currency": "<string>",
      "destination_currency": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "recipient_transaction": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "<string>",
      "external_reference": "<string>",
      "fee_amount": 123,
      "source_amount": 123,
      "destination_amount": 123,
      "source_currency": "<string>",
      "destination_currency": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "updated_at": "2023-11-07T05:31:56Z"
    },
    "pending_claim": {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "recipient_email": "<string>",
      "amount": 123,
      "currency": "<string>"
    }
  }
}
Send funds to another Rolla business instantly and fee-free. You can identify the recipient by their registered email address, Rolla tag, or a saved beneficiaryId with withdrawal_method: rolla_transfer. The request amount is always in the smallest currency unit for currency (USD = cents — 100 = $1.00 USD; NGN = kobo).

​
Example Request (by email)

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/transfer" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "destinationCurrency": "USD",
    "recipient": "partner@example.com",
    "description": "Invoice payment",
    "saveBeneficiary": true
  }'

​
Example Request (by saved beneficiary)

curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/transfer" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "destinationCurrency": "USD",
    "beneficiaryId": "d4e5f6a7-b8c9-0123-defa-456789012345",
    "description": "Invoice payment"
  }'

​
Example Request (cross-currency)

Cross-currency transfers require a rateToken from the GET /wallet/rates endpoint first. 
curl -X POST "https://api.rolla.xyz/api/v1/external/wallet/transfer" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "currency": "USD",
    "destinationCurrency": "NGN",
    "recipient": "partner@example.com",
    "rateToken": "rate_token_from_rates_endpoint",
    "description": "Cross-currency payment"
  }'

​
Example Response

The amount you send uses the smallest unit of currency (USD = cents below). Ledger fields such as source_amount mirror that unit. 
{
  "status": 200,
  "success": true,
  "message": "Transfer initiated successfully",
  "data": {
    "transfer_reference": "TRANSFER-1712345678-abc12345",
    "sender_transaction": {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "transaction_type": "withdrawal",
      "status": "completed",
      "description": "Invoice payment",
      "fee_amount": 0,
      "source_amount": 100,
      "destination_amount": 100,
      "source_currency": "USD",
      "destination_currency": "USD",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    "recipient_transaction": {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "transaction_type": "deposit",
      "status": "completed",
      "description": "Invoice payment",
      "fee_amount": 0,
      "source_amount": 100,
      "destination_amount": 100,
      "source_currency": "USD",
      "destination_currency": "USD",
      "created_at": "2024-01-15T10:30:00.000Z"
    },
    "pending_claim": null
  }
}

​
Key Behaviours

Free transfers — Rolla-to-Rolla transfers have zero fees.
pending_claim — If the recipient email matches multiple Rolla businesses, funds are held in escrow and a pending_claim object is returned. The recipient must log in and claim the funds.
IP whitelisting — This endpoint requires your API key to have IP whitelisting configured, or the request must originate from a whitelisted IP.

​
Parameters

FieldTypeRequiredDescription
amountnumberYesAmount in the smallest currency unit for currency (e.g. cents for USD: 100 = $1.00 USD; kobo for NGN)
currencystringYesSource currency code (e.g. USD)
destinationCurrencystringYesRecipient’s currency code
recipientstringConditionalRecipient’s email or Rolla tag. Required if beneficiaryId not provided
beneficiaryIdstring (UUID)ConditionalSaved beneficiary ID with withdrawal_method: rolla_transfer. Required if recipient not provided
descriptionstringNoTransfer description (max 500 chars)
saveBeneficiarybooleanNoAuto-save the recipient as a beneficiary for future transfers
rateTokenstringConditionalRequired for cross-currency transfers — obtain from GET /wallet/rates

Authorizations

​
X-API-Key
string
header
required

Your Rolla API key

Body

application/json
​
amount
number
required

Amount in the smallest currency unit for the given currency (e.g. kobo for NGN, cents for USD — 100 cents = $1.00 USD).

Example:

100

​
currency
string
required

Source currency code

Example:

"USD"

​
destinationCurrency
string
required

Recipient currency code

Example:

"USD"

​
recipient
string

Recipient email or Rolla tag. Required if beneficiaryId not provided.

Example:

"partner@example.com"

​
beneficiaryId
string<uuid>

Saved beneficiary ID with withdrawal_method rolla_transfer. Required if recipient not provided.

​
description
string

Transfer description

Maximum string length: 500
Example:

"Invoice payment"

​
saveBeneficiary
boolean

Auto-save the recipient as a beneficiary for future transfers

​
rateToken
string

Required for cross-currency transfers. Obtain from GET /wallet/rates.

Response

Transfer initiated successfully

​
status
integer
Example:

200

​
success
boolean
Example:

true

​
message
string
Example:

"Transfer initiated successfully"

​
data
object