Transfers

Terminology Note: In Notch Pay, the term “Transfers” refers to sending money to recipients (payouts, withdrawals, and fund distributions). This is the official terminology used throughout the platform and API.

Notch Pay Transfers allows you to distribute funds to recipients through various payment channels. This feature is essential for businesses that need to send money to customers, employees, vendors, or other beneficiaries.

Overview

Notch Pay Transfers enables you to effortlessly send money to your recipients. This simplifies tasks like:

Processing refunds to customers
Paying salaries or commissions to employees
Distributing funds to vendors or suppliers
Sending rebates or rewards to customers
Making payouts to marketplace sellers
Withdrawing funds to your own accounts

Key Benefits

Send money to mobile money accounts
Process transfers in multiple currencies
Automate recurring payouts
Track transfer status in real-time
Receive webhook notifications for transfers

How Transfers Work

The transfer process follows these steps:

Create a Recipient: First, create a transfer recipient with the necessary details (phone number, name, etc.)
Initiate Transfer: Send a transfer request to the Notch Pay API with the recipient ID, amount, and other details
Processing: Notch Pay processes the transfer through the appropriate payment network
Status Updates: Receive status updates via webhooks or API calls as the transfer progresses
Completion: The recipient receives the funds in their account

Transfer Types

Mobile Money Transfers

Mobile money transfers allow you to send funds directly to mobile money accounts. This is one of the most popular transfer methods in Africa due to the widespread adoption of mobile money services.

Supported Mobile Money Providers

MTN Mobile Money (Cameroon): Send money to MTN Mobile Money accounts in Cameroon
Orange Money (Cameroon): Send money to Orange Money accounts in Cameroon
Generic Mobile Money (Cameroon): Automatically route transfers to the appropriate mobile money provider based on the recipient’s phone number

Mobile Money Transfer Example

// Create a mobile money recipient
fetch('https://api.notchpay.co/recipients', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    channel: 'cm.mtn', // MTN Cameroon
    name: 'John Doe',
    phone: '+237600000000',
    account_number: '+237600000000'
  })
})
.then(response => response.json())
.then(data => {
  const recipientId = data.recipient.id;

  // Initiate transfer to the recipient
  return fetch('https://api.notchpay.co/transfers', {
    method: 'POST',
    headers: {
      'Authorization': 'YOUR_PUBLIC_KEY',
      'X-Grant': 'YOUR_PRIVATE_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      recipient: recipientId,
      amount: 5000,
      currency: 'XAF',
      description: 'Payment for services'
    })
  });
})
.then(response => response.json())
.then(data => {
  console.log('Transfer initiated:', data.transfer);
})

Bank Transfers

Bank transfers allow you to send money directly to bank accounts. This method is useful for larger transactions or when the recipient prefers to receive funds in their bank account. Note: Bank transfers functionality is coming soon to Notch Pay.

Creating Transfer Recipients

Before initiating a transfer, you need to create a recipient (also known as a beneficiary) who will receive the funds. This step collects and validates the recipient’s information.

Terminology Note: In Notch Pay, the terms “recipient” and “beneficiary” are used interchangeably to refer to the person or entity receiving funds through a transfer.

Types of Recipients/Beneficiaries

Notch Pay offers two main types of recipients for transfers:

Standard Recipients: Created via API or dashboard, these are used for regular transfers to mobile money accounts and other payment methods.
Payout Accounts: High-privilege accounts created exclusively through the Notch Pay dashboard. These accounts have elevated permissions for outgoing transactions and are typically used for:
- Regular business partners
- Trusted vendors
- Company accounts
- High-volume payment recipients

Payout Accounts provide additional security and streamlined processing for frequent or high-value transfers. They cannot be created or accessed via the API and must be managed through the Notch Pay dashboard.

Supported Recipient Types

For standard recipients, Notch Pay currently supports the following types:

cm.mtn: MTN Cameroon Mobile Money
cm.orange: Orange Cameroon Mobile Money
cm.mobile: Generic Cameroon Mobile Money (automatically routes to MTN or Orange)

Creating a Recipient via API

To create a standard transfer recipient, make a POST request to the Recipient API:

// Create a transfer recipient
fetch('https://api.notchpay.co/recipients', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    type: 'cm.mtn', // or 'cm.orange', 'cm.mobile'
    name: 'John Doe',
    email: 'john@example.com', // Optional
    phone: '+237600000000',
    metadata: { // Optional
      customer_id: '12345',
      department: 'sales'
    }
  })
})
.then(response => response.json())
.then(data => {
  const recipientId = data.recipient.id;
  console.log('Recipient created with ID:', recipientId);
})

Managing Standard Recipients

You can retrieve, update, or delete standard recipients as needed:

// Retrieve a recipient
fetch('https://api.notchpay.co/recipients/rcp_123456789', {
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log(data.recipient);
})

// Update a recipient
fetch('https://api.notchpay.co/recipients/rcp_123456789', {
  method: 'PUT',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'John Smith',
    email: 'john.smith@example.com'
  })
})
.then(response => response.json())
.then(data => {
  console.log('Recipient updated:', data.recipient);
})

// Delete a recipient
fetch('https://api.notchpay.co/recipients/rcp_123456789', {
  method: 'DELETE',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Recipient deleted:', data.deleted);
})

Payout Accounts

Payout Accounts are high-privilege recipients that can only be created and managed through the Notch Pay dashboard. These accounts provide enhanced security and streamlined processing for frequent or high-value transfers.

Creating Payout Accounts

To create a Payout Account:

Log in to your Notch Pay Business dashboard
Navigate to Transfers > Payout Accounts
Click Create Payout Account
Fill in the required information:
- Account name
- Account holder’s name
- Phone number
- Email address (optional)
- Payment method (Mobile Money, Bank Account)
- Payment details (depending on the method)
Click Create Account

Benefits of Payout Accounts

Payout Accounts offer several advantages over standard recipients:

Enhanced Security: Additional verification and security measures for high-value transfers
Streamlined Processing: Faster processing times for transfers to trusted recipients
Detailed History: Comprehensive transaction history and reporting
Higher Limits: Potentially higher transfer limits for verified accounts
Batch Transfers: Easily include in batch transfers for payroll and mass disbursements

When to Use Payout Accounts

Payout Accounts are ideal for:

Regular Business Partners: Vendors, suppliers, or partners you pay regularly
Employee Payroll: Staff members receiving regular salary payments
Company Accounts: Your own accounts for withdrawals or internal transfers
High-Volume Recipients: Recipients who receive frequent or large transfers

Security Considerations

Since Payout Accounts have elevated privileges, they include additional security measures:

Creation only through the secure dashboard (not via API)
Additional verification steps during setup
Option to require approval for transfers above certain thresholds
Detailed audit logs of all activities
Ability to temporarily disable accounts when not in use

Initiating Transfers

Once you have created a recipient (either a standard recipient via API or a Payout Account via dashboard), you can initiate a transfer to send money to them.

Transfer Request

To initiate a transfer, make a POST request to the Transfers API. This works for both standard recipients and Payout Accounts:

// Initiate a transfer
fetch('https://api.notchpay.co/transfers', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    recipient: 'rcp_123456789', // Recipient ID
    amount: 5000, // Amount in the smallest currency unit (e.g., 5000 = 5000 XAF)
    currency: 'XAF',
    description: 'Salary payment for June 2023', // Optional
    metadata: { // Optional
      invoice_id: 'INV-123',
      payment_type: 'salary'
    }
  })
})
.then(response => response.json())
.then(data => {
  const transferId = data.transfer.reference;
  console.log('Transfer initiated with ID:', transferId);
  console.log('Transfer status:', data.transfer.status);
})

Transfer Process

When you initiate a transfer, it goes through several stages:

Request Validation: The system validates your request to ensure it includes all necessary information
Transfer Creation: A formal transfer record is created in the system
Approval Checks: Depending on the amount or policies, the transfer may require approval
Processing: The transfer is sent to the payment processor for execution

Transfer Response

The API response includes details about the transfer:

{
  "status": "Accepted",
  "message": "Transfer initialized",
  "code": 201,
  "transfer": {
    "amount": 5000,
    "amount_total": 5100, // Amount including fees
    "sandbox": false,
    "fee": 100, // Transfer fee
    "converted_amount": 5000,
    "beneficiary": "rcp_123456789",
    "description": "Salary payment for June 2023",
    "reference": "po.rKI4eJBYkebUAKj5stAHeCCnLyV8NZy9", // Transfer ID
    "trxref": null,
    "statement": null,
    "status": "sent", // Current status
    "currency": "XAF",
    "geo": "127.0.0.1",
    "created_at": "2023-06-17T21:35:51.000000Z"
  }
}

Transfer Status

Transfers can have the following statuses:

Status	Description
`pending`	The transfer has been initiated but not yet processed
`sent`	The transfer has been sent to the payment processor
`processing`	The transfer is being processed by the payment network
`complete`	The transfer has been completely completed
`failed`	The transfer has failed
`reversed`	The transfer has been reversed

Checking Transfer Status

You can check the status of a transfer at any time:

// Check transfer status
fetch('https://api.notchpay.co/transfers/po.rKI4eJBYkebUAKj5stAHeCCnLyV8NZy9', {
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'X-Grant': 'YOUR_PRIVATE_KEY'
  }
})
.then(response => response.json())
.then(data => {
  console.log('Transfer status:', data.transfer.status);
})

Webhook Notifications

To receive real-time updates about transfers, set up webhooks for the following events:

transfer.pending: A transfer has been initiated
transfer.processing: A transfer is being processed
transfer.complete: A transfer has been completely completed
transfer.failed: A transfer has failed
transfer.reversed: A transfer has been reversed

Example webhook payload for a complete transfer:

{
  "event": "transfer.complete",
  "data": {
    "reference": "po.rKI4eJBYkebUAKj5stAHeCCnLyV8NZy9",
    "amount": 5000,
    "fee": 100,
    "currency": "XAF",
    "status": "complete",
    "beneficiary": "rcp_123456789",
    "description": "Salary payment for June 2023",
    "created_at": "2023-06-17T21:35:51.000000Z",
    "metadata": {
      "invoice_id": "INV-123",
      "payment_type": "salary"
    }
  }
}

Transfer Fees

Transfers may incur fees depending on the amount, currency, and recipient type. The fee is automatically calculated and included in the transfer response. For example, if you initiate a transfer of 5,000 XAF and the fee is 100 XAF, the total amount deducted from your account will be 5,100 XAF, while the recipient will receive 5,000 XAF.

Best Practices

Security

API Key Security: Keep your API keys secure and never expose them in client-side code
Verify Webhook Signatures: Always verify webhook signatures to prevent fraud
Use HTTPS: Always use HTTPS for all API requests and webhook endpoints
Implement Proper Authentication: Secure your endpoints with proper authentication

Transfer Management

Idempotent Requests: Use unique references for each transfer to prevent duplicate transfers
Error Handling: Implement proper error handling for failed transfers
Reconciliation: Regularly reconcile transfers with your internal records
Logging: Keep detailed logs of all transfers for auditing purposes

User Experience

Clear Communication: Clearly communicate transfer status to your users
Estimated Delivery Time: Provide estimated delivery times for transfers
Notification System: Implement a notification system to keep users informed about their transfers
Error Messages: Provide clear error messages when transfers fail

Troubleshooting

Common Issues

Insufficient Funds: Ensure your Notch Pay account has sufficient funds to cover the transfer amount and fees
Invalid Recipient: Verify that the recipient information is correct and the recipient exists
Network Issues: Some transfers may fail due to issues with the recipient’s mobile money network
Validation Errors: Check that all required fields are provided and in the correct format

Support

If you encounter issues with transfers:

Check the API Reference for detailed parameter documentation
Contact our support team for assistance
Join our developer community to connect with other developers

Next Steps

Bulk Transfers - Send money to multiple recipients at once
Beneficiaries Management - Create and manage your recipients
Webhooks - Set up webhooks for transfer notifications
API Reference - Detailed API documentation for transfers

Beneficiaries

​Overview

​Key Benefits

​How Transfers Work

​Transfer Types

​Mobile Money Transfers

​Supported Mobile Money Providers

​Mobile Money Transfer Example

​Bank Transfers

​Creating Transfer Recipients

​Types of Recipients/Beneficiaries

​Supported Recipient Types

​Creating a Recipient via API

​Managing Standard Recipients

​Payout Accounts

​Creating Payout Accounts

​Benefits of Payout Accounts

​When to Use Payout Accounts

​Security Considerations

​Initiating Transfers

​Transfer Request

​Transfer Process

​Transfer Response

​Transfer Status

​Checking Transfer Status

​Webhook Notifications

​Transfer Fees

​Best Practices

​Security

​Transfer Management

​User Experience

​Troubleshooting

​Common Issues

​Support

​Next Steps