rembFlutterwave Transfers provides a suite of services that enable you to send money seamlessly to bank accounts, mobile numbers, wallets, and even through cash pickups. Depending on your business model, you can choose from the following options to facilitate transfers:
You can complete a transfer using either of the following flows:
- Transfer Orchestrator - This flow supports one-time transfers. Using this flow, it is quicker to initiate your transfer requests as all information is collected at once.
- General Transfer Flow - This supports recurring transfers best, i.e. transfers made to the same recipient or transfers requiring the same sender information. It is a customizable flow that offers more control over the payout process and user experience.
❗️
To effectively use through these instructions, You'll need API credentials. Sign up for test credentials here.
This guide demonstrates the orchestrator flow for one-time transfers. Read this explainer to initiate recurring transfers on your account.
Use the identity endpoint to generate your auth token. Read more about our API authentication here.
curl --location 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{YOUR_CLIENT_ID}}' \
--data-urlencode 'client_secret={{YOUR_CLIENT_SECRET}}' \
--data-urlencode 'grant_type=client_credentials'
Validate your customer's bank account information. This step is important to ensure that your transfer is processed successfully to the correct recipient.
Example Request
curl --request POST \
--url https://developersandbox-api.flutterwave.com/banks/account-resolve \
--header 'content-type: application/json' \
--data '
{
"account": {
"code": "044",
"number": "0690000040"
},
"currency": "NGN"
}
'
{
"status": "success",
"message": "string",
"data": {
"bank_code": "044",
"account_number": "0690000040",
"account_name": "Alex James"
}
}
200 Ok
curl --request POST \
--url https://developersandbox-api.flutterwave.com/banks/account-resolve \
--header 'content-type: application/json' \
--data '
{
"account": {
"code": "044",
"number": "0690000040"
},
"currency": "NGN"
}
'
{
"status": "success",
"message": "string",
"data": {
"bank_code": "044",
"account_number": "0690000040",
"account_name": "Alex James"
}
}
Send the transfer reference, payment instruction and transfer type to initiate the transfer. Read more about initiating transfers here.
Example Request
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
"action": "instant",
"payment_instruction": {
"source_currency": "NGN",
"amount": {
"applies_to": "destination_currency",
"value": 1000
},
"recipient": {
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"destination_currency": "NGN"
},
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb"
}'
{
"status": "success",
"message": "Transfer created",
"data": {
"id": "trf_pGoKPGH7rEgY4v",
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb",
"status": "NEW",
"source_currency": "NGN",
"destination_currency": "NGN",
"amount": {
"value": 50000,
"applies_to": "destination_currency"
},
"recipient": {
"type": "bank",
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"meta": {},
"created_datetime": "2024-12-05T12:36:20.069512926Z"
}
}
{
"status": "failed",
"error": {
"type": "REFERENCE_ALREADY_EXISTS",
"code": "201409",
"message": "Transfer with reference already exists",
"validation_errors": []
}
}
200 Ok
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
"action": "instant",
"payment_instruction": {
"source_currency": "NGN",
"amount": {
"applies_to": "destination_currency",
"value": 1000
},
"recipient": {
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"destination_currency": "NGN"
},
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb"
}'
{
"status": "success",
"message": "Transfer created",
"data": {
"id": "trf_pGoKPGH7rEgY4v",
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb",
"status": "NEW",
"source_currency": "NGN",
"destination_currency": "NGN",
"amount": {
"value": 50000,
"applies_to": "destination_currency"
},
"recipient": {
"type": "bank",
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"meta": {},
"created_datetime": "2024-12-05T12:36:20.069512926Z"
}
}
{
"status": "failed",
"error": {
"type": "REFERENCE_ALREADY_EXISTS",
"code": "201409",
"message": "Transfer with reference already exists",
"validation_errors": []
}
}
400 Bad Request
curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/direct-transfers' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_UNIQUE_INDEMPOTENCY_KEY}}' \
--data '{
"action": "instant",
"payment_instruction": {
"source_currency": "NGN",
"amount": {
"applies_to": "destination_currency",
"value": 1000
},
"recipient": {
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"destination_currency": "NGN"
},
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb"
}'
{
"status": "success",
"message": "Transfer created",
"data": {
"id": "trf_pGoKPGH7rEgY4v",
"type": "bank",
"reference": "574874568ufdgjhvbjhcdbchb",
"status": "NEW",
"source_currency": "NGN",
"destination_currency": "NGN",
"amount": {
"value": 50000,
"applies_to": "destination_currency"
},
"recipient": {
"type": "bank",
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"meta": {},
"created_datetime": "2024-12-05T12:36:20.069512926Z"
}
}
{
"status": "failed",
"error": {
"type": "REFERENCE_ALREADY_EXISTS",
"code": "201409",
"message": "Transfer with reference already exists",
"validation_errors": []
}
}
Before closing out the transfer, confirm its final status. See more details about status retrieval here.
{
"status": "success",
"message": "Transfer fetched",
"data": {
"id": "trf_ighwLOK9pHxoo9",
"type": "bank",
"action": "instant",
"reference": "5748745ug8ufdgjhveyyeebjhcdbchb",
"status": "SUCCESSFUL",
"source_currency": "NGN",
"destination_currency": "NGN",
"amount": {
"value": 50000,
"applies_to": "destination_currency"
},
"fee": {
"currency": "NGN",
"value": 500
},
"debit_information": {
"currency": "NGN",
"actual_debit_amount": 50000,
"rate_used": 0.00123,
"vat": 3750
},
"payment_information": {
"proof": "754119292904667985302775753026"
},
"callback_url": "https://webhook.site/352c4518-7797-4044-becc-669fc5b1e928",
"recipient": {
"type": "bank",
"id": "rcb_TDk7vKxUkj",
"name": {
"first": "Ajadi",
"last": "Jackson"
},
"currency": "NGN",
"bank": {
"account_number": "0122333334",
"code": "044"
}
},
"meta": {},
"created_datetime": "2025-02-18T11:20:37.282Z"
}
}
Updated 7 months ago