Disbursements
Make your first transfer
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 POSTconst 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;
?>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 POSTconst 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;
?>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 POSTconst 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;
?>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;
?>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.