Single Transfers
In a nutshell
With the Paystack Transfer API, you can send money to bank accounts and mobile money wallet
You can transfer money in four easy steps:
Before you begin!
To send money on Paystack, you need API keys to authenticate your transfers. You can find your keys on the Paystack Dashboard under Settings → API Keys & Webhooks.
Verify the account number
You need to collect the customer's account details and confirm that it’s valid before sending money. This is to ensure you don’t send money to the wrong or invalid account. Kindly check out the Verify Account Number page to learn about how to verify account details in different regions.
List banks and telcos
When creating a transfer recipient, you need the bank or telco details of the customer. The list bankAPI can be used to get all supported banks and telcos in a country.
To fetch a list of banks in a country, make a GET request passing the currency in the query parameter:
1curl https://api.paystack.co/bank?currency=NGN2-H "Authorization: Bearer YOUR_SECRET_KEY"3-X GET
1{2 "status": true,3 "message": "Banks retrieved",4 "data": [5 {6 "name": "Abbey Mortgage Bank",7 "slug": "abbey-mortgage-bank",8 "code": "801",9 "longcode": "",10 "gateway": null,11 "pay_with_bank": false,12 "active": true,13 "is_deleted": false,14 "country": "Nigeria",15 "currency": "NGN",16 "type": "nuban",17 "id": 174,18 "createdAt": "2020-12-07T16:19:09.000Z",19 "updatedAt": "2020-12-07T16:19:19.000Z"20 },21 ...22 ]23}
To fetch a list of supported telcos for mobile money, you can add currency and type in the query parameters for the list bankAPI:
1curl https://api.paystack.co/bank?currency=GHS&type=mobile_money2-H "Authorization: Bearer YOUR_SECRET_KEY"3-X GET
1{2 "status": true,3 "message": "Banks retrieved",4 "data": [5 {6 "name": "AirtelTigo",7 "slug": "atl-mobile-money",8 "code": "ATL",9 "longcode": "",10 "gateway": null,11 "pay_with_bank": false,12 "active": true,13 "is_deleted": null,14 "country": "Ghana",15 "currency": "GHS",16 "type": "mobile_money",17 "id": 29,18 "createdAt": "2018-03-29T12:54:59.000Z",19 "updatedAt": "2020-01-24T10:01:06.000Z"20 },21 {22 "name": "MTN",23 "slug": "mtn-mobile-money",24 "code": "MTN",25 "longcode": "",26 "gateway": null,27 "pay_with_bank": false,28 "active": true,29 "is_deleted": null,30 "country": "Ghana",31 "currency": "GHS",32 "type": "mobile_money",33 "id": 28,34 "createdAt": "2018-03-29T12:54:59.000Z",35 "updatedAt": "2019-10-22T11:04:46.000Z"36 },37 {38 "name": "Vodafone",39 "slug": "vod-mobile-money",40 "code": "VOD",41 "longcode": "",42 "gateway": null,43 "pay_with_bank": false,44 "active": true,45 "is_deleted": null,46 "country": "Ghana",47 "currency": "GHS",48 "type": "mobile_money",49 "id": 66,50 "createdAt": "2018-03-29T12:54:59.000Z",51 "updatedAt": "2019-10-22T11:05:08.000Z"52 }53 ]54}
Create a transfer recipient
Before sending money to an account, you need to create a transfer recipient with the customer’s account details.
The recipient type can take the following values based on country:
| Type | Currency | Description |
|---|---|---|
nuban | NGN | This means the Nigerian Uniform Bank Account Number. It represents bank accounts in Nigeria. |
mobile_money | GHS | Mobile Money or MoMo is an account tied to a mobile number |
basa | ZAR | This means the Banking Association South Africa. It represents bank accounts in South Africa |
authorization | All | This is a unique code that represents a customer’s card. We return an authorization code after a user makes a payment with their card. |
To create the transfer recipient, make a POST request to the transfer recipientAPI passing one of the following customer’s detail:
- Bank account
- Mobile money
- Authorization code
Bank account
Here, you specify the type based on your integration currency, then pass the customer’s details:
1curl https://api.paystack.co/transferrecipient2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "type": "nuban",5 "name": "John Doe",6 "account_number": "0001234567",7 "bank_code": "058",8 "currency": "NGN"9 }'10-X POST
1{2 "status": true,3 "message": "Transfer recipient created successfully",4 "data": {5 "active": true,6 "createdAt": "2020-05-13T13:59:07.741Z",7 "currency": "NGN",8 "domain": "test",9 "id": 6788170,10 "integration": 428626,11 "name": "John Doe",12 "recipient_code": "RCP_t0ya41mp35flk40",13 "type": "nuban",14 "updatedAt": "2020-05-13T13:59:07.741Z",15 "is_deleted": false,16 "details": {17 "authorization_code": null,18 "account_number": "0001234567",19 "account_name": null,20 "bank_code": "058",21 "bank_name": "Guaranty Trust Bank"22 }23 }24}
Mobile money
With mobile money, the bank_code takes the telco code as its value and the mobile number is passed to the account_number parameter:
1curl https://api.paystack.co/transferrecipient2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "type": "mobile_money",5 "name": "Abina Nana",6 "account_number": "0551234987",7 "bank_code": "MTN",8 "currency": "GHS"9 }'10-X POST
1{2 "status": true,3 "message": "Transfer recipient created successfully",4 "data": {5 "active": true,6 "createdAt": "2022-02-21T12:57:02.156Z",7 "currency": "GHS",8 "domain": "test",9 "id": 25753454,10 "integration": 519035,11 "name": "Abina Nana",12 "recipient_code": "RCP_u2tnoyjjvh95pzm",13 "type": "mobile_money",14 "updatedAt": "2022-02-21T12:57:02.156Z",15 "is_deleted": false,16 "isDeleted": false,17 "details": {18 "authorization_code": null,19 "account_number": "0551234987",20 "account_name": null,21 "bank_code": "MTN",22 "bank_name": "MTN"23 }24 }25}
Authorization 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:
1curl https://api.paystack.co/transferrecipient2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "type": "authorization",5 "name": "Revs Ore",6 "email": "revs@ore.com",7 "authorization_code": "AUTH_ncx8hews93"8 }'9-X POST
1{2 "status": true,3 "message": "Transfer recipient created successfully",4 "data": {5 "active": true,6 "createdAt": "2022-02-21T11:35:59.302Z",7 "currency": "NGN",8 "domain": "test",9 "email": "revs@ore.com",10 "id": 25747878,11 "integration": 463433,12 "name": "Revs Ore",13 "recipient_code": "RCP_wql6bj95bll7m6h",14 "type": "authorization",15 "updatedAt": "2022-02-21T11:35:59.302Z",16 "is_deleted": false,17 "isDeleted": false,18 "details": {19 "authorization_code": "AUTH_ncx8hews93",20 "account_number": null,21 "account_name": null,22 "bank_code": "057",23 "bank_name": "Zenith Bank"24 }25 }26}
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, kindly request the customer’s account details and follow the process to create a transfer recipient using a bank account.
The recipient_code from the data object is the unique identifier for this user and would be used to make transfers to the specified account. This code should be saved with the customer's records in your database.
Generate a transfer reference
A transfer reference is a unique identifier that lets you track, manage and reconcile each transfer request made on your integration. Transfer references allow you to prevent double crediting as you can retry a non-conclusive transfer rather than initiate a new request.
In order to take advantage of a transfer reference, you need to generate and provide it for every request. When you don’t provide a transfer reference, Paystack generates one for you but this defeats the purpose of the transfer reference.
We recommend generating a v4 UUID reference of no more than 100 characters. However, if you prefer implementing your own logic, you should ensure your reference contains at least 16 alphanumeric characters.
1{2 "source": "balance",3 "reason": "Savings",4 "amount": 30000,5 "reference": "your-unique-reference",6 "recipient": "RCP_1a25w1h3n0xctjg"7}
Initiate a transfer
To send money to a customer, you make a POST request to the Initate TransferAPI, passing the reference and recipient_code previously created.
Disabling OTP
When building a fully automated system, you might need to disable OTP for transfers. You can disable OTP from the Preferences tab on the Paystack Dashoard. You should uncheck the Confirm transfers before sending checkbox as shown in the image below.
1curl https://api.paystack.co/transfer2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "source": "balance",5 "amount": "37800",6 "reference": "your-unique-reference",7 "recipient": "RCP_t0ya41mp35flk40",8 "reason": "Holiday Flexing"9 }'10-X POST
1{2 "status": true,3 "message": "Transfer has been queued",4 "data": {5 "reference": "your-unique-reference",6 "integration": 428626,7 "domain": "test",8 "amount": 37800,9 "currency": "NGN",10 "source": "balance",11 "reason": "Holiday Flexing",12 "recipient": 6788170,13 "status": "success",14 "transfer_code": "TRF_fiyxvgkh71e717b",15 "id": 23070321,16 "createdAt": "2020-05-13T14:22:49.687Z",17 "updatedAt": "2020-05-13T14:22:49.687Z"18 }19}
When you send this request, if there are no errors, the response comes back with a pending status, while the transfer is being processed.
Retrying a transfer
If there is an error with the transfer request, kindly retry the transaction with the same reference in order to avoid double crediting. If a new reference is used, the transfer would be treated as a new request.
Test transfers always return success, because there is no processing involved. The live transfers processing usually take between a few seconds and a few minutes. When it's done processing, a notification is sent to your webhook URL.
Verify a transfer
When a transfer is initiated, it could take a few seconds or minutes to be processed. This is why we recommend relying on webhooks for verification as opposed to polling.
Receiving Notifications
In order to receive notifications, you need to implement a webhook URL and set the webhook URL on your Paystack Dashboard.
Once a transfer is processed, we send the final status of the transfer as a POST request to your webhook URL.
| Event | Description |
|---|---|
transfer.success | This is sent when the transfer is successful |
transfer.failed | This is sent when the transfer fails |
transfer.reversed | This is sent when we refund a previously debited amount for a transfer that couldn’t be completed |
- Transfer Successful
- Transfer Failed
- Transfer Reversed
1{2 "event": "transfer.success",3 "data": {4 "amount": 30000,5 "currency": "NGN",6 "domain": "test",7 "failures": null,8 "id": 37272792,9 "integration": {10 "id": 463433,11 "is_live": true,12 "business_name": "Boom Boom Industries NG"13 },14 "reason": "Have fun...",15 "reference": "1jhbs3ozmen0k7y5efmw",16 "source": "balance",17 "source_details": null,18 "status": "success",19 "titan_code": null,20 "transfer_code": "TRF_wpl1dem4967avzm",21 "transferred_at": null,22 "recipient": {23 "active": true,24 "currency": "NGN",25 "description": "",26 "domain": "test",27 "email": null,28 "id": 8690817,29 "integration": 463433,30 "metadata": null,31 "name": "Jack Sparrow",32 "recipient_code": "RCP_a8wkxiychzdzfgs",33 "type": "nuban",34 "is_deleted": false,35 "details": {36 "account_number": "0000000000",37 "account_name": null,38 "bank_code": "011",39 "bank_name": "First Bank of Nigeria"40 },41 "created_at": "2020-09-03T12:11:25.000Z",42 "updated_at": "2020-09-03T12:11:25.000Z"43 },44 "session": { "provider": null, "id": null },45 "created_at": "2020-10-26T12:28:57.000Z",46 "updated_at": "2020-10-26T12:28:57.000Z"47 }48}49
The response for a transfer also contains a unique transfer code to identify this transfer. You can use this code to call the Fetch TransferAPI endpoint to fetch status and details of the transfer anytime you want.
Authenticating with OTP
As an additional layer of security, a Paystack business owner might want to confirm a transfer by using the One Time Password (OTP) sent to their device.
If you have
OTP enabled on your Paystack Dashboard and you intiate a transfer via the API, you get a response with message: Transfer requires OTP to continue and data.status: otp
- Response
1{2 "status": true,3 "message": "Transfer requires OTP to continue",4 "data": {5 "reference": "x8beye1xud",6 "integration": 463433,7 "domain": "test",8 "amount": 20000,9 "currency": "NGN",10 "source": "balance",11 "reason": "E choke",12 "recipient": 10751086,13 "status": "otp",14 "transfer_code": "TRF_1aqrqhoomp0rjro",15 "id": 56506855,16 "createdAt": "2021-04-07T12:41:57.763Z",17 "updatedAt": "2021-04-07T12:41:57.763Z"18 }19}
When the business owner supplies the OTP sent to their mobile number (and email if enabled), the transfer can be completed by using our Finalize TransferAPI endpoint:
1curl https://api.paystack.co/transfer/finalize_transfer2-H "Authorization: Bearer YOUR_SECRET_KEY"3-H "Content-Type: application/json"4-d '{ "transfer_code": "TRF_vsyqdmlzble3uii", "otp": "928783" }'5-X POST
1{2 "status": true,3 "message": "Transfer has been queued",4 "data": {5 "reference": "on5hyz9poe",6 "integration": 428626,7 "domain": "test",8 "amount": 3794800,9 "currency": "NGN",10 "source": "balance",11 "reason": "Holiday Flexing",12 "recipient": 6788170,13 "status": "success",14 "transfer_code": "TRF_vsyqdmlzble3uii",15 "id": 23070321,16 "createdAt": "2020-05-13T14:22:49.687Z",17 "updatedAt": "2020-05-13T14:22:49.687Z"18 }19}