Initiate an Orchestrator transfer.

Create a transfer with Orchestrator helper.

POST /direct-transfers

Initiate an Orchestrator transfer.

cURL

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
    },
    "recipient": {
      "bank": {
        "account_number": "0690000031",
        "code": "044"
      }
    }
  },
  "reference": "<string>",
  "narration": "<string>",
  "disburse_option": {
    "date_time": "<string>"
  },
  "callback_url": "<string>",
  "meta": {}
}
'

201

{
  "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": "[e-mail]",
      "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": "[e-mail]",
      "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

Option 1

Option 2

Option 3

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.

Option 1

Option 2

Option 3

Option 4

Option 5

Option 6

Option 7

Option 8

Show child attributes

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.

Show child attributes

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

Show child attributes

Response

201

application/json

OK

status · enum<string>

Available options: success, failed

message · string

data · object

Show child attributes