v1

latestOpenAPI 3.1.02026-07-2656258207.2 KB

Transfers

Create a transfer

Creates a direct transfer using only the recipient and sender IDs. Before calling this endpoint, make sure you have already created both the recipient and the sender via their respective endpoints and obtained their IDs.

post/transfers

Headers

X-Trace-Idstring

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

X-Idempotency-Keystring

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

X-Scenario-Keystring

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.

Request body

action'instant' | 'deferred' | 'scheduled' required

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

referencestring

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

narrationstring

transfer description. This cannot be greater than 180 characters

callback_urlstring

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

metaMeta

Example request

{
  "payment_instruction": {
    "source_currency": "NGN",
    "amount": {
      "value": 3000.44
    },
    "recipient_id": "rcb_atNyZLK4f9",
    "sender_id": "sdr_DJOWzrFT6V"
  }
}

Response

status'success' | 'failed'

messagestring

Example response

{
  "data": {
    "id": "trf_yuK89vb",
    "type": "bank",
    "reversal": {
      "initial_status": "SUCCESSFUL",
      "reconciliation_status": "REVERSED"
    },
    "narration": "Salary payment for January",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": {
      "value": 3000.44
    },
    "fee": {
      "currency": "NGN",
      "value": 10.35
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 100.35,
      "rate_used": 100.35,
      "vat": 100.35
    },
    "extra_information": {
      "amount_credited": "USDT 100"
    },
    "payment_information": {
      "proof": "11000224070317345400001414441712312381"
    },
    "retry": {
      "parent_id": "trf_HUQUYb1Sp5CkiIJFebk1Z",
      "parent_reference": "flw_z882wFGMjc"
    },
    "duplicate": {
      "parent_id": "trf_HUQUYb1Sp5CkiIJFebk1Z",
      "parent_reference": "flw_z882wFGMjc"
    },
    "callback_url": "https://example.com/flw/callback",
    "provider_response": {
      "message": "DISBURSE FAILED: Insufficient wallet balance"
    },
    "recipient": {
      "name": {
        "first": "King",
        "middle": "Leo",
        "last": "LeBron"
      },
      "currency": "NGN",
      "national_identification": {
        "identifier": "FLY5869798686",
        "expiration_date": "2029-07-08"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      },
      "email": "cornelius@gmail.com",
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "postal_code": "10001",
        "state": "New York"
      }
    },
    "sender": {
      "name": {
        "first": "King",
        "middle": "Leo",
        "last": "LeBron"
      },
      "national_identification": {
        "identifier": "FLY5869798686",
        "expiration_date": "2029-07-08"
      },
      "phone": {
        "country_code": "234",
        "number": "08012345678"
      },
      "email": "cornelius@gmail.com",
      "address": {
        "city": "New York",
        "country": "US",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "postal_code": "10001",
        "state": "New York"
      }
    },
    "transfer_purpose": "personal"
  }
}