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 |
|---|---|
basa | Banking Association South Africa which represents bank accounts in South Africa |
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=NGN -H "Authorization: ******"const https = require("https");
const options = {
hostname: "api.paystack.co",
port: 443,
path: "/bank?currency=NGN",
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=NGN",
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 linkVerify the account number
You need to collect the destination account number and confirm that it’s valid. This is to ensure you don’t send money to the wrong or invalid account.
Use Account validation to confirm the account details before you create the recipient.
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": "basa",
"name": "John Doe",
"account_number": "0123456047",
"bank_code": "051001",
"currency": "ZAR"
}' \
-X POSTconst https = require("https");
const params = JSON.stringify({
"type": "basa",
"name": "John Doe",
"account_number": "0123456047",
"bank_code": "051001",
"currency": "ZAR"
});
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" => "basa",
"name" => "John Doe",
"account_number" => "0123456047",
"bank_code" => "051001",
"currency" => "ZAR",
];
$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"
}
}