Transfers

The Transfers API allows you automate sending money to your customers.

Initiate Transfer

Send money to your customers.

Status of transfer object returned will be pending if OTP is disabled. In the event that an OTP is required, status will read otp.

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
source String	Where should we transfer from? Only `balance` for now
amount Integer	Amount to transfer in kobo if currency is `NGN` and pesewas if currency is `GHS`.
recipient String	Code for transfer recipient
reason String	The reason for the transfer
currency String	Specify the currency of the transfer. Defaults to NGN
reference String	If specified, the field should be a unique identifier (in lowercase) for the object. Only `-`,`_` and alphanumeric characters allowed.

1#!/bin/sh
2url="https://api.paystack.co/transfer"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "source": "balance", 
7  "reason": "Calm down", 
8  "amount":3794800, "recipient": "RCP_gx2wn530m0i3w3m"
9}'
10
11curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Transfer requires OTP to continue",
4  "data": {
5    "integration": 100073,
6    "domain": "test",
7    "amount": 3794800,
8    "currency": "NGN",
9    "source": "balance",
10    "reason": "Calm down",
11    "recipient": 28,
12    "status": "otp",
13    "transfer_code": "TRF_1ptvuv321ahaa7q",
14    "id": 14,
15    "createdAt": "2017-02-03T17:21:54.508Z",
16    "updatedAt": "2017-02-03T17:21:54.508Z"
17  }
18}

Finalize Transfer

Finalize an initiated transfer

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
transfer_code String	The transfer code you want to finalize
otp String	OTP sent to business phone to verify transfer

1#!/bin/sh
2url="https://api.paystack.co/transfer/finalize_transfer"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "transfer_code": "TRF_vsyqdmlzble3uii", 
7  "otp": "928783"
8}'
9
10curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "Transfer has been queued",
4  "data": {
5    "domain": "test",
6    "amount": 1000000,
7    "currency": "NGN",
8    "reference": "n7ll9pzl6b",
9    "source": "balance",
10    "source_details": null,
11    "reason": "E go better for you",
12    "status": "success",
13    "failures": null,
14    "transfer_code": "TRF_zuirlnr9qblgfko",
15    "titan_code": null,
16    "transferred_at": null,
17    "id": 529410,
18    "integration": 123460,
19    "recipient": 225204,
20    "createdAt": "2018-08-02T10:02:55.000Z",
21    "updatedAt": "2018-08-02T10:12:05.000Z"
22  }
23}

Initiate Bulk Transfer

Batch multiple transfers in a single request.

You need to disable the Transfers OTP requirement to use this endpoint.

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
source String	Where should we transfer from? Only `balance` for now
transfers Array	A list of transfer object. Each object should contain `amount`, `recipient`, and `reference`

1#!/bin/sh
2url="https://api.paystack.co/transfer/bulk"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4content_type="Content-Type: application/json"
5data='{ 
6  "currency": "NGN",
7  "source": "balance",
8  "transfers": [
9    {
10      "amount": 20000,
11      "reference": "588YtfftReF355894J",
12      "reason": "Why not?",
13      "recipient": "RCP_2tn9clt23s7qr28"
14    },
15    {
16      "amount": 30000,
17      "reference": "YunoTReF35e0r4J",
18      "reason": "Because I can",
19      "recipient": "RCP_1a25w1h3n0xctjg"
20    },
21    {
22      "amount": 40000,
23      "reason": "Coming right up",
24      "recipient": "RCP_aps2aibr69caua7"
25    }
26  ]
27}'
28
29curl "$url" -H "$authorization" -H "$content_type" -d "$data" -X POST

1{
2  "status": true,
3  "message": "3 transfers queued.",
4  "data": [
5    {
6      "reference": "588YtfftReF355894J",
7      "recipient": "RCP_2tn9clt23s7qr28",
8      "amount": 20000,
9      "transfer_code": "TRF_ful4rvpbiuaph4fo",
10      "currency": "NGN",
11      "status": "received"
12    },
13    {
14      "reference": "YunoTReF35e0r4J",
15      "recipient": "RCP_1a25w1h3n0xctjg",
16      "amount": 30000,
17      "transfer_code": "TRF_0lztrf3rox1rpbw1",
18      "currency": "NGN",
19      "status": "received"
20    },
21    {
22      "reference": "nm7kjk9gb-l5i4lr9wq3",
23      "recipient": "RCP_aps2aibr69caua7",
24      "amount": 40000,
25      "transfer_code": "TRF_hsk59k6loek7vlut",
26      "currency": "NGN",
27      "status": "received"
28    }
29  ]
30}

List Transfers

List the transfers made on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional 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 transfer you want to page. If not specify we use a default value of 1.
customer String	Filter by customer ID
from Datetime	A timestamp from which to start listing transfer e.g. `2016-09-24T00:00:05.000Z`, `2016-09-21`
to Datetime	A timestamp at which to stop listing transfer e.g. `2016-09-24T00:00:05.000Z`, `2016-09-21`

1#!/bin/sh
2url="https://api.paystack.co/transfer"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Transfers retrieved",
4  "data": [
5    {
6      "integration": 100073,
7      "recipient": {
8        "domain": "test",
9        "type": "nuban",
10        "currency": "NGN",
11        "name": "Flesh",
12        "details": {
13          "account_number": "olounje",
14          "account_name": null,
15          "bank_code": "044",
16          "bank_name": "Access Bank"
17        },
18        "description": "Eater",
19        "metadata": null,
20        "recipient_code": "RCP_2x5j67tnnw1t98k",
21        "active": true,
22        "id": 28,
23        "integration": 100073,
24        "createdAt": "2017-02-02T19:39:04.000Z",
25        "updatedAt": "2017-02-02T19:39:04.000Z"
26      },
27      "domain": "test",
28      "amount": 4400,
29      "currency": "NGN",
30      "source": "balance",
31      "source_details": null,
32      "reason": "Eater",
33      "status": "otp",
34      "failures": null,
35      "transfer_code": "TRF_1ptvuv321ahaa7q",
36      "id": 14,
37      "createdAt": "2017-02-03T17:21:54.000Z",
38      "updatedAt": "2017-02-03T17:21:54.000Z"
39    },
40    {
41      "integration": 100073,
42      "recipient": {
43        "domain": "test",
44        "type": "nuban",
45        "currency": "USD",
46        "name": "FleshUSD",
47        "details": {
48          "account_number": "1111111111",
49          "account_name": null,
50          "bank_code": "044",
51          "bank_name": "Access Bank"
52        },
53        "description": "EaterUSD",
54        "metadata": null,
55        "recipient_code": "RCP_bi84k5gguakuqmg",
56        "active": true,
57        "id": 22,
58        "integration": 100073,
59        "createdAt": "2017-01-23T16:52:48.000Z",
60        "updatedAt": "2017-01-23T16:52:48.000Z"
61      },
62      "domain": "test",
63      "amount": 3300,
64      "currency": "NGN",
65      "source": "balance",
66      "source_details": null,
67      "reason": "I love you",
68      "status": "otp",
69      "failures": null,
70      "transfer_code": "TRF_5pr8ypzb0htx0cn",
71      "id": 13,
72      "createdAt": "2017-01-23T16:55:59.000Z",
73      "updatedAt": "2017-01-23T16:55:59.000Z"
74    }
75  ],
76  "meta": {
77    "total": 2,
78    "skipped": 0,
79    "perPage": 50,
80    "page": 1,
81    "pageCount": 1
82  }
83}

Fetch Transfer

Get details of a transfer on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
id_or_code String	The transfer `ID` or `code` you want to fetch

1#!/bin/sh
2url="https://api.paystack.co/transfer/{id_or_code}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Transfer retrieved",
4  "data": {
5    "amount": 20000,
6    "createdAt": "2024-02-01T08:32:21.000Z",
7    "currency": "NGN",
8    "domain": "test",
9    "failures": null,
10    "id": 451930323,
11    "integration": 463433,
12    "reason": "Life go better for you",
13    "reference": "ge-bzrf8u8k2pygxrnqf",
14    "source": "balance",
15    "source_details": null,
16    "status": "success",
17    "titan_code": null,
18    "transfer_code": "TRF_fpmd0l8uta8upow7",
19    "request": 502643104,
20    "transferred_at": null,
21    "updatedAt": "2024-02-01T08:34:07.000Z",
22    "recipient": {
23      "active": true,
24      "createdAt": "2021-10-21T11:08:04.000Z",
25      "currency": "NGN",
26      "description": null,
27      "domain": "test",
28      "email": "jake@jill.com",
29      "id": 19643784,
30      "integration": 463433,
31      "metadata": {
32        "custom_fields": [
33          {
34            "display_name": "Branch Name",
35            "variable_name": "branchName",
36            "value": "funny place, Alabama"
37          },
38          {
39            "display_name": "Branch ID",
40            "variable_name": "branchID",
41            "value": "123"
42          }
43        ]
44      },
45      "name": "Abbey Baker",
46      "recipient_code": "RCP_rjs1szi4ax5hoeo",
47      "type": "nuban",
48      "updatedAt": "2023-03-29T08:39:39.000Z",
49      "is_deleted": false,
50      "isDeleted": false,
51      "details": {
52        "authorization_code": null,
53        "account_number": "0123456789",
54        "account_name": "Abbey Baker",
55        "bank_code": "058",
56        "bank_name": "Guaranty Trust Bank"
57      }
58    },
59    "session": {
60      "provider": null,
61      "id": null
62    },
63    "fee_charged": 0,
64    "fees_breakdown": null,
65    "gateway_response": null
66  }
67}

Verify Transfer

Verify the status of a transfer on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
reference String	Transfer reference

1#!/bin/sh
2url="https://api.paystack.co/transfer/verify/{reference}"
3authorization="Authorization: Bearer YOUR_SECRET_KEY"
4
5curl "$url" -H "$authorization" -X GET

1{
2  "status": true,
3  "message": "Transfer retrieved",
4  "data": {
5    "amount": 20000,
6    "createdAt": "2024-02-01T08:32:21.000Z",
7    "currency": "NGN",
8    "domain": "test",
9    "failures": null,
10    "id": 451930323,
11    "integration": 463433,
12    "reason": "Life go better for you",
13    "reference": "ge-bzrf8u8k2pygxrnqf",
14    "source": "balance",
15    "source_details": null,
16    "status": "success",
17    "titan_code": null,
18    "transfer_code": "TRF_fpmd0l8uta8upow7",
19    "request": 502643104,
20    "transferred_at": null,
21    "updatedAt": "2024-02-01T08:34:07.000Z",
22    "recipient": {
23      "active": true,
24      "createdAt": "2021-10-21T11:08:04.000Z",
25      "currency": "NGN",
26      "description": null,
27      "domain": "test",
28      "email": "jake@jill.com",
29      "id": 19643784,
30      "integration": 463433,
31      "metadata": {
32        "custom_fields": [
33          {
34            "display_name": "Branch Name",
35            "variable_name": "branchName",
36            "value": "funny place, Alabama"
37          },
38          {
39            "display_name": "Branch ID",
40            "variable_name": "branchID",
41            "value": "123"
42          }
43        ]
44      },
45      "name": "Abbey Baker",
46      "recipient_code": "RCP_rjs1szi4ax5hoeo",
47      "type": "nuban",
48      "updatedAt": "2023-03-29T08:39:39.000Z",
49      "is_deleted": false,
50      "isDeleted": false,
51      "details": {
52        "authorization_code": null,
53        "account_number": "0123456789",
54        "account_name": "Abbey Baker",
55        "bank_code": "058",
56        "bank_name": "Guaranty Trust Bank"
57      }
58    },
59    "session": {
60      "provider": null,
61      "id": null
62    },
63    "fee_charged": 0,
64    "fees_breakdown": null,
65    "gateway_response": null
66  }
67}