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

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

Request
Response

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)

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

Request
Response

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)

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

Advanced Parameters

locked_currency

string

Restrict to a specific currency

locked_channel

string

Restrict to a specific payment channel

locked_country

string

Restrict to a specific country

items

array

Array of items being purchased

shipping

object

Shipping information

address

object

Customer’s address

customer_meta

object

Additional customer metadata

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

Request
Response

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

Request
Response

DELETE /payments/{reference}

Cancel a pending payment.

Path Parameters

reference

string

required

Reference of the payment to cancel

Process a Payment

Request
Response

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

Mobile Money Parameters

For Mobile Money payments, the data object should include:

data.phone

string

The mobile money account number

data.account_number

string

Alternative to phone, the mobile money account number

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

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

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

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

Common Error Codes

400

Bad Request

Invalid request parametersThis typically occurs when required parameters are missing or have invalid values.

401

Unauthorized

Invalid API keyCheck that you’re using the correct API key and that it’s properly included in the Authorization header.

404

Not Found

Payment not foundThe payment reference you provided doesn’t exist or belongs to another account.

422

Unprocessable Entity

Payment cannot be processedThis occurs when trying to process a payment that’s already completed, canceled, or in a state that doesn’t allow the requested operation.

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.

Introduction

Core Resources

Additional Resources

API Specification

Payments API

Payments API

The Payment Object

Payment Object Properties

API Endpoints

List All Payments

Query Parameters

Create a Payment

Request Parameters

Example Request

Retrieve a Payment

Path Parameters

Cancel a Payment

Path Parameters

Process a Payment

Path Parameters

Request Parameters

Example Request for MTN Mobile Money

Payment Statuses

pending

processing

complete

failed

canceled

expired

Handling Callbacks

Webhooks

Error Handling

Best Practices

Store Payment References

Verify Payment Status

Use Webhooks

Idempotent References

Error Handling

Introduction

Core Resources

Additional Resources

API Specification

​Payments API

​The Payment Object

​Payment Object Properties

​API Endpoints

List All Payments

​Query Parameters

Create a Payment

​Request Parameters

​Example Request

Retrieve a Payment

​Path Parameters

Cancel a Payment

​Path Parameters

Process a Payment

​Path Parameters

​Request Parameters

​Example Request for MTN Mobile Money

​Payment Statuses

pending

processing

complete

failed

canceled

expired

​Handling Callbacks

​Webhooks

​Error Handling

​Best Practices

Store Payment References

Verify Payment Status

Use Webhooks

Idempotent References

Error Handling

Payments API

The Payment Object

Payment Object Properties

API Endpoints

Query Parameters

Request Parameters

Example Request

Path Parameters

Path Parameters

Path Parameters

Request Parameters

Example Request for MTN Mobile Money

Payment Statuses

Handling Callbacks

Webhooks

Error Handling

Best Practices