> ## Documentation Index > Fetch the complete documentation index at: https://developer.notchpay.co/llms.txt > Use this file to discover all available pages before exploring further. # Transfers API > Send money to beneficiaries with the Notch Pay Transfers API # 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. ```bash theme={null} Authorization: YOUR_PUBLIC_KEY X-Grant: YOUR_PRIVATE_KEY ``` For API transfers, you must add your IP address to the whitelist in your dashboard at [https://business.notchpay.co/settings/developer/ips](https://business.notchpay.co/settings/developer/ips) ## The Transfer Object ```json Transfer Object theme={null} { "id": "trf_123456789", "reference": "ref_123456789", "amount": 5000, "currency": "XAF", "status": "complete", "beneficiary": "ben_123456789", "channel": "cm.mtn", "description": "Salary payment", "metadata": {}, "created_at": "2023-01-01T12:00:00Z", "completed_at": "2023-01-01T12:05:00Z" } ``` ### 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 ```bash theme={null} GET /transfers ``` Retrieve a list of transfers with pagination. ### 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) ```json theme={null} { "code": 200, "status": "OK", "message": "Transfers retrieved", "totals": 50, "last_page": 2, "current_page": 1, "selected": 30, "items": [ { "id": "trf_123456789", "reference": "ref_123456789", "amount": 5000, "currency": "XAF", "status": "complete", "beneficiary": "ben_123456789", "channel": "cm.mtn", "created_at": "2023-01-01T12:00:00Z" }, // More transfers... ] } ``` ```bash theme={null} POST /transfers ``` Initiate a new transfer to a beneficiary. ### 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) Beneficiary's name Beneficiary's email address Beneficiary's phone number Account number for bank transfers Bank code for bank transfers Beneficiary's country code 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 ```json With Existing Beneficiary theme={null} { "amount": 5000, "currency": "XAF", "beneficiary": "ben_123456789", "channel": "cm.mtn", "description": "Salary payment", "reference": "salary_jan_2023" } ``` ```json With New Beneficiary theme={null} { "amount": 5000, "currency": "XAF", "beneficiary_data": { "name": "John Doe", "phone": "+237670000000", "email": "john@example.com" }, "channel": "cm.mtn", "description": "Salary payment", "reference": "salary_jan_2023" } ``` ```json theme={null} { "status": "Accepted", "message": "Transfer initiated", "code": 201, "transfer": { "id": "trf_123456789", "reference": "salary_jan_2023", "amount": 5000, "currency": "XAF", "status": "pending", "beneficiary": "ben_123456789", "channel": "cm.mtn", "description": "Salary payment", "created_at": "2023-01-01T12:00:00Z" } } ``` After initiating a transfer, you should monitor its status using webhooks or by retrieving it periodically. ```bash theme={null} GET /transfers/{id} ``` Retrieve details of a specific transfer. ### Path Parameters ID or reference of the transfer to retrieve ```json theme={null} { "status": "Accepted", "message": "Transfer retrieved", "code": 202, "transfer": { "id": "trf_123456789", "reference": "salary_jan_2023", "amount": 5000, "currency": "XAF", "status": "complete", "beneficiary": "ben_123456789", "channel": "cm.mtn", "description": "Salary payment", "created_at": "2023-01-01T12:00:00Z", "completed_at": "2023-01-01T12:05:00Z" } } ``` ```bash theme={null} DELETE /transfers/{id} ``` Cancel a pending transfer. ### Path Parameters ID or reference of the transfer to cancel ```json theme={null} { "code": 202, "status": "Accepted", "message": "Transfer canceled successfully" } ``` You can only cancel transfers that are in the `pending` status. Transfers that are already `processing`, `complete`, or `failed` cannot be canceled. ## Bulk Transfers ```bash theme={null} POST /transfers/bulk ``` Initiate multiple transfers in a single request. ### Request Parameters Array of transfer objects Amount to transfer ID of an existing beneficiary Beneficiary details (if not using an existing beneficiary) Payment channel Unique reference Description Three-letter ISO currency code for all transfers Description for the bulk transfer ### Example Request ```json theme={null} { "currency": "XAF", "description": "January 2023 Payroll", "transfers": [ { "amount": 5000, "beneficiary": "ben_123456789", "channel": "cm.mtn", "reference": "salary_john_jan_2023" }, { "amount": 7000, "beneficiary_data": { "name": "Jane Doe", "phone": "+237670000001", "email": "jane@example.com" }, "channel": "cm.orange", "reference": "salary_jane_jan_2023" } ] } ``` ```json theme={null} { "status": "Accepted", "message": "Bulk transfer initiated", "code": 201, "bulk_transfer": { "id": "btrf_123456789", "description": "January 2023 Payroll", "currency": "XAF", "total_amount": 12000, "total_transfers": 2, "created_at": "2023-01-01T12:00:00Z", "transfers": [ { "id": "trf_123456789", "reference": "salary_john_jan_2023", "amount": 5000, "status": "pending" }, { "id": "trf_987654321", "reference": "salary_jane_jan_2023", "amount": 7000, "status": "pending" } ] } } ``` Bulk transfers are processed asynchronously. Individual transfers may succeed or fail independently. ```bash theme={null} GET /transfers/bulk/{id} ``` Retrieve details of a specific bulk transfer. ### Path Parameters ID of the bulk transfer to retrieve ```json theme={null} { "status": "Accepted", "message": "Bulk transfer retrieved", "code": 202, "bulk_transfer": { "id": "btrf_123456789", "description": "January 2023 Payroll", "currency": "XAF", "total_amount": 12000, "total_transfers": 2, "created_at": "2023-01-01T12:00:00Z", "transfers": [ { "id": "trf_123456789", "reference": "salary_john_jan_2023", "amount": 5000, "status": "complete", "beneficiary": "ben_123456789", "channel": "cm.mtn", "completed_at": "2023-01-01T12:05:00Z" }, { "id": "trf_987654321", "reference": "salary_jane_jan_2023", "amount": 7000, "status": "complete", "beneficiary": "ben_987654321", "channel": "cm.orange", "completed_at": "2023-01-01T12:07:00Z" } ] } } ``` ## Transfer Statuses Transfer has been initiated but not yet processed Transfer is being processed by the payment provider Transfer has been completed Transfer attempt failed 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: Triggered when a new transfer is created ```json theme={null} { "id": "evt_123456789", "type": "transfer.created", "data": { "id": "trf_123456789", "status": "pending" // Other transfer properties } } ``` Triggered when a transfer status changes to "complete" ```json theme={null} { "id": "evt_123456789", "type": "transfer.complete", "data": { "id": "trf_123456789", "status": "complete" // Other transfer properties } } ``` Triggered when a transfer fails ```json theme={null} { "id": "evt_123456789", "type": "transfer.failed", "data": { "id": "trf_123456789", "status": "failed", "failure_reason": "Insufficient balance" // Other transfer properties } } ``` See the [Webhooks API](/api-reference/webhooks) documentation for more information on setting up and handling webhooks. ## Error Handling Invalid request parameters This typically occurs when required parameters are missing or have invalid values. Invalid API key Check that you're using the correct API key and that it's properly included in the Authorization header. Missing or invalid grant key Transfer endpoints require the `X-Grant` header with your private key for additional security. Transfer not found The transfer ID or reference you provided doesn't exist or belongs to another account. Transfer cannot be processed This occurs when there's a business logic error, such as insufficient balance or invalid beneficiary details. ```json theme={null} { "code": 422, "status": "Unprocessable Entity", "message": "Insufficient balance to complete this transfer" } ``` **Solution**: Add funds to your Notch Pay account before attempting the transfer. ```json theme={null} { "code": 422, "status": "Unprocessable Entity", "message": "Validation failed", "errors": { "beneficiary": ["Beneficiary not found"] } } ``` **Solution**: Ensure the beneficiary exists and is correctly specified. ```json theme={null} { "code": 422, "status": "Unprocessable Entity", "message": "Validation failed", "errors": { "channel": ["Invalid payment channel"] } } ``` **Solution**: Use one of the supported payment channels for transfers. ## Best Practices Always store the transfer ID and reference in your database for future reference and reconciliation. Always verify the transfer status using the API before confirming to the recipient that funds have been sent. Set up webhooks for reliable transfer notifications, especially for asynchronous transfers like mobile money. Use unique, idempotent references for each transfer to prevent duplicate transfers and simplify reconciliation. Implement proper error handling for failed transfers, including user-friendly error messages and recovery options. Check your account balance before initiating large transfers or bulk transfers to ensure sufficient funds. ## Implementation Examples ```javascript Node.js theme={null} const axios = require('axios'); async function createTransfer() { try { const response = await axios.post('https://api.notchpay.co/transfers', { amount: 5000, currency: 'XAF', beneficiary: 'ben_123456789', channel: 'cm.mtn', description: 'Salary payment', reference: 'salary_jan_2023' }, { headers: { 'Authorization': 'YOUR_PUBLIC_KEY', 'X-Grant': 'YOUR_PRIVATE_KEY', 'Content-Type': 'application/json' } }); console.log('Transfer initiated:', response.data); return response.data.transfer.id; } catch (error) { console.error('Error creating transfer:', error.response?.data || error.message); throw error; } } ``` ```php PHP theme={null} 5000, 'currency' => 'XAF', 'beneficiary' => 'ben_123456789', 'channel' => 'cm.mtn', 'description' => 'Salary payment', 'reference' => 'salary_jan_2023' ]; curl_setopt_array($curl, [ CURLOPT_URL => 'https://api.notchpay.co/transfers', CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($data), CURLOPT_HTTPHEADER => [ 'Authorization: YOUR_PUBLIC_KEY', 'X-Grant: YOUR_PRIVATE_KEY', 'Content-Type: application/json' ] ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { throw new Exception("Error creating transfer: " . $err); } $result = json_decode($response, true); echo "Transfer initiated: " . $result['transfer']['id'] . "\n"; return $result['transfer']['id']; } ``` ```javascript Node.js theme={null} async function checkTransferStatus(transferId) { try { const response = await axios.get(`https://api.notchpay.co/transfers/${transferId}`, { headers: { 'Authorization': 'YOUR_PUBLIC_KEY', 'X-Grant': 'YOUR_PRIVATE_KEY' } }); console.log('Transfer status:', response.data.transfer.status); return response.data.transfer; } catch (error) { console.error('Error checking transfer:', error.response?.data || error.message); throw error; } } ``` ```php PHP theme={null} function checkTransferStatus($transferId) { $curl = curl_init(); curl_setopt_array($curl, [ CURLOPT_URL => "https://api.notchpay.co/transfers/{$transferId}", CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Authorization: YOUR_PUBLIC_KEY', 'X-Grant: YOUR_PRIVATE_KEY' ] ]); $response = curl_exec($curl); $err = curl_error($curl); curl_close($curl); if ($err) { throw new Exception("Error checking transfer: " . $err); } $result = json_decode($response, true); echo "Transfer status: " . $result['transfer']['status'] . "\n"; return $result['transfer']; } ``` ```javascript Node.js theme={null} async function createBulkTransfer() { try { const response = await axios.post('https://api.notchpay.co/transfers/bulk', { currency: 'XAF', description: 'January 2023 Payroll', transfers: [ { amount: 5000, beneficiary: 'ben_123456789', channel: 'cm.mtn', reference: 'salary_john_jan_2023' }, { amount: 7000, beneficiary_data: { name: 'Jane Doe', phone: '+237670000001', email: 'jane@example.com' }, channel: 'cm.orange', reference: 'salary_jane_jan_2023' } ] }, { headers: { 'Authorization': 'YOUR_PUBLIC_KEY', 'X-Grant': 'YOUR_PRIVATE_KEY', 'Content-Type': 'application/json' } }); console.log('Bulk transfer initiated:', response.data); return response.data.bulk_transfer.id; } catch (error) { console.error('Error creating bulk transfer:', error.response?.data || error.message); throw error; } } ``` ```javascript Node.js theme={null} async function checkBulkTransferStatus(bulkTransferId) { try { const response = await axios.get(`https://api.notchpay.co/transfers/bulk/${bulkTransferId}`, { headers: { 'Authorization': 'YOUR_PUBLIC_KEY', 'X-Grant': 'YOUR_PRIVATE_KEY' } }); console.log('Bulk transfer details:', response.data); // Check status of individual transfers response.data.bulk_transfer.transfers.forEach(transfer => { console.log(`Transfer ${transfer.id}: ${transfer.status}`); }); return response.data.bulk_transfer; } catch (error) { console.error('Error checking bulk transfer:', error.response?.data || error.message); throw error; } } ``` For more information about beneficiaries, see the [Beneficiaries API](/api-reference/beneficiaries) documentation.