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

string

Your custom reference for the payment

number

Amount of the payment in the smallest currency unit

string

Three-letter ISO currency code

string

Status of the payment: pending, processing, complete, failed, canceled, expired

string

ID of the customer making the payment

string

ID of the payment method used

string

Description of the payment

object

Additional data attached to the payment

string

Timestamp when the payment was created

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

integer

Number of items per page (default: 30, max: 100)

integer

Page number (default: 1)

string

Search by reference

string

Filter by status

string

Filter by payment channels (comma-separated)

string

Start date filter (format: YYYY-MM-DD)

string

End date filter (format: YYYY-MM-DD)

{
  "code": 200,
  "status": "OK",
  "message": "Payments retrieved",
  "totals": 50,
  "last_page": 2,
  "current_page": 1,
  "selected": 30,
  "items": [
    {
      "id": "pay_123456789",
      "reference": "order_123",
      "amount": 5000,
      "currency": "XAF",
      "status": "complete",
      "customer": "cus_123456789",
      "created_at": "2023-01-01T12:00:00Z"
    },
    // More payments...
  ]
}

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

number

required

Amount to charge in the smallest currency unit

string

required

Three-letter ISO currency code (e.g., XAF)

string

Customer’s email address (required if phone and customer are not provided)

string

Customer’s phone number (required if email and customer are not provided)

string or object

Customer ID or object (required if email and phone are not provided)

string

Description of the payment

string

Unique reference for the payment

string

URL to redirect after payment completion

Advanced Parameters

string

Restrict to a specific currency

string

Restrict to a specific payment channel

string

Restrict to a specific country

array

Array of items being purchased

object

Shipping information

object

Customer’s address

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

const payment = {
  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"
};

fetch('https://api.notchpay.co/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'YOUR_PUBLIC_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payment)
});

{
  "status": "Accepted",
  "message": "Payment initialized",
  "code": 201,
  "transaction": {
    "id": "pay_123456789",
    "reference": "order_123",
    "amount": 5000,
    "currency": "XAF",
    "status": "pending",
    "customer": "cus_123456789",
    "created_at": "2023-01-01T12:00:00Z"
  },
  "authorization_url": "https://pay.notchpay.co/pay_123456789"
}

After creating a payment, redirect your customer to the authorization_url to complete the payment.

Retrieve a Payment

Request
Response

GET /payments/{reference}

Retrieve details of a specific payment using its reference.

Path Parameters

string

required

Reference of the payment to retrieve

{
  "status": "Accepted",
  "message": "Transaction retrieved",
  "code": 202,
  "transaction": {
    "id": "pay_123456789",
    "reference": "order_123",
    "amount": 5000,
    "currency": "XAF",
    "status": "complete",
    "customer": "cus_123456789",
    "payment_method": "pm.ndzAfIh555VCPML1",
    "created_at": "2023-01-01T12:00:00Z",
    "completed_at": "2023-01-01T12:05:00Z"
  }
}

Cancel a Payment

Request
Response

DELETE /payments/{reference}

Cancel a pending payment.

Path Parameters

string

required

Reference of the payment to cancel

{
  "code": 202,
  "status": "Accepted",
  "message": "Your payment has been canceled"
}

You can only cancel payments that are in the pending status. Payments that are already processing, complete, or failed cannot be canceled.

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

string

required

Reference of the payment to process

Request Parameters

string

required

Payment channel (e.g., cm.mtn, cm.orange)

object

Channel-specific data

string

Client’s IP address

Mobile Money Parameters

For Mobile Money payments, the data object should include:

string

The mobile money account number

string

Alternative to phone, the mobile money account number

Example Request for MTN Mobile Money

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

{
  "status": "Accepted",
  "message": "Payment processing initiated",
  "code": 202,
  "transaction": {
    "id": "pay_123456789",
    "reference": "order_123",
    "status": "processing"
  }
}

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

Bad Request

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

Unauthorized

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

Not Found

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

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

​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