Sign in

Disbursements

Make your first transfer

View as Markdown

In a nutshell

Create a recipient, initiate a transfer, approve it with OTP if required, and confirm the final status with webhooks or the verify endpoint.

This tutorial shows you how to send a single transfer to a customer with Paystack. You will confirm the destination account, create a recipient, initiate the transfer, and confirm the final status.

Copy link1. Prerequisites

Before you start, make sure you have:

  • Your Paystack test secret key
  • A server that can make HTTPS requests to the Paystack API
  • A public webhook URL that Paystack can send events to

Set your secret key in your shell before making requests:

export PAYSTACK_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxxx"

Copy link2. Confirm the account details

Account resolution isn't available in Kenya. Confirm the M-PESA phone number with your customer before you create the recipient.

Copy link3. Create a transfer recipient

Create a mobile_money recipient with the customer's M-PESA number. Save the recipient_code from the response.

POSTapi.paystack.co/transferrecipient

curl https://api.paystack.co/transferrecipient \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "mobile_money",
    "name": "Wanjiru Kamau",
    "account_number": "0712345678",
    "bank_code": "MPESA",
    "currency": "KES"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "type": "mobile_money",
  "name": "Wanjiru Kamau",
  "account_number": "0712345678",
  "bank_code": "MPESA",
  "currency": "KES"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transferrecipient",
  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 = [
  "type" => "mobile_money",
  "name" => "Wanjiru Kamau",
  "account_number" => "0712345678",
  "bank_code" => "MPESA",
  "currency" => "KES",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transferrecipient",
  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 recipient created successfully",
  "data": {
    "active": true,
    "createdAt": "2022-02-21T12:57:02.156Z",
    "currency": "KES",
    "domain": "test",
    "id": 25753454,
    "integration": 519035,
    "name": "Wanjiru Kamau",
    "recipient_code": "RCP_u2tnoyjjvh95pzm",
    "type": "mobile_money",
    "updatedAt": "2022-02-21T12:57:02.156Z",
    "is_deleted": false,
    "isDeleted": false,
    "details": {
      "authorization_code": null,
      "account_number": "0712345678",
      "account_name": null,
      "bank_code": "MPESA",
      "bank_name": "M-PESA"
    }
  }
}

Store the recipient_code in your database so you can reuse it for future transfers to the same account. See Transfer recipients for every recipient type available in your market.

Copy link4. Initiate the transfer

Create the transfer from your Paystack balance. Send the amount in cents, so KES 1,000 becomes 100000. Generate a unique reference for each transfer so you can verify it and retry it safely.

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"
  }
}

Save the transfer_code and reference from the response. In live mode, the transfer may remain pending briefly while it is processed. Use webhooks to receive the final outcome.

Copy link5. Approve the transfer with OTP

If OTP is turned on for transfers, the response has message: Transfer requires OTP to continue and data.status: otp. Finalize the transfer with the transfer_code and the OTP sent to the business owner:

POSTapi.paystack.co/transfer/finalize_transfer

curl https://api.paystack.co/transfer/finalize_transfer \
  -H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transfer_code": "TRF_vsyqdmlzble3uii",
    "otp": "928783"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "transfer_code": "TRF_vsyqdmlzble3uii",
  "otp": "928783"
});

const options = {
  hostname: "api.paystack.co",
  port: 443,
  path: "/transfer/finalize_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 = [
  "transfer_code" => "TRF_vsyqdmlzble3uii",
  "otp" => "928783",
];

$curl = curl_init();
curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.paystack.co/transfer/finalize_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": {
    "reference": "acv_9ee55786-2323-4760-98e2-6380c9cb3f68",
    "integration": 463433,
    "domain": "test",
    "amount": 100000,
    "currency": "KES",
    "source": "balance",
    "reason": "Bonus for the week",
    "recipient": 56824902,
    "status": "success",
    "transfer_code": "TRF_vsyqdmlzble3uii",
    "id": 23070321,
    "createdAt": "2025-08-04T10:32:40.000Z",
    "updatedAt": "2025-08-04T10:32:40.000Z"
  }
}

If the status is pending or success, skip this step. To send transfers without OTP, see Transfer approval.

Copy link6. Handle the webhook

Listen for transfer.success, transfer.failed, and transfer.reversed on your webhook URL. Verify the x-paystack-signature header with an HMAC SHA512 hash of the raw request body before you trust the event.

Warning

Compute the signature from the raw request body exactly as Paystack sent it. Parsing and re-serializing the payload before verification can break the hash.

import crypto from 'node:crypto'
import express from 'express'

const app = express()

app.post('/webhooks/paystack', express.raw({ type: 'application/json' }), (req, res) => {
  const secret = process.env.PAYSTACK_SECRET_KEY
  const signature = req.get('x-paystack-signature')
  const hash = crypto
    .createHmac('sha512', secret)
    .update(req.body)
    .digest('hex')

  if (hash !== signature) {
    return res.status(401).send('Invalid signature')
  }

  const event = JSON.parse(req.body.toString('utf8'))

  switch (event.event) {
    case 'transfer.success':
      console.log('Transfer succeeded:', event.data.transfer_code)
      break
    case 'transfer.failed':
      console.log('Transfer failed:', event.data.transfer_code)
      break
    case 'transfer.reversed':
      console.log('Transfer reversed:', event.data.transfer_code)
      break
    default:
      break
  }

  return res.sendStatus(200)
})

Update your database with the final transfer status when one of those events arrives.

Copy link7. Verify the transfer

If you need the status without waiting for a webhook, verify the transfer with the reference you sent:

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
  }
}

Read the transfer status from data.status. The HTTP status code only tells you whether the API call succeeded.

Copy link8. Test it

In test mode, run the full flow with your Paystack test secret key.

Test transfers complete immediately, so you should see transfer.success without waiting.

After testing, repeat the same flow in live mode with a real account, a live secret key, and a production webhook URL.

Was this page helpful?