Making a Transfer

📘
We assume that you have completed onboarding. Retrieve your API credentials before proceeding with the guide.

Follow these steps to charge a customer's card on your account.

Generate Access Token

Send your Client-Id and Client-Secret to our authentication endpoint to generate your access token. Each token is valid for 10 minutes, after which you should generate a new token.

curl -X POST 'https://idp.flutterwave.com/realms/flutterwave/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{CLIENT_ID}}' \
--data-urlencode 'client_secret={{CLIENT_SECRET}}' \
--data-urlencode 'grant_type=client_credentials'

{
    "access_token": "SAMPLE_TOKEN",
    "expires_in": 600,
    "refresh_expires_in": 0,
    "token_type": "Bearer",
    "not-before-policy": 0,
    "scope": "profile email"
}

Create a Transfer Recipient object

Create an entity to store the recipient's banking information; this object links the recipient data to the transfer.

curl --location 'https://developersandbox-api.flutterwave.com/transfers/recipients' \
--header 'Authorization: Bearer {{YOUR_ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Trace-Id: {{YOUR_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{YOUR_IDEMPOTENCY_KEY}}' \
--data '{
  "type": "bank_ngn",
  "bank": {
    "account_number": "0690000031",
    "code": "044"
  }
}'

{
  "status": "success",
  "message": "Recipient created",
  "data": {
    "type": "bank",
    "id": "rcb_B9aAgsdzzl",
    "name": {
      "first": "Tim",
      "last": "Jackson"
    },
    "currency": "NGN",
    "bank": {
      "account_number": "0690001031",
      "code": "044"
    }
  }
}

Save the recipient's id returned as response.data.id.

Initiate the Transfer

Provide the amount, recipient_id and currency for the transfer. Specify instant as the action before sending your request to the create transfer endpoint.

curl --location 'https://developersandbox-api.flutterwave.com/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}}' \
--header 'X-Scenario-Key: scenario:successful' \
--data '{
    "action": "instant",
    "reference": "95e25053-8ee4-42770-a29-af4004dyf9462d",
    "narration": "Test transfer",
    "meta": {
        "username": "Madyson.Jones43"
    },
    "payment_instruction": {
        "source_currency": "NGN",
        "destination_currency": "NGN",
        "amount": {
            "applies_to": "destination_currency",
            "value": 1000
        },
        "recipient_id": "rcb_B9aAgsdzzl"
    }
}'

{
    "status": "success",
    "message": "Transfer created",
    "data": {
        "id": "trf_iWUfJopFYdyBmB",
        "type": "bank",
        "action": "instant",
        "reference": "95e25053-8ee4-42770-a29-af4004dyf9462d",
        "status": "NEW",
        "narration": "Example Transfers",
        "source_currency": "NGN",
        "destination_currency": "NGN",
        "amount": {
            "value": 1000,
            "applies_to": "destination_currency"
        },
        "callback_url": "https://www.company.com/callback",
        "recipient": {
            "type": "bank",
            "currency": "NGN",
            "bank": {
                "account_number": "0690000031",
                "code": "044"
            },
            "id": "rcb_B9aAgsdzzl"
        },
        "meta": {},
        "created_datetime": "2024-12-10T13:49:06.374991375Z"
    }
}

Once the transfer is completed, we send you a transfer.disburse event via webhooks.

{
  "webhook_id": "wbk_rp0bjKyAWA52ViM8xlZ0",
  "timestamp": 1739877172874,
  "type": "transfer.disburse",
  "data": {
    "id": "trf_iWUfJopFYdyBmB",
    "type": "BANK",
    "source_currency": "NGN",
    "destination_currency": "NGN",
    "amount": 1000,
    "reference": "95e25053-8ee4-42770-a29-af4004dyf9462d",
    "status": "SUCCESSFUL",
    "bank": {
      "account_number": "0690000031",
      "code": "044",
      "branch": null,
      "name": null,
      "routing_number": null,
      "swift_code": null
    },
    "fee": {
      "currency": "NGN",
      "value": 10
    },
    "debit_information": {
      "currency": "NGN",
      "actual_debit_amount": 1000,
      "rate_used": 0.00123,
      "vat": 375
    },
    "payment_information": {
      "proof": "504828363550713897092362940989"
    },
    "meta": {}
  }
}