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.

The Transfer Object

{
  "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

id
string
Unique identifier for the transfer
reference
string
Your custom reference for the transfer
amount
number
Amount of the transfer in the smallest currency unit
currency
string
Three-letter ISO currency code
status
string
Status of the transfer: pending, processing, complete, failed, canceled
beneficiary
string
ID of the beneficiary receiving the transfer
channel
string
Payment channel used for the transfer (e.g., cm.mtn, cm.orange)
description
string
Description of the transfer
metadata
object
Additional data attached to the transfer
created_at
string
Timestamp when the transfer was created
completed_at
string
Timestamp when the transfer was completed (if applicable)

API Endpoints

List All Transfers

GET /transfers
Retrieve a list of transfers with pagination.

Query Parameters

limit
integer
Number of items per page (default: 30, max: 100)
page
integer
Page number (default: 1)
Search by reference or beneficiary
status
string
Filter by status
channels
string
Filter by transfer channels (comma-separated)
date_start
string
Start date filter (format: YYYY-MM-DD)
date_end
string
End date filter (format: YYYY-MM-DD)

Create a Transfer

POST /transfers
Initiate a new transfer to a beneficiary.

Request Parameters

amount
number
required
Amount to transfer in the smallest currency unit
currency
string
required
Three-letter ISO currency code (e.g., XAF)
beneficiary
string
ID of an existing beneficiary (required if beneficiary details are not provided)
beneficiary_data
object
Beneficiary details (required if beneficiary is not provided)
channel
string
required
Payment channel to use for the transfer
description
string
Description of the transfer
reference
string
Unique reference for the transfer
metadata
object
Additional data to attach to the transfer

Example Requests

{
  "amount": 5000,
  "currency": "XAF",
  "beneficiary": "ben_123456789",
  "channel": "cm.mtn",
  "description": "Salary payment",
  "reference": "salary_jan_2023"
}

Retrieve a Transfer

GET /transfers/{id}
Retrieve details of a specific transfer.

Path Parameters

id
string
required
ID or reference of the transfer to retrieve

Cancel a Transfer

DELETE /transfers/{id}
Cancel a pending transfer.

Path Parameters

id
string
required
ID or reference of the transfer to cancel

Bulk Transfers

Create a Bulk Transfer

POST /transfers/bulk
Initiate multiple transfers in a single request.

Request Parameters

transfers
array
required
Array of transfer objects
currency
string
required
Three-letter ISO currency code for all transfers
description
string
Description for the bulk transfer

Example Request

{
  "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"
    }
  ]
}

Retrieve a Bulk Transfer

GET /transfers/bulk/{id}
Retrieve details of a specific bulk transfer.

Path Parameters

id
string
required
ID of the bulk transfer to retrieve

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

transfer.created

Triggered when a new transfer is created
{
  "id": "evt_123456789",
  "type": "transfer.created",
  "data": {
    "id": "trf_123456789",
    "status": "pending"
    // Other transfer properties
  }
}

transfer.complete

Triggered when a transfer status changes to “complete”
{
  "id": "evt_123456789",
  "type": "transfer.complete",
  "data": {
    "id": "trf_123456789",
    "status": "complete"
    // Other transfer properties
  }
}

transfer.failed

Triggered when a transfer fails
{
  "id": "evt_123456789",
  "type": "transfer.failed",
  "data": {
    "id": "trf_123456789",
    "status": "failed",
    "failure_reason": "Insufficient balance"
    // Other transfer properties
  }
}
See the Webhooks API documentation for more information on setting up and handling webhooks.

Error Handling

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

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;
  }
}
2

Check Transfer Status

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;
  }
}