Skip to main content
POST
/
direct-transfers
Initiate an Orchestrator transfer.
curl --request POST \
  --url https://developersandbox-api.flutterwave.com/direct-transfers \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "action": "instant",
  "payment_instruction": {
    "source_currency": "NGN",
    "amount": {
      "value": 3000.44,
      "applies_to": "destination_currency"
    },
    "recipient": {
      "bank": {
        "account_number": "0690000031",
        "code": "044"
      }
    },
    "sender": {
      "name": {
        "first": "King",
        "last": "LeBron",
        "middle": "Leo"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      },
      "email": "erik@devxpay.com",
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main Street",
        "postal_code": "10001",
        "state": "New York",
        "line2": "Apt 4B"
      }
    }
  },
  "reference": "<string>",
  "narration": "<string>",
  "disburse_option": {
    "date_time": "<string>",
    "timezone": "Africa/Cairo"
  },
  "callback_url": "<string>",
  "meta": {}
}
'
{
  "status": "success",
  "message": "<string>",
  "data": {
    "id": "trf_yuK89vb",
    "type": "bank",
    "action": "instant",
    "reference": "<string>",
    "status": "NEW",
    "reversal": {
      "reversal_datetime": "2023-11-07T05:31:56Z",
      "initial_status": "SUCCESSFUL",
      "reconciliation_status": "REVERSED",
      "reconciliation_type": "D"
    },
    "narration": "Salary payment for January",
    "source_currency": "NGN",
    "destination_currency": "EUR",
    "amount": {
      "value": 3000.44,
      "applies_to": "destination_currency"
    },
    "fee": {
      "currency": "NGN",
      "value": 10.35
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 100.35,
      "rate_used": 100.35,
      "vat": 100.35
    },
    "payment_information": {
      "proof": "11000224070317345400001414441712312381"
    },
    "retry": {
      "parent_id": "trf_HUQUYb1Sp5CkiIJFebk1Z",
      "parent_reference": "flw_z882wFGMjc"
    },
    "duplicate": {
      "parent_id": "trf_HUQUYb1Sp5CkiIJFebk1Z",
      "parent_reference": "flw_z882wFGMjc"
    },
    "disburse_option": {
      "date_time": "<string>",
      "timezone": "Africa/Cairo"
    },
    "callback_url": "https://example.com/flw/callback",
    "provider_response": {
      "type": "transfer_amount_exceeds_limit",
      "code": "<string>",
      "message": "DISBURSE FAILED: Insufficient wallet balance"
    },
    "recipient": {
      "bank": {
        "account_number": "<string>",
        "code": "<string>",
        "account_type": "checking",
        "branch": "<string>",
        "name": "<string>",
        "routing_number": "<string>",
        "swift_code": "<string>",
        "sort_code": "<string>"
      },
      "id": "<string>",
      "type": "bank",
      "name": {
        "first": "King",
        "middle": "Leo",
        "last": "LeBron"
      },
      "currency": "NGN",
      "national_identification": {
        "type": "PASSPORT",
        "identifier": "FLY5869798686",
        "expiration_date": "2029-07-08"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      },
      "date_of_birth": "<string>",
      "email": "hi@flutterwave.com",
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main Street",
        "postal_code": "10001",
        "state": "New York",
        "line2": "Apt 4B"
      }
    },
    "sender": {
      "id": "<string>",
      "name": {
        "first": "King",
        "middle": "Leo",
        "last": "LeBron"
      },
      "national_identification": {
        "type": "PASSPORT",
        "identifier": "FLY5869798686",
        "expiration_date": "2029-07-08"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      },
      "date_of_birth": "<string>",
      "email": "cornelius@gmail.com",
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main Street",
        "postal_code": "10001",
        "state": "New York",
        "line2": "Apt 4B"
      }
    },
    "meta": {},
    "created_datetime": "2023-11-07T05:31:56Z"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
X-Trace-Id
string

A unique identifier to track this operation. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Idempotency-Key
string

A unique identifier to prevent duplicate requests. It must be between 12 and 255 characters in length.

Required string length: 12 - 255
​
X-Scenario-Key
string

An optional scenario key that can be used to simulate specific behaviors or test different scenarios within the API. Providing this header allows you to trigger predefined responses or alter data based on the key's value, which can be useful for testing, development, or demonstrating specific functionalities. The key should be a string of 1 to 1000 characters.

Body

application/json
​
action
enum<string>
required

To define whether the transfer should be processed immediately, scheduled for a later date, or deferred for future processing.

Available options:
instant,
deferred,
scheduled
Example:

"instant"

​
payment_instruction
object
required

Currency-specific information for the transfer.

​
reference
string

A custom identifier to track the transaction, This must be unique across all your transactions.

Required string length: 6 - 42
Pattern: ^[a-zA-Z0-9\-]+$
​
narration
string

Transfer description. This cannot be greater than 180 characters.

Required string length: 1 - 180
​
disburse_option
object

To specify the date and time for disbursement, this is required when action is set to scheduled.

​
callback_url
string

Specify to set a callback url for receiving payout webhook, this will take precedent over the merchant's default webhook url.

​
meta
object

Response

OK

​
status
enum<string>
Available options:
success,
failed
​
message
string
​
data
object