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
Unique identifier for the transfer
Your custom reference for the transfer
Amount of the transfer in the smallest currency unit
Three-letter ISO currency code
Status of the transfer:
pending
, processing
, complete
, failed
, canceled
ID of the beneficiary receiving the transfer
Payment channel used for the transfer (e.g.,
cm.mtn
, cm.orange
)Description of the transfer
Additional data attached to the transfer
Timestamp when the transfer was created
Timestamp when the transfer was completed (if applicable)
API Endpoints
List All Transfers
Query Parameters
Number of items per page (default: 30, max: 100)
Page number (default: 1)
Search by reference or beneficiary
Filter by status
Filter by transfer channels (comma-separated)
Start date filter (format: YYYY-MM-DD)
End date filter (format: YYYY-MM-DD)
Create a Transfer
Request Parameters
Amount to transfer in the smallest currency unit
Three-letter ISO currency code (e.g., XAF)
ID of an existing beneficiary (required if beneficiary details are not provided)
Beneficiary details (required if
beneficiary
is not provided)Payment channel to use for the transfer
Description of the transfer
Unique reference for the transfer
Additional data to attach to the transfer
Example Requests
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.
Transfer cannot be processedThis occurs when there’s a business logic error, such as insufficient balance or invalid beneficiary details.
Specific Transfer Errors
Specific Transfer Errors
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
1
Create a Transfer
2
Check Transfer Status
For more information about beneficiaries, see the Beneficiaries API documentation.