Transfers API
The Transfers API allows you to send money to beneficiaries through various channels, such as mobile money accounts and bank accounts. Use these endpoints to programmatically initiate and manage transfers.
All transfer-related endpoints require both standard API key authentication and additional authentication using the
X-Grant header for enhanced security.For API transfers, you must add your IP address to the whitelist in your dashboard at https://business.notchpay.co/settings/developer/ips
The Transfer Object
Transfer Object Properties
API Endpoints
Bulk Transfers
Transfer Statuses
pending
Transfer has been initiated but not yet processed
processing
Transfer is being processed by the payment provider
complete
Transfer has been completed
failed
Transfer attempt failed
canceled
Transfer was canceled by the merchant
Webhooks for Transfers
To receive real-time notifications about transfer status changes, set up webhooks for the following events:
transfer.created
Triggered when a new transfer is created
transfer.complete
Triggered when a transfer status changes to “complete”
transfer.failed
Triggered when a transfer fails
Error Handling
Common Error Codes
Common Error Codes
Invalid request parametersThis typically occurs when required parameters are missing or have invalid values.
Invalid API keyCheck that you’re using the correct API key and that it’s properly included in the Authorization header.
Missing or invalid grant keyTransfer endpoints require the
X-Grant header with your private key for additional security.Transfer not foundThe transfer ID or reference you provided doesn’t exist or belongs to another account.
Best Practices
Store Transfer References
Always store the transfer ID and reference in your database for future reference and reconciliation.
Verify Transfer Status
Always verify the transfer status using the API before confirming to the recipient that funds have been sent.
Use Webhooks
Set up webhooks for reliable transfer notifications, especially for asynchronous transfers like mobile money.
Idempotent References
Use unique, idempotent references for each transfer to prevent duplicate transfers and simplify reconciliation.
Error Handling
Implement proper error handling for failed transfers, including user-friendly error messages and recovery options.
Balance Management
Check your account balance before initiating large transfers or bulk transfers to ensure sufficient funds.
Implementation Examples
- Single Transfer
- Bulk Transfer
1
Create a Transfer
2
Check Transfer Status
For more information about beneficiaries, see the Beneficiaries API documentation.