Sign in

Disbursements

Transfer recipients

View as Markdown

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:

TypeDescription
nubanNigerian Uniform Bank Account Number which represents bank accounts in Nigeria
authorizationA 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;
?>
{
  "status": true,
  "message": "Banks retrieved",
  "data": [
    {
      "id": 1,
      "code": "001",
      "name": "Guaranty Trust Bank",
      "longname": "Guaranty Trust Bank plc",
      "pay_with_bank": true,
      "active": true,
      "country_id": 1,
      "is_deleted": 0,
      "createdAt": "2016-07-14T10:04:45.000Z"
    },
    {
      "id": 2,
      "code": "003",
      "name": "United Bank for Africa",
      "longname": "United Bank for Africa plc",
      "pay_with_bank": true,
      "active": true,
      "country_id": 1,
      "is_deleted": 0,
      "createdAt": "2016-07-14T10:04:45.000Z"
    }
  ]
}

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 Resolve account number to confirm the account name 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": "nuban",
    "name": "John Doe",
    "account_number": "1000000001",
    "bank_code": "057",
    "currency": "NGN"
  }' \
  -X POST
const https = require("https");

const params = JSON.stringify({
  "type": "nuban",
  "name": "John Doe",
  "account_number": "1000000001",
  "bank_code": "057",
  "currency": "NGN"
});

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" => "nuban",
  "name" => "John Doe",
  "account_number" => "1000000001",
  "bank_code" => "057",
  "currency" => "NGN",
];

$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": "2020-05-13T13:59:07.741Z",
    "currency": "NGN",
    "domain": "test",
    "id": 6788170,
    "integration": 428626,
    "name": "John Doe",
    "recipient_code": "RCP_gd9vgag7n5lr5ix",
    "type": "nuban",
    "updatedAt": "2020-05-13T13:59:07.741Z",
    "is_deleted": false,
    "details": {
      "authorization_code": null,
      "account_number": "1000000001",
      "account_name": null,
      "bank_code": "057",
      "bank_name": "Zenith Bank"
    }
  }
}

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;
?>
{
  "status": true,
  "message": "Transfer recipient created successfully",
  "data": {
    "active": true,
    "createdAt": "2022-02-21T11:35:59.302Z",
    "currency": "NGN",
    "domain": "test",
    "email": "[email protected]",
    "id": 25747878,
    "integration": 463433,
    "name": "Revs Ore",
    "recipient_code": "RCP_wql6bj95bll7m6h",
    "type": "authorization",
    "updatedAt": "2022-02-21T11:35:59.302Z",
    "is_deleted": false,
    "isDeleted": false,
    "details": {
      "authorization_code": "AUTH_ncx8hews93",
      "account_number": null,
      "account_name": null,
      "bank_code": "057",
      "bank_name": "Zenith Bank"
    }
  }
}

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"
  }
}
Was this page helpful?