DocumentationAPI ReferencesSupportBlogAsk AI
Documentation

Cash Pickup

Learn how to send money for your customers to pick up at an authorized location.

Suggest Edits

Flutterwave allows you to initiate transfers to a customer where they can simply walk into a bank and collect it. We refer to these as cash pick-up transfers.

You can read this article for a detailed explanation of how to initiate these transfers from your dashboard.

This feature is only supported in Egypt (EGP) and Nigeria (NGN).


Prerequisites

  • Whitelist your IP addresses.
  • Ensure your balance has sufficient funds. You can fund your balance by one of the following methods:
    • Direct funding via collections.
    • Indirect funding via FX conversion from a different currency balance, i.e., intra-wallet transfers.

🚧

Approval Required

You need approval to use this feature. Contact us at [email protected] to request permission on your account.

Payout Flow

Every successful wallet-to-wallet transfer goes through two (2) stages of the process before completion:

  • Initiate Payout
  • Verify Payout

Initiate Payout

To successfully initiate a wallet-to-wallet transfer, you must include the following required parameters in your request to the create a transfer endpoint:

  • action: This defines how the transfer should be processed. Possible values are instant, deferred, or scheduled.
  • type: Indicates the type of transfer. For cash pickup transfers, use cash_pickup.
  • payment_instruction: An object containing details of the payment, including:
    • amount
    • currency (source_currency and destination_currency)
    • recipient details, such as the cash pickup network.
    • sender details (required due to regulations)

Sample Request

curl --location 'https://api-sit.flutterwave.cloud/developersandbox/transfers' \
--header 'X-Trace-Id: {{UNIQUE_TRACE_ID}}' \
--header 'X-Idempotency-Key: {{UNIQUE_IDEMPOTENCY_KEY}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API_ACCESS_TOKEN}}' \
--data-raw '{
    "reference": "{{UNIQUE_TRANSFER_REFERENCE}}",
    "action": "instant",
    "type": "cash_pickup",
    "narration": "An awesome cash pickup",
    "payment_instruction": {
        "destination_currency": "NGN",
        "source_currency": "EGP",
        "amount": {
            "value": "1234.56",
            "applies_to": "source_currency"
        },
        "sender": {
            "name": {
                "first": "Bob",
                "middle": "The",
                "last": "Builder"
            },
            "email": "[email protected]",
            "phone": {
                "country_code": "91",
                "number": "9012345678"
            },
            "address": {
                "line1": "7A, Simple Street",
                "line2": "Awesome Apartments",
                "city": "Cool City",
                "postal_code": "123456",
                "state": "Super State",
                "country": "EG"
            },
                "date_of_birth": "1980-08-15",
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "1234567890",
                "expiration_date": "2028-12-25"
            }
        },
        "recipient": {
            "name": {
                "first": "John",
                "middle": "Generic",
                "last": "Doe"
            },
            "email": "[email protected]",
            "phone": {
                "country_code": "234",
                "number": "9012345678"
            },
            "address": {
                "line1": "8B, Simple Street",
                "line2": "Awesome Apartments",
                "city": "Cool City",
                "postal_code": "123456",
                "state": "Super State",
                "country": "NG"
            },
            "date_of_birth": "1980-08-15",
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "9876543210",
                "expiration_date": "2028-12-25"
            },
            "cash_pickup": {
                "network": "GT_BANK"
            }
        }
    }
}'

💱

Handling International Transfer

Check out the managing currency section to learn how to manage payouts between different currencies.

You can also initiate scheduled or deferred mobile money transfers by setting the action field to scheduled or deferred, respectively.

For a scheduled transfer, include the disburse_option object in the request, which specifies:

  • date_time: The exact time the transfer should be triggered.
  • timezone: The timezone for the scheduled time.

Refer to the transfer overview for detailed steps on creating and completing these types of transfers.

Handling the Response

On successfully initiating a transfer, you’ll get a response like this:

{
    "status": "success",
    "message": "Transfer created",
    "data": {
        "id": "trf_RnB180t3HcuGui",
        "type": "cash_pickup",
        "action": "instant",
        "reference": "66ada47c-314b-4cff-bcf3-ce4f40d3738d",
        "status": "NEW",
        "narration": "An awesome payment",
        "source_currency": "EGP",
        "destination_currency": "NGN",
        "amount": {
            "value": 1234.56,
            "applies_to": "source_currency"
        },
        "recipient": {
            "type": "bank",
            "name": {
                "first": "Bob",
                "middle": "The",
                "last": "Builder"
            },
            "currency": "NGN",
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "9876543210"
            },
            "phone": {
                "country_code": "234",
                "number": "9012345678"
            },
            "email": "[email protected]",
            "address": {
                "city": "Cool City",
                "country": "NG",
                "line1": "8B, Simple Street",
                "line2": "Awesome Apartments",
                "postal_code": "123456",
                "state": "Super State"
            },
            "id": "rcc_djiYqp8reU"
        },
        "sender": {
            "id": "sdr_W3PJ4U5Z4b",
            "name": {
                "first": "Bob",
                "middle": "The",
                "last": "Builder"
            },
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "1234567890"
            },
            "phone": {
                "country_code": "91",
                "number": "9012345678"
            },
            "date_of_birth": "1980-08-15",
            "email": "[email protected]",
            "address": {
                "city": "Cool City",
                "country": "EG",
                "line1": "7A, Simple Street",
                "line2": "Awesome Apartments",
                "postal_code": "123456",
                "state": "Super State"
            }
        },
        "meta": {},
        "created_datetime": "2025-01-28T15:40:27.650598789Z"
    }
}

The status returned in the data.status field above is always “NEW” (refer to the status section to see possible statuses). This indicates that the transfer has been successfully initiated. Your customers can then proceed to their bank to pick up the funds.

💡

Customer Identification

Ensure that your users are informed about collecting cash with valid means of identification. Cash collection is subject to the directives of the Central Bank of the recipient’s country.

To verify the final status of the transfer, see the verify payout section below for details on how to verify the status of a cash pickup transfer.

Verify Payout

There are three ways to find out the status of a transfer:

Webhooks:
It is important to have webhooks enabled on your Flutterwave dashboard. If you have webhooks enabled, we'll call your webhook URL with the transfer details when the transfer is completed or fails. Below is a sample webhook payload:

[SAMPLE WEBHOOK]

Callback
If you specified a callback_url in the initial request to create a mobile money transfer, we'll call that URL with the transfer details when the transfer is completed or fails.

Query Payout Status
You can manually check the status of a transfer by calling the retrieve a transfer endpoint using the transfer ID. After successfully initiating a payout, use the id returned in the data.id field of the create transfer response. Pass this id as a path parameter in a GET request to the retrieve a transfer endpoint.

curl --location 'https://api-sit.flutterwave.cloud/developersandbox/transfers/trf_RnB180t3HcuGui' \
--header 'X-Trace-Id: {{UNIQUE_TRACE_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{API_ACCESS_TOKEN}}'

You'll get a response like this:

{
    "status": "success",
    "message": "Transfer fetched",
    "data": {
        "id": "trf_RnB180t3HcuGui",
        "type": "cash_pickup",
        "action": "instant",
        "reference": "66ada47c-314b-4cff-bcf3-ce4f40d3738d",
        "status": "NEW",
        "narration": "An awesome payment",
        "source_currency": "EGP",
        "destination_currency": "NGN",
        "amount": {
            "value": 1234.56,
            "applies_to": "source_currency"
        },
        "fee": {
            "currency": "NGN",
            "value": 12.3456
        },
        "recipient": {
            "type": "cash_pickup",
            "name": {
                "first": "Bob",
                "middle": "The",
                "last": "Builder"
            },
            "currency": "NGN",
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "1234567890"
            },
            "phone": {
                "country_code": "234",
                "number": "9012345678"
            },
            "email": "[email protected]",
            "address": {
                "city": "Cool City",
                "country": "NG",
                "line1": "8B, Simple Street",
                "line2": "Awesome Apartments",
                "postal_code": "123456",
                "state": "Super State"
            },
            "cash_pickup": {
                "network": "GT_BANK"
            },
            "id": "rcc_djiYqp8reU"
        },
        "sender": {
            "id": "sdr_W3PJ4U5Z4b",
            "name": {
                "first": "Bob",
                "middle": "The",
                "last": "Builder"
            },
            "national_identification": {
                "type": "PASSPORT",
                "identifier": "1234567890"
            },
            "phone": {
                "country_code": "91",
                "number": "9012345678"
            },
            "date_of_birth": "1980-08-15",
            "email": "[email protected]",
            "address": {
                "city": "Cool City",
                "country": "EG",
                "line1": "7A, Simple Street",
                "line2": "Awesome Apartments",
                "postal_code": "123456",
                "state": "Super State"
            }
        },
        "meta": {},
        "created_datetime": "2025-01-28T15:40:27.650Z"
    }
}

{
    "status": "failed",
    "error": {
        "type": "TRANSFER_NOT_FOUND",
        "code": "301404",
        "message": "Transfer not found",
        "validation_errors": []
    }
}

Supported Networks

The following networks are currently supported for cash pickup:

CountryCurrencyNetworks
EgyptEGPFAWRY
NigeriaNGNGT_BANK, FIDELITY_BANK

Testing Cash Pickup Transfers

[REUSABLE CONTENT PLACED HERE]

Updated 2 months ago