​
Payments API

The Payments API allows you to initialize, retrieve, and manage payment transactions. Use these endpoints to accept payments from your customers through various payment methods.

​
The Payment Object

{
  "id": "pay_123456789",
  "reference": "order_123",
  "amount": 5000,
  "currency": "XAF",
  "status": "complete",
  "customer": "cus_123456789",
  "payment_method": "pm.ndzAfIh555VCPML1",
  "description": "Payment for Order #123",
  "metadata": {},
  "created_at": "2023-01-01T12:00:00Z",
  "completed_at": "2023-01-01T12:05:00Z"
}

​
Payment Object Properties

​
id
string
Unique identifier for the payment
​
reference
string
Your custom reference for the payment
​
amount
number
Amount of the payment in the smallest currency unit
​
currency
string
Three-letter ISO currency code
​
status
string
Status of the payment: pending, processing, complete, failed, canceled, expired
​
customer
string
ID of the customer making the payment
​
payment_method
string
ID of the payment method used
​
description
string
Description of the payment
​
metadata
object
Additional data attached to the payment
​
created_at
string
Timestamp when the payment was created
​
completed_at
string
Timestamp when the payment was completed (if applicable)

​
API Endpoints

List All Payments

GET /payments
Retrieve a list of payments with pagination.

​
Query Parameters

​
limit
integer
Number of items per page (default: 30, max: 100)
​
page
integer
Page number (default: 1)
​
search
string
Search by reference
​
status
string
Filter by status
​
channels
string
Filter by payment 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 Payment

POST /payments
POST /payments/initialize (Legacy)
Initialize a new payment. Both endpoints are equivalent and can be used interchangeably.

​
Request Parameters

​
amount
number
required
Amount to charge in the smallest currency unit
​
currency
string
required
Three-letter ISO currency code (e.g., XAF)
​
email
string
Customer’s email address (required if phone and customer are not provided)
​
phone
string
Customer’s phone number (required if email and customer are not provided)
​
customer
string or object
Customer ID or object (required if email and phone are not provided)
​
description
string
Description of the payment
​
reference
string
Unique reference for the payment
​
callback
string
URL to redirect after payment completion

​
Example Request

{
  "amount": 5000,
  "currency": "XAF",
  "customer": {
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+237600000000"
  },
  "description": "Payment for Order #123",
  "callback": "https://example.com/callback",
  "reference": "order_123"
}

Retrieve a Payment

GET /payments/{reference}
Retrieve details of a specific payment using its reference.

​
Path Parameters

​
reference
string
required
Reference of the payment to retrieve

Cancel a Payment

DELETE /payments/{reference}
Cancel a pending payment.

​
Path Parameters

​
reference
string
required
Reference of the payment to cancel

Process a Payment

POST /payments/{reference}
PUT /payments/{reference}
Process a pending payment with a specific payment method. Both HTTP methods are equivalent.

​
Path Parameters

​
reference
string
required
Reference of the payment to process

​
Request Parameters

​
channel
string
required
Payment channel (e.g., cm.mtn, cm.orange)
​
data
object
Channel-specific data
​
client_ip
string
Client’s IP address

​
Example Request for MTN Mobile Money

{
  "channel": "cm.mtn",
  "data": {
    "phone": "+237680000000"
  }
}

​
Payment Statuses

pending

Payment has been initialized but not yet processed

processing

Payment is being processed by the payment provider

complete

Payment has been completed

failed

Payment attempt failed

canceled

Payment was canceled by the merchant or customer

expired

Payment expired before completion

​
Handling Callbacks

1

Redirect to Callback URL

When a payment is completed, Notch Pay will redirect the customer to the callback URL you provided when creating the payment. The URL will include the payment reference as a query parameter:
https://example.com/callback?reference=order_123
2

Verify Payment Status

Always verify the payment status by calling the Retrieve a Payment endpoint before fulfilling the order.
// Example verification in JavaScript
app.get('/callback', async (req, res) => {
  const { reference } = req.query;
  
  try {
    const response = await fetch(`https://api.notchpay.co/payments/${reference}`, {
      headers: { 'Authorization': 'YOUR_PUBLIC_KEY' }
    });
    
    const data = await response.json();
    
    if (data.transaction.status === 'complete') {
      // Payment complete, fulfill the order
      // ...
      res.send('Payment complete!');
    } else {
      // Payment not complete
      res.send('Payment not completed.');
    }
  } catch (error) {
    console.error('Error verifying payment:', error);
    res.status(500).send('Error verifying payment');
  }
});
3

Fulfill the Order

Once you’ve verified that the payment is complete, you can fulfill the order or provide access to the purchased product or service.

​
Webhooks

For more reliable payment notifications, we recommend setting up webhooks to receive real-time updates about payment status changes.
Webhooks provide a more reliable way to receive payment notifications than callbacks, as they don’t depend on the customer’s browser. See the Webhooks API documentation for more information.

​
Error Handling

​
Best Practices

Store Payment References

Always store the payment ID and reference in your database for future reference and reconciliation.

Verify Payment Status

Always verify the payment status using the API before fulfilling orders or providing services.

Use Webhooks

Set up webhooks for reliable payment notifications, especially for asynchronous payment methods like mobile money.

Idempotent References

Use unique, idempotent references for each payment to prevent duplicate payments and simplify reconciliation.

Error Handling

Implement proper error handling for failed payments, including user-friendly error messages and recovery options.