Sign in

Disbursements

Send money to a single recipient

View as Markdown

In a nutshell

Create a recipient, initiate one transfer, complete OTP approval when needed, and confirm the final status.

You can transfer money in four easy steps:

Before you begin!

To send money on Paystack, you need API keys to authenticate your transfers. You can find your keys on the Paystack Dashboard under Developers → API configuration.

Copy linkCreate a transfer recipient

A transfer recipient is a beneficiary on your integration that you can send money to. Before sending money to your customer, you need to collect their details first, then use their details to create a transfer recipient. The Recipients page lists the recipient types available in your market.

The recipient_code from the data object is the unique identifier for a user and would be used to make transfers to that customer This code should be saved with the customer's records in your database.

Copy linkGenerate a transfer reference

A transfer reference is a unique identifier that lets you track, manage and reconcile each transfer request made on your integration. Transfer references allow you to prevent double crediting as you can retry a non-conclusive transfer rather than initiate a new request.

In order to take advantage of a transfer reference, you need to generate and provide it for every request. We recommend generating a v4 UUID reference of no more than 50 characters. However, here are the constraints to take note of regardless of the logic you decide to implement:

  1. The reference can only contain lowercase letters (a-z), digits (0-9) and these symbols: underscore (_) and dash (_)
  2. The minimum length should be 16 characters
  3. The maximum length should be 50 characters
  4. You can prepend or append special identifiers to the reference to further reduce the chances of collision
{
  "source": "balance",
  "reason": "Bonus for the week",
  "amount": 100000,
  "recipient": "RCP_gd9vgag7n5lr5ix",
  "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68"
}

Copy linkInitiate a transfer

To send money to a customer, you make a POST request to the Initiate TransferAPI endpoint, passing the reference and recipient_code previously created.

If OTP is turned on for transfers, the transfer waits for approval. To approve it or turn OTP off for automated transfers, see Transfer approval.

POSTapi.paystack.co/transfer

curl https://api.paystack.co/transfer \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "balance",
    "amount": 100000,
    "currency": "KES",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "recipient": "RCP_gd9vgag7n5lr5ix",
    "reason": "Bonus for the week"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "source": "balance",
  "amount": 100000,
  "currency": "KES",
  "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
  "recipient": "RCP_gd9vgag7n5lr5ix",
  "reason": "Bonus for the week"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transfer",
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
    "Content-Type": "application/json",
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.write(params);
req.end();
<?php
$fields = [
  "source" => "balance",
  "amount" => 100000,
  "currency" => "KES",
  "reference" => "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
  "recipient" => "RCP_gd9vgag7n5lr5ix",
  "reason" => "Bonus for the week",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transfer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode($fields),
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Content-Type: application/json",
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Transfer has been queued",
  "data": {
    "transfersessionid": [],
    "transfertrials": [],
    "domain": "test",
    "amount": 100000,
    "currency": "KES",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "source": "balance",
    "source_details": null,
    "reason": "Bonus for the week",
    "status": "success",
    "failures": null,
    "transfer_code": "TRF_v5tip3zx8nna9o78",
    "titan_code": null,
    "transferred_at": null,
    "id": 860703114,
    "integration": 463433,
    "request": 1068439313,
    "recipient": 56824902,
    "createdAt": "2025-08-04T10:32:40.000Z",
    "updatedAt": "2025-08-04T10:32:40.000Z"
  }
}

When you send this request, if there are no errors, the response comes back with a pending status, while the transfer is being processed.

Retrying a transfer

If there is an error with the transfer request, you should retry the transaction with the same reference to avoid double crediting. If a new reference is used, the transfer would be treated as a new request.

Test transfers always return success, because there is no processing involved. The live transfers processing usually take between a few seconds and a few minutes. When it's done processing, a notification is sent to your webhook URL.

Copy linkVerify a transfer

When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.

Copy linkVerify via webhooks

Receiving Notifications

In order to receive notifications, you need to implement a webhook URL and set the webhook URL in Developers → API configuration on your Paystack Dashboard.

Once a transfer is processed, we send the final status of the transfer as a POST request to your webhook URL.

EventDescription
transfer.successThis is sent when the transfer is successful
transfer.failedThis is sent when the transfer fails
transfer.reversedThis is sent when we refund a previously debited amount for a transfer that couldn’t be completed
{
  "event": "transfer.success",
  "data": {
    "id": 860703114,
    "amount": 100000,
    "currency": "KES",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "transfer_code": "TRF_v5tip3zx8nna9o78",
    "status": "success",
    "reason": "Bonus for the week",
    "source": "balance",
    "recipient": {
      "recipient_code": "RCP_gd9vgag7n5lr5ix",
      "name": "John Doe",
      "type": "kepss",
      "currency": "KES",
      "details": {
        "account_number": "0123456047456",
        "bank_code": "68",
        "bank_name": "Equity Bank Kenya Ltd"
      }
    },
    "createdAt": "2025-08-04T10:32:40.000Z",
    "updatedAt": "2025-08-04T10:32:45.000Z"
  }
}
{
  "event": "transfer.failed",
  "data": {
    "id": 860703114,
    "amount": 100000,
    "currency": "KES",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "transfer_code": "TRF_v5tip3zx8nna9o78",
    "status": "failed",
    "reason": "Bonus for the week",
    "source": "balance",
    "recipient": {
      "recipient_code": "RCP_gd9vgag7n5lr5ix",
      "name": "John Doe",
      "type": "kepss",
      "currency": "KES",
      "details": {
        "account_number": "0123456047456",
        "bank_code": "68",
        "bank_name": "Equity Bank Kenya Ltd"
      }
    },
    "createdAt": "2025-08-04T10:32:40.000Z",
    "updatedAt": "2025-08-04T10:32:45.000Z"
  }
}
{
  "event": "transfer.reversed",
  "data": {
    "id": 860703114,
    "amount": 100000,
    "currency": "KES",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "transfer_code": "TRF_v5tip3zx8nna9o78",
    "status": "reversed",
    "reason": "Bonus for the week",
    "source": "balance",
    "recipient": {
      "recipient_code": "RCP_gd9vgag7n5lr5ix",
      "name": "John Doe",
      "type": "kepss",
      "currency": "KES",
      "details": {
        "account_number": "0123456047456",
        "bank_code": "68",
        "bank_name": "Equity Bank Kenya Ltd"
      }
    },
    "createdAt": "2025-08-04T10:32:40.000Z",
    "updatedAt": "2025-08-04T10:32:45.000Z"
  }
}

Copy linkVerify via polling

If you prefer to use an endpoint to verify the status of the transfer, you can call the Verify Transfer endpoint with the transfer reference you used for the request:

GETapi.paystack.co/transfer/verify/acv_9ee55786-2323-4760-98e2-6380c9cb3f68

curl https://api.paystack.co/transfer/verify/acv_9ee55786-2323-4760-98e2-6380c9cb3f68 \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY"
const https = require("https");

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transfer/verify/acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
  },
};

const req = https.request(options, (res) => {
  let data = "";
  res.on("data", (chunk) => {
    data += chunk;
  });
  res.on("end", () => {
    console.log(res.statusCode, JSON.parse(data));
  });
});

req.on("error", (error) => {
  console.error(error);
});

req.end();
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transfer/verify/acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
    "Authorization: Bearer " . getenv("PAYSTACK_SECRET_KEY"),
    "Cache-Control: no-cache",
  ),
));
$response = curl_exec($curl);
echo curl_getinfo($curl, CURLINFO_HTTP_CODE) . " " . $response;
?>
{
  "status": true,
  "message": "Transfer retrieved",
  "data": {
    "amount": 100000,
    "createdAt": "2025-08-04T10:32:40.000Z",
    "currency": "KES",
    "domain": "test",
    "failures": null,
    "id": 860703114,
    "integration": 463433,
    "reason": "Bonus for the week",
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "source": "balance",
    "source_details": null,
    "status": "success",
    "titan_code": null,
    "transfer_code": "TRF_v5tip3zx8nna9o78",
    "request": 1068439313,
    "transferred_at": null,
    "updatedAt": "2025-08-04T10:32:40.000Z",
    "recipient": {
      "active": true,
      "createdAt": "2023-07-11T15:42:27.000Z",
      "currency": "KES",
      "description": "",
      "domain": "test",
      "email": null,
      "id": 56824902,
      "integration": 463433,
      "metadata": null,
      "name": "John Doe",
      "recipient_code": "RCP_gd9vgag7n5lr5ix",
      "type": "kepss",
      "updatedAt": "2023-07-11T15:42:27.000Z",
      "is_deleted": false,
      "isDeleted": false,
      "details": {
        "authorization_code": null,
        "account_number": "0123456047456",
        "account_name": null,
        "bank_code": "68",
        "bank_name": "Equity Bank Kenya Ltd"
      }
    },
    "session": {
      "provider": null,
      "id": null
    },
    "gateway_response": null
  }
}

Verification status

The HTTP status code you get from the API response indicates the status of the API call and not the status of the transfer. The status of the transfer is in the data object of the response, i.e data.status. The status of a transfer should only be updated with the data.status value when you get a 200 status code. Check out the how transfers work page to learn more about handling transfer statuses.

Copy linkTroubleshooting

When building or maintaining your transfer integration, keep the following integration checklist in mind:

  • Ensure you have enough funds in your Paystack balance to carry out your transfers
  • Ensure you are sending amount in the smallest denomination of your currency
  • Ensure you have generated a transfer reference
  • Implement a webhook URL to receive updates
  • Ensure the recipient details are valid
  • Ensure there are no long running tasks in your approval URL

Despite checking all items in the checklist, things might still not work as they should. If you encounter any issue with your integration, the first step is to check the status of the transfer.

Typically, issues occur during the validation phase or when there are multiple occurrences of an unsuccessful status. Validation errors come with descriptive messages and solutions are easy to fix. Here are some errors and solutions to them:

ErrorResolution
Your reference contains illegal special charactersEnsure that the reference contains lowercase alphanumeric characters and the only special characters are hyphen (-) and underscore (_)
Your balance is not enough to fulfil this requestTop up your Paystack balance and try again
Sorry, we can't make the transfer to this recipient at the momentThe customer should reach out to the bank to resolve the issues with their account
Account closedThe customer should reach out to the bank if they didn't close the account
Bank code is invalidEnsure that you're passing the correct bank code. Use the list bank endpoint to get the list of all available banks and their corresponding bank codes

A transfer request could also be stuck in an unsuccessful status. Here's how to handle unsuccessful status:

  1. pending: A transfer might remain in this state for a long time if there is an issue communicating with the recipient's bank. This is one of the reasons why we use queues. We keep retrying through different channels till we've exhausted all options and the transfer fails. You can also check our status page to confirm that there's no incident.
  2. blocked: This happens when your server fails to respond to approval request within a few seconds. If multiple transfers keep returning this status, check your approval logic to ensure that there are no long running tasks.
  3. abandoned: A high rate of abandoned transfers means there's an OTP issue. OTP is either not being delivered or you aren't using the OTP within 30 minutes. If you are going to use OTP for approval, we recommend turning on both email and phone channels. This is to increase the chances of OTP delivery.
Was this page helpful?