Disbursements
Transfer recipients
In a nutshell
Create and manage recipients that you can send money to.
A transfer recipient is a beneficiary created on your integration to allow you send money. Before sending money from your integration, you need to collect the customer’s details to create a transfer recipient.
Paystack supports the following recipient types:
| Type | Description |
|---|---|
kepss | Kenya Electronic Payment and Settlement System which represents bank accounts in Kenya |
mobile_money | Mobile money accounts tied to a mobile number |
mobile_money_business | Paybill and business Till numbers |
authorization | A card authorization code from a previous payment |
To create the transfer recipient, make a POST request to the Transfer RecipientAPI endpoint passing the customer’s details for the recipient type.
Copy linkBank account
When creating a transfer recipient with a bank account, you need to collect the customer’s bank details. Typically, the account number and associated bank should suffice, however, more details could be required for account verification. You should design your user interface to allow the collection of the necessary details based on your business operation.
Copy linkList banks
When creating your user interface (UI) to collect the user’s bank details, you’ll need to populate the UI with a list of banks available via the List bankAPI endpoint.
To fetch a list of banks in a country, make a GET request passing the currency in the query parameter:
GETapi.paystack.co/bank
curl https://api.paystack.co/bank?currency=KES -H "Authorization: ******"const https = require("https");
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/bank?currency=KES",
method: "GET",
headers: {
Authorization: "******",
},
};
const req = https.request(options, (res) => {
let data = "";
res.on("data", (chunk) => {
data += chunk;
});
res.on("end", () => {
console.log(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/bank?currency=KES",
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: ******",
"Cache-Control: no-cache",
),
));
$response = curl_exec($curl);
echo $response;
?>Copy linkCreate recipient
With the verification completed, you can pass the customer’s bank details and the recipient type to the Create Transfer recipientAPI endpoint:
POSTapi.paystack.co/transferrecipient
curl https://api.paystack.co/transferrecipient \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "kepss",
"name": "John Doe",
"account_number": "0123456047456",
"bank_code": "68",
"currency": "KES"
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"type": "kepss",
"name": "John Doe",
"account_number": "0123456047456",
"bank_code": "68",
"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" => "kepss",
"name" => "John Doe",
"account_number" => "0123456047456",
"bank_code" => "68",
"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;
?>Copy linkMobile money
Feature availability
This feature is currently available to businesses in Ghana and Kenya.
Mobile money allows a merchant send money to a customer’s mobile number. To start with, you need to collect the customer’s phone number and telco. To fetch the supported telcos, call List BanksAPI with your currency and type set to mobile_money:
GETapi.paystack.co/bank
curl "https://api.paystack.co/bank?currency=KES&type=mobile_money" \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY"const https = require("https");
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/bank?currency=KES&type=mobile_money",
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/bank?currency=KES&type=mobile_money",
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;
?>With the customer’s mobile number, you can then create a recipient by using the telco code as the bank_code and the mobile number as the account_number:
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;
?>Copy linkM-PESA Paybill and Till numbers
M-PESA has several bank_code options:
MPESAfor individual Mpesa usersMPPAYBILLfor Paybill numbers and requires additional information during disbursementMPTILLfor business Till numbers
The recipient type for Paybill and Till numbers is mobile_money_business.
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_business",
"name": "Till Transfer",
"bank_code": "MPTILL",
"account_number": "247247",
"currency": "KES"
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"type": "mobile_money_business",
"name": "Till Transfer",
"bank_code": "MPTILL",
"account_number": "247247",
"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_business",
"name" => "Till Transfer",
"bank_code" => "MPTILL",
"account_number" => "247247",
"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;
?>Copy linkAuthorization code
An authorization code is returned after a successful card payment by a customer. Combining the authorization code with the email address used for payment, you can create a transfer recipient:
POSTapi.paystack.co/transferrecipient
curl https://api.paystack.co/transferrecipient \
-H "Authorization: Bearer $PAYSTACK_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "authorization",
"name": "Revs Ore",
"email": "[email protected]",
"authorization_code": "AUTH_ncx8hews93"
}' \
-X POST
const https = require("https");
const params = JSON.stringify({
"type": "authorization",
"name": "Revs Ore",
"email": "[email protected]",
"authorization_code": "AUTH_ncx8hews93"
});
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" => "authorization",
"name" => "Revs Ore",
"email" => "[email protected]",
"authorization_code" => "AUTH_ncx8hews93",
];
$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;
?>
Account Number Association
If an account number isn’t associated with the authorization code, we return a
response with a message: Account details not found for this authorization.
If you get this error, request the customer's account details and
follow the process to create a transfer recipient using a bank account.
Copy linkSave the recipient code
The recipient_code in the data object of the response is the unique identifier for the customer and would be used to make transfers to the specified account. This code should be saved with the customer’s records in your database.
{
"status": true,
"message": "Transfer recipient created successfully",
"data": {
"active": true,
"name": "Revs Ore",
"recipient_code": "RCP_wql6bj95bll7m6h",
"type": "authorization"
}
}