Transfers Recipients

The Transfer Recipients API allows you create and manage beneficiaries that you send money to.

Create Transfer Recipient

Creates a new recipient. A duplicate account number will lead to the retrieval of the existing record.

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
type
String
Recipient Type. It could be one of: nuban, ghipss, mobile_money or basa
name
String
The recipient's name according to their account registration.
account_number
String
Required for all recipient types except authorization
bank_code
String
Required for all recipient types except authorization. You can get the list of Bank Codes by calling the List Banks endpoint.
description
String
A description for this recipient
currency
String
Currency for the account receiving the transfer
authorization_code
String
An authorization code from a previous transaction
metadata
Object
Store additional information about your recipient in a structured format, JSON
Show optional parameters
POST/transferrecipient
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "type": "nuban",
7 "name": "Tolu Robert",
8 "account_number": "01000000010",
9 "bank_code": "058",
10 "currency": "NGN"
11}'
12
13curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Transfer recipient created successfully",
4 "data": {
5 "active": true,
6 "createdAt": "2021-11-05T11:27:53.131Z",
7 "currency": "NGN",
8 "domain": "test",
9 "id": 20317609,
10 "integration": 463433,
11 "name": "Tolu Robert",
12 "recipient_code": "RCP_m7ljkv8leesep7p",
13 "type": "nuban",
14 "updatedAt": "2021-11-05T11:27:53.131Z",
15 "is_deleted": false,
16 "details": {
17 "authorization_code": null,
18 "account_number": "01000000010",
19 "account_name": "Tolu Robert",
20 "bank_code": "058",
21 "bank_name": "Guaranty Trust Bank"
22 }
23 }
24}

Bulk Create Transfer Recipient

Create multiple transfer recipients in batches. A duplicate account number will lead to the retrieval of the existing record.

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Body Parameters
batch
Array
A list of transfer recipient object. Each object should contain type, name, and bank_code. Any Create Transfer Recipient param can also be passed.
POST/transferrecipient/bulk
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient/bulk"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "batch": [
7 {
8 "type":"nuban",
9 "name" : "Habenero Mundane",
10 "account_number": "0123456789",
11 "bank_code": "033",
12 "currency": "NGN"
13 },
14 {
15 "type":"nuban",
16 "name" : "Soft Merry",
17 "account_number": "98765432310",
18 "bank_code": "50211",
19 "currency": "NGN"
20 }]
21}'
22
23curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Recipients added successfully",
4 "data": {
5 "success": [
6 {
7 "domain": "test",
8 "name": "Habenero Mundane",
9 "type": "nuban",
10 "description": "",
11 "integration": 463433,
12 "currency": "NGN",
13 "metadata": null,
14 "details": {
15 "account_number": "0123456789",
16 "account_name": null,
17 "bank_code": "033",
18 "bank_name": "United Bank For Africa"
19 },
20 "recipient_code": "RCP_wh5k8r4vzuh5c94",
21 "active": true,
22 "id": 10152540,
23 "isDeleted": false,
24 "createdAt": "2020-11-09T10:12:48.213Z",
25 "updatedAt": "2020-11-09T10:12:48.213Z"
26 },
27 {
28 "domain": "test",
29 "name": "Soft Merry",
30 "type": "nuban",
31 "description": "",
32 "integration": 463433,
33 "currency": "NGN",
34 "metadata": null,
35 "details": {
36 "account_number": "98765432310",
37 "account_name": null,
38 "bank_code": "50211",
39 "bank_name": "Kuda Bank"
40 },
41 "recipient_code": "RCP_yu1kkyktoljnczg",
42 "active": true,
43 "id": 10152541,
44 "isDeleted": false,
45 "createdAt": "2020-11-09T10:12:48.213Z",
46 "updatedAt": "2020-11-09T10:12:48.213Z"
47 }
48 ],
49 "errors": []
50 }
51}

List Transfer Recipients

List transfer recipients available on your integration

Headers
authorization
String
Set value to Bearer SECRET_KEY
Query Parameters
perPage
Integer
Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page
Integer
Specify exactly what page you want to retrieve. If not specify we use a default value of 1.
from
Datetime
A timestamp from which to start listing transfer recipients e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
to
Datetime
A timestamp at which to stop listing transfer recipients e.g. 2016-09-24T00:00:05.000Z, 2016-09-21
Show optional parameters
GET/transferrecipient
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Recipients retrieved",
4 "data": [
5 {
6 "domain": "test",
7 "type": "nuban",
8 "currency": "NGN",
9 "name": "Flesh",
10 "details": {
11 "account_number": "01000000000",
12 "account_name": null,
13 "bank_code": "044",
14 "bank_name": "Access Bank"
15 },
16 "metadata": {
17 "job": "Eater"
18 },
19 "recipient_code": "RCP_2x5j67tnnw1t98k",
20 "active": true,
21 "id": 28,
22 "createdAt": "2017-02-02T19:39:04.000Z",
23 "updatedAt": "2017-02-02T19:39:04.000Z"
24 },
25 {
26 "integration": 100073,
27 "domain": "test",
28 "type": "nuban",
29 "currency": "NGN",
30 "name": "Flesh",
31 "details": {
32 "account_number": "0100000010",
33 "account_name": null,
34 "bank_code": "044",
35 "bank_name": "Access Bank"
36 },
37 "metadata": {},
38 "recipient_code": "RCP_1i2k27vk4suemug",
39 "active": true,
40 "id": 27,
41 "createdAt": "2017-02-02T19:35:33.000Z",
42 "updatedAt": "2017-02-02T19:35:33.000Z"
43 }
44 ],
45 "meta": {
46 "total": 2,
47 "skipped": 0,
48 "perPage": 50,
49 "page": 1,
50 "pageCount": 1
51 }
52}

Fetch Transfer Recipient

Fetch the details of a transfer recipient

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
id_or_code
String
An ID or code for the recipient whose details you want to receive.
GET/transferrecipient/:id_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient/{id_or_code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Recipient retrieved",
4 "data": {
5 "domain": "test",
6 "type": "nuban",
7 "currency": "NGN",
8 "name": "Flesh",
9 "details": {
10 "account_number": "01000000000",
11 "account_name": null,
12 "bank_code": "044",
13 "bank_name": "Access Bank"
14 },
15 "metadata": {
16 "job": "Eater"
17 },
18 "recipient_code": "RCP_2x5j67tnnw1t98k",
19 "active": true,
20 "id": 28,
21 "createdAt": "2017-02-02T19:39:04.000Z",
22 "updatedAt": "2017-02-02T19:39:04.000Z"
23 }
24}

Update Transfer Recipient

Update transfer recipients available on your integration

Headers
authorization
String
Set value to Bearer SECRET_KEY
content-type
String
Set value to application/json
Path Parameters
id_or_code
String
Transfer Recipient's ID or code
Body Parameters
name
String
A name for the recipient
email
String
Email address of the recipient
Show optional parameters
PUT/transferrecipient/:id_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient/{id_or_code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{
6 "name": "Rick Sanchez"
7}'
8
9curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X PUT
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Recipient updated",
4 "data": {
5 "type": "nuban",
6 "name": "Rick Sanchez",
7 "metadata": {
8 "job": "Flesh Eater",
9 "retired": true
10 },
11 "domain": "test",
12 "details": {
13 "account_number": "01000000010",
14 "account_name": null,
15 "bank_code": "044",
16 "bank_name": "Access Bank"
17 },
18 "currency": "NGN",
19 "recipient_code": "RCP_1i2k27vk4suemug",
20 "active": true,
21 "id": 27,
22 "createdAt": "2017-02-02T19:35:33.686Z",
23 "updatedAt": "2017-02-02T19:35:33.686Z"
24 }
25}

Delete Transfer Recipient

Delete a transfer recipient (sets the transfer recipient to inactive)

Headers
authorization
String
Set value to Bearer SECRET_KEY
Path Parameters
id_or_code
String
An ID or code for the recipient who you want to delete.
DELETE/transferrecipient/:id_or_code
cURL
1#!/bin/sh
2url="https://api.paystack.co/transferrecipient/{id_or_code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X DELETE
Sample Response
200 Ok
1{
2 "status": true,
3 "message": "Transfer recipient set as inactive"
4}