Transfer Recipient

A collection of endpoints for creating and managing beneficiaries that you send money to

Copy link List Transfer Recipients

List transfer recipients available on your integration

Query Parameters

use_cursorboolean
A flag to indicate if cursor based pagination should be used
nextstring
An alphanumeric value returned for every cursor based retrieval, used to retrieve the next set of data
previousstring
An alphanumeric value returned for every cursor based retrieval, used to retrieve the previous set of data
per_pageinteger
The number of records to fetch per request
pageinteger
The offset to retrieve data from

Response

200
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
5 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredinteger
pagerequiredinteger
pageCountrequiredinteger
GET/transferrecipient
curl https://api.paystack.co/transferrecipient \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.list({
  use_cursor: true,
  next: "NEXT"
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.list({
  use_cursor: true,
  next: "NEXT"
})
puts response.data
Response
{
  "status": true,
  "message": "Recipients retrieved",
  "data": [
    {
      "domain": "test",
      "type": "nuban",
      "currency": "NGN",
      "name": "Flesh",
      "details": {
        "account_number": "01000000000",
        "account_name": null,
        "bank_code": "044",
        "bank_name": "Access Bank"
      },
      "metadata": {
        "job": "Eater"
      },
      "recipient_code": "RCP_2x5j67tnnw1t98k",
      "active": true,
      "id": 28,
      "createdAt": "2017-02-02T19:39:04.000Z",
      "updatedAt": "2017-02-02T19:39:04.000Z"
    },
    {
      "integration": 100073,
      "domain": "test",
      "type": "nuban",
      "currency": "NGN",
      "name": "Flesh",
      "details": {
        "account_number": "0100000010",
        "account_name": null,
        "bank_code": "044",
        "bank_name": "Access Bank"
      },
      "metadata": {},
      "recipient_code": "RCP_1i2k27vk4suemug",
      "active": true,
      "id": 27,
      "createdAt": "2017-02-02T19:35:33.000Z",
      "updatedAt": "2017-02-02T19:35:33.000Z"
    }
  ],
  "meta": {
    "total": 2,
    "skipped": 0,
    "perPage": 50,
    "page": 1,
    "pageCount": 1
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Create Transfer Recipient

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

Request Body

typerequiredstring
Recipient Type
Enumnubanghipssmobile_moneybasaauthorization
namerequiredstring
The recipient's name according to their account registration.
account_numberrequiredstring
Recipient's bank account number
bank_coderequiredstring
Recipient's bank code. You can get the list of Bank Codes by calling the List Banks endpoint
descriptionstring
A description for this recipient
currencystring
Currency for the account receiving the transfer
authorization_codestring
An authorization code from a previous transaction
metadataobject
JSON object of custom data

Response

201
statusrequiredboolean
messagerequiredstring
datarequiredobject
16 object properties
activerequiredboolean
createdAtrequiredstring
currencyrequiredstring
descriptionrequiredstring
domainrequiredstring
emailrequiredstring
idrequiredinteger
integrationrequiredinteger
metadataobject
namerequiredstring
recipient_coderequiredstring
typerequiredstring
updatedAtrequiredstring
is_deletedrequiredboolean
isDeletedrequiredboolean
detailsrequiredobject
5 object properties
authorization_coderequiredstring
account_numberrequiredstring
account_namerequiredstring
bank_coderequiredstring
bank_namerequiredstring
POST/transferrecipient
curl https://api.paystack.co/transferrecipient \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "nuban",
    "name": "Smith Taplo",
    "account_number": "01000000010",
    "bank_code": "058"
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.create({
  type: "nuban",
  name: "Smith Taplo",
  account_number: "01000000010",
  bank_code: "058"
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.create({
  type: "nuban",
  name: "Smith Taplo",
  account_number: "01000000010",
  bank_code: "058"
})
puts response.data
Response
{
  "status": true,
  "message": "Request successful",
  "data": {
    "active": true,
    "createdAt": "string",
    "currency": "string",
    "description": "string",
    "domain": "string",
    "email": "string",
    "id": 0,
    "integration": 0,
    "metadata": {},
    "name": "string",
    "recipient_code": "string",
    "type": "string",
    "updatedAt": "string",
    "is_deleted": true,
    "isDeleted": true,
    "details": {
      "authorization_code": "string",
      "account_number": "string",
      "account_name": "string",
      "bank_code": "string",
      "bank_name": "string"
    }
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Bulk Create Transfer Recipient

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

Request Body

batchrequiredarray[object]
A list of transfer recipient object.

Response

200Sucessful response
statusrequiredboolean
messagerequiredstring
datarequiredobject
2 object properties
successrequiredarray[object]
errorsrequiredarray[object]
POST/transferrecipient/bulk
curl https://api.paystack.co/transferrecipient/bulk \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": []
  }' \
  -X POST
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.bulk({
  batch: []
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.bulk({
  batch: []
})
puts response.data
Response
{
  "status": true,
  "message": "Recipients added successfully",
  "data": {
    "success": [
      {
        "domain": "test",
        "name": "Habenero Mundane",
        "type": "nuban",
        "description": "",
        "integration": 463433,
        "currency": "NGN",
        "metadata": null,
        "details": {
          "account_number": "0123456789",
          "account_name": null,
          "bank_code": "033",
          "bank_name": "United Bank For Africa"
        },
        "recipient_code": "RCP_wh5k8r4vzuh5c94",
        "active": true,
        "id": 10152540,
        "isDeleted": false,
        "createdAt": "2020-11-09T10:12:48.213Z",
        "updatedAt": "2020-11-09T10:12:48.213Z"
      },
      {
        "domain": "test",
        "name": "Soft Merry",
        "type": "nuban",
        "description": "",
        "integration": 463433,
        "currency": "NGN",
        "metadata": null,
        "details": {
          "account_number": "98765432310",
          "account_name": null,
          "bank_code": "50211",
          "bank_name": "Kuda Bank"
        },
        "recipient_code": "RCP_yu1kkyktoljnczg",
        "active": true,
        "id": 10152541,
        "isDeleted": false,
        "createdAt": "2020-11-09T10:12:48.213Z",
        "updatedAt": "2020-11-09T10:12:48.213Z"
      }
    ],
    "errors": []
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Fetch Transfer recipient

Fetch the details of a transfer recipient

Path Parameters

coderequiredstring
Transfer recipient code

Response

200Successful response
statusrequiredboolean
messagerequiredstring
datarequiredobject
17 object properties
integrationrequiredinteger
domainrequiredstring
typerequiredstring
currencyrequiredstring
namerequiredstring
detailsrequiredobject
4 object properties
account_numberrequiredstring
account_namerequiredstring
bank_coderequiredstring
bank_namerequiredstring
descriptionrequiredstring
metadataobject
recipient_coderequiredstring
activerequiredboolean
recipient_accountrequiredstring
institution_coderequiredstring
emailrequiredstring
idrequiredinteger
isDeletedrequiredboolean
createdAtrequiredstring
updatedAtrequiredstring
GET/transferrecipient/{code}
curl https://api.paystack.co/transferrecipient/RCP_5ap8rcimmcj8lbi \
  -H "Authorization: Bearer YOUR_SECRET_KEY"
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.fetch("RCP_5ap8rcimmcj8lbi");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.fetch("RCP_5ap8rcimmcj8lbi")
puts response.data
Response
{
  "status": true,
  "message": "Recipient retrieved",
  "data": {
    "domain": "test",
    "type": "nuban",
    "currency": "NGN",
    "name": "Flesh",
    "details": {
      "account_number": "01000000000",
      "account_name": null,
      "bank_code": "044",
      "bank_name": "Access Bank"
    },
    "metadata": {
      "job": "Eater"
    },
    "recipient_code": "RCP_2x5j67tnnw1t98k",
    "active": true,
    "id": 28,
    "createdAt": "2017-02-02T19:39:04.000Z",
    "updatedAt": "2017-02-02T19:39:04.000Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Update Transfer Recipient

Update the details of a transfer recipient

Path Parameters

coderequiredstring
Transfer recipient code

Request Body

namestring
Recipient's name
emailstring
Recipient's email address

Response

200Successful response
statusrequiredboolean
messagerequiredstring
PUT/transferrecipient/{code}
curl https://api.paystack.co/transferrecipient/RCP_5ap8rcimmcj8lbi \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NAME",
    "email": "[email protected]"
  }' \
  -X PUT
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.update("RCP_5ap8rcimmcj8lbi", {
  name: "NAME",
  email: "[email protected]"
});
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.update("RCP_5ap8rcimmcj8lbi", {
  name: "NAME",
  email: "[email protected]"
})
puts response.data
Response
{
  "status": true,
  "message": "Recipient updated",
  "data": {
    "type": "nuban",
    "name": "Rick Sanchez",
    "metadata": {
      "job": "Flesh Eater",
      "retired": true
    },
    "domain": "test",
    "details": {
      "account_number": "01000000010",
      "account_name": null,
      "bank_code": "044",
      "bank_name": "Access Bank"
    },
    "currency": "NGN",
    "recipient_code": "RCP_1i2k27vk4suemug",
    "active": true,
    "id": 27,
    "createdAt": "2017-02-02T19:35:33.686Z",
    "updatedAt": "2017-02-02T19:35:33.686Z"
  }
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}

Copy link Delete Transfer Recipient

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

Path Parameters

coderequiredstring
Transfer recipient code

Response

200Successful response
statusrequiredboolean
messagerequiredstring
DELETE/transferrecipient/{code}
curl https://api.paystack.co/transferrecipient/RCP_5ap8rcimmcj8lbi \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -X DELETE
import { Paystack } from "@paystack/paystack-sdk";

const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });

const response = await paystack.transferRecipient.delete("RCP_5ap8rcimmcj8lbi");
console.log(response.data);
require "paystack"

paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))

response = paystack.transfer_recipient.delete_("RCP_5ap8rcimmcj8lbi")
puts response.data
Response
{
  "status": true,
  "message": "Transfer recipient set as inactive"
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}
{
  "status": false,
  "message": "An error occurred",
  "meta": {
    "nextStep": "string"
  },
  "type": "string",
  "code": "validation_error",
  "errorCodeMappingNotFound": true
}