> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rolla.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Rolla Transfer
> Send funds to another Rolla business instantly and fee-free. Identify the recipient by email, Rolla tag, or a saved beneficiaryId.
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`](/api-reference/introduction#acting-on-a-tenant-account-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)
```bash theme={null}
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)
```bash theme={null}
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`](/api-reference/endpoint/wallet/rates) endpoint first.
```bash theme={null}
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.
```json theme={null}
{
"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` |
## OpenAPI
````yaml POST /wallet/transfer
openapi: 3.1.0
info:
title: Rolla Developer API
description: >-
API for programmatic transaction management on the Rolla platform. Monetary
`amount` fields use the smallest unit of the referenced currency unless an
endpoint says otherwise (e.g. NGN = kobo, USD = cents, where **100 cents =
USD 1.00**).
version: 1.0.0
servers:
- url: https://api.rolla.xyz/api/v1/external
description: Production server
security:
- apiKeyAuth: []
paths:
/wallet/transfer:
post:
summary: Rolla Transfer
description: >-
Send funds to another Rolla business instantly and fee-free. Identify
the recipient by email, Rolla tag, or a saved beneficiaryId.
operationId: rollaTransfer
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- amount
- currency
- destinationCurrency
properties:
amount:
type: number
description: >-
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:
type: string
description: Source currency code
example: USD
destinationCurrency:
type: string
description: Recipient currency code
example: USD
recipient:
type: string
description: >-
Recipient email or Rolla tag. Required if beneficiaryId not
provided.
example: partner@example.com
beneficiaryId:
type: string
format: uuid
description: >-
Saved beneficiary ID with withdrawal_method rolla_transfer.
Required if recipient not provided.
description:
type: string
description: Transfer description
maxLength: 500
example: Invoice payment
saveBeneficiary:
type: boolean
description: >-
Auto-save the recipient as a beneficiary for future
transfers
rateToken:
type: string
description: >-
Required for cross-currency transfers. Obtain from GET
/wallet/rates.
responses:
'200':
description: Transfer initiated successfully
content:
application/json:
schema:
type: object
properties:
status:
type: integer
example: 200
success:
type: boolean
example: true
message:
type: string
example: Transfer initiated successfully
data:
type: object
properties:
transfer_reference:
type: string
example: TRANSFER-1712345678-abc12345
sender_transaction:
$ref: '#/components/schemas/Transaction'
recipient_transaction:
oneOf:
- $ref: '#/components/schemas/Transaction'
- type: 'null'
description: Null if pending_claim is set
pending_claim:
type: object
nullable: true
description: >-
Set when the recipient email matches multiple Rolla
businesses. Funds are held until claimed.
properties:
id:
type: string
format: uuid
recipient_email:
type: string
amount:
type: integer
currency:
type: string
status:
type: string
enum:
- pending
- claimed
- expired
'400':
description: >-
Bad request — insufficient balance, invalid recipient, or missing
fields
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: Unauthorized - Invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Transaction:
type: object
properties:
id:
type: string
format: uuid
description: Transaction identifier
transaction_type:
type: string
enum:
- deposit
- withdrawal
- swap
description: Transaction type
status:
type: string
enum:
- pending
- completed
- failed
- rejected
- sent
- processing
description: Transaction status
description:
type: string
description: Transaction description
external_reference:
type: string
nullable: true
description: External reference ID
fee_amount:
type: number
description: >-
Fee charged for this transaction. On a `fee` transaction this is `0`
— the fee value is carried as that row's
source_amount/destination_amount, so totalling fee_amount across
transactions does not double-count it.
fee_transaction_id:
type: string
format: uuid
description: >-
Where the fee is charged to a different account rather than deducted
from this transaction, the id of the separate transaction it was
booked as. Omitted when no such transaction exists.
fee_reference:
type: string
description: >-
Reference of that fee transaction, in the form `FEE-XXXXXXXX`.
Omitted when no separate fee transaction exists.
example: FEE-9J76UADV
related_transaction_id:
type: string
format: uuid
description: >-
On a `fee` transaction, the id of the transaction the fee was
charged for — the reverse of fee_transaction_id. Omitted on
transactions that are not fees.
related_reference:
type: string
description: >-
Reference of that originating transaction. Omitted on transactions
that are not fees.
source_amount:
type: number
description: >-
Amount debited from the source wallet. Normally amount + fee for a
payout, but equal to the amount when the fee is charged to a
separate account. Never derive the fee from this — read fee_amount.
destination_amount:
type: number
description: Amount credited to the destination wallet
source_currency:
type: string
description: Currency of the source wallet
destination_currency:
type: string
description: Currency of the destination wallet
created_at:
type: string
format: date-time
description: Transaction creation timestamp
updated_at:
type: string
format: date-time
description: Last update timestamp
Error:
type: object
properties:
success:
type: boolean
example: false
message:
type: string
securitySchemes:
apiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Your Rolla API key
````