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
kepssKenya Electronic Payment and Settlement System which represents bank accounts in Kenya
mobile_moneyMobile money accounts tied to a mobile number
mobile_money_businessPaybill and business Till numbers
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=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;
?>
{
  "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 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 POST
const 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;
?>
{
  "status": true,
  "message": "Transfer recipient created successfully",
  "data": {
    "active": true,
    "createdAt": "2020-05-13T13:59:07.741Z",
    "currency": "KES",
    "domain": "test",
    "id": 6788170,
    "integration": 428626,
    "name": "John Doe",
    "recipient_code": "RCP_gd9vgag7n5lr5ix",
    "type": "kepss",
    "updatedAt": "2020-05-13T13:59:07.741Z",
    "is_deleted": false,
    "details": {
      "authorization_code": null,
      "account_number": "0123456047456",
      "account_name": null,
      "bank_code": "68",
      "bank_name": "Equity Bank Kenya Ltd"
    }
  }
}

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;
?>
{
  "status": true,
  "message": "Banks retrieved",
  "data": [
    {
      "name": "Airtel Kenya",
      "slug": "airtel-ke",
      "code": "ATL_KE",
      "active": true,
      "country": "Kenya",
      "currency": "KES",
      "type": "mobile_money",
      "id": 819
    },
    {
      "name": "M-PESA",
      "slug": "m-pesa",
      "code": "MPESA",
      "active": true,
      "country": "Kenya",
      "currency": "KES",
      "type": "mobile_money",
      "id": 231
    },
    {
      "name": "Telkom Kenya",
      "slug": "telkom-ke",
      "code": "97",
      "active": true,
      "country": "Kenya",
      "currency": "KES",
      "type": "mobile_money",
      "id": 808
    }
  ]
}

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

Copy linkM-PESA Paybill and Till numbers

M-PESA has several bank_code options:

  1. MPESA for individual Mpesa users
  2. MPPAYBILL for Paybill numbers and requires additional information during disbursement
  3. MPTILL for 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 POST
const 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;
?>
{
  "status": true,
  "message": "Transfer recipient created successfully",
  "data": {
    "active": true,
    "createdAt": "2024-11-28T09:28:50.000Z",
    "currency": "KES",
    "description": null,
    "domain": "test",
    "email": null,
    "id": 92176030,
    "integration": 845995,
    "metadata": null,
    "name": "Till Transfer",
    "recipient_code": "RCP_5vl8b2yma7xdnjp",
    "type": "mobile_money_business",
    "updatedAt": "2024-11-28T09:28:50.000Z",
    "is_deleted": false,
    "isDeleted": false,
    "details": {
      "authorization_code": null,
      "account_number": "247247",
      "account_name": null,
      "bank_code": "MPTILL",
      "bank_name": "M-PESA Till"
    }
  }
}

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?