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>"
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/wallet/transfer"
payload = {
"amount": 100,
"currency": "USD",
"destinationCurrency": "USD",
"recipient": "partner@example.com",
"beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "Invoice payment",
"saveBeneficiary": True,
"rateToken": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 100,
currency: 'USD',
destinationCurrency: 'USD',
recipient: 'partner@example.com',
beneficiaryId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
description: 'Invoice payment',
saveBeneficiary: true,
rateToken: '<string>'
})
};
fetch('https://api.rolla.xyz/api/v1/external/wallet/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/wallet/transfer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 100,
'currency' => 'USD',
'destinationCurrency' => 'USD',
'recipient' => 'partner@example.com',
'beneficiaryId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'description' => 'Invoice payment',
'saveBeneficiary' => true,
'rateToken' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rolla.xyz/api/v1/external/wallet/transfer"
payload := strings.NewReader("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/wallet/transfer")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/wallet/transfer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"success": true,
"message": "Transfer initiated successfully",
"data": {
"transfer_reference": "TRANSFER-1712345678-abc12345",
"sender_transaction": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transaction_type": "deposit",
"status": "pending",
"description": "<string>",
"external_reference": "<string>",
"fee_amount": 123,
"fee_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fee_reference": "FEE-9J76UADV",
"related_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"related_reference": "<string>",
"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",
"transaction_type": "deposit",
"status": "pending",
"description": "<string>",
"external_reference": "<string>",
"fee_amount": 123,
"fee_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fee_reference": "FEE-9J76UADV",
"related_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"related_reference": "<string>",
"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>",
"status": "pending"
}
}
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<string>"
}Wallet
Rolla Transfer
Send funds to another Rolla business instantly and fee-free. Identify the recipient by email, Rolla tag, or a saved beneficiaryId.
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>"
}
'import requests
url = "https://api.rolla.xyz/api/v1/external/wallet/transfer"
payload = {
"amount": 100,
"currency": "USD",
"destinationCurrency": "USD",
"recipient": "partner@example.com",
"beneficiaryId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"description": "Invoice payment",
"saveBeneficiary": True,
"rateToken": "<string>"
}
headers = {
"X-API-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
amount: 100,
currency: 'USD',
destinationCurrency: 'USD',
recipient: 'partner@example.com',
beneficiaryId: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
description: 'Invoice payment',
saveBeneficiary: true,
rateToken: '<string>'
})
};
fetch('https://api.rolla.xyz/api/v1/external/wallet/transfer', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.rolla.xyz/api/v1/external/wallet/transfer",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'amount' => 100,
'currency' => 'USD',
'destinationCurrency' => 'USD',
'recipient' => 'partner@example.com',
'beneficiaryId' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'description' => 'Invoice payment',
'saveBeneficiary' => true,
'rateToken' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-API-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.rolla.xyz/api/v1/external/wallet/transfer"
payload := strings.NewReader("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.rolla.xyz/api/v1/external/wallet/transfer")
.header("X-API-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.rolla.xyz/api/v1/external/wallet/transfer")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"amount\": 100,\n \"currency\": \"USD\",\n \"destinationCurrency\": \"USD\",\n \"recipient\": \"partner@example.com\",\n \"beneficiaryId\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"description\": \"Invoice payment\",\n \"saveBeneficiary\": true,\n \"rateToken\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"status": 200,
"success": true,
"message": "Transfer initiated successfully",
"data": {
"transfer_reference": "TRANSFER-1712345678-abc12345",
"sender_transaction": {
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"transaction_type": "deposit",
"status": "pending",
"description": "<string>",
"external_reference": "<string>",
"fee_amount": 123,
"fee_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fee_reference": "FEE-9J76UADV",
"related_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"related_reference": "<string>",
"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",
"transaction_type": "deposit",
"status": "pending",
"description": "<string>",
"external_reference": "<string>",
"fee_amount": 123,
"fee_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"fee_reference": "FEE-9J76UADV",
"related_transaction_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"related_reference": "<string>",
"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>",
"status": "pending"
}
}
}{
"success": false,
"message": "<string>"
}{
"success": false,
"message": "<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).
Transferring from a specific merchant (tenant keys): if your API key is a white-label tenant key managing multiple merchants, add the
X-Account-Id header set to the account ID you want to send from — the transfer is then debited from that account’s wallet. Without it, it runs against your own (parent) account. This is how you move funds between your institutional account and merchant wallets.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 arateToken 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
Theamount 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
| Field | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | Amount in the smallest currency unit for currency (e.g. cents for USD: 100 = $1.00 USD; kobo for NGN) |
currency | string | Yes | Source currency code (e.g. USD) |
destinationCurrency | string | Yes | Recipient’s currency code |
recipient | string | Conditional | Recipient’s email or Rolla tag. Required if beneficiaryId not provided |
beneficiaryId | string (UUID) | Conditional | Saved beneficiary ID with withdrawal_method: rolla_transfer. Required if recipient not provided |
description | string | No | Transfer description (max 500 chars) |
saveBeneficiary | boolean | No | Auto-save the recipient as a beneficiary for future transfers |
rateToken | string | Conditional | Required for cross-currency transfers — obtain from GET /wallet/rates |
Authorizations
Your Rolla API key
Body
application/json
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
Source currency code
Example:
"USD"
Recipient currency code
Example:
"USD"
Recipient email or Rolla tag. Required if beneficiaryId not provided.
Example:
"partner@example.com"
Saved beneficiary ID with withdrawal_method rolla_transfer. Required if recipient not provided.
Transfer description
Maximum string length:
500Example:
"Invoice payment"
Auto-save the recipient as a beneficiary for future transfers
Required for cross-currency transfers. Obtain from GET /wallet/rates.
⌘I