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

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)

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)

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

POST /payments
POST /payments/initialize (Legacy)

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

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

POST /payments
POST /payments/initialize (Legacy)

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

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

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

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

GET /payments/{reference}

Retrieve details of a specific payment using its reference.

Path Parameters

reference

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

DELETE /payments/{reference}

Cancel a pending payment.

Path Parameters

reference

string

required

Reference of the payment to cancel

DELETE /payments/{reference}

Cancel a pending payment.

Path Parameters

reference

string

required

Reference of the payment to cancel

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

Process a Payment

POST /payments/{reference}
PUT /payments/{reference}

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

Example Request for MTN Mobile Money

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

POST /payments/{reference}
PUT /payments/{reference}

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

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

// 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

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

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

​The Payment Object

​Payment Object Properties

​API Endpoints

List All Payments

​Query Parameters

​Query Parameters

Create a Payment

​Request Parameters

​Example Request

​Request Parameters

​Example Request

Retrieve a Payment

​Path Parameters

​Path Parameters

Cancel a Payment

​Path Parameters

​Path Parameters

Process a Payment

​Path Parameters

​Request Parameters

​Example Request for MTN Mobile Money

​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

Query Parameters

Request Parameters

Example Request

Request Parameters

Example Request

Path Parameters

Path Parameters

Path Parameters

Path Parameters

Path Parameters

Request Parameters

Example Request for MTN Mobile Money

Path Parameters

Request Parameters

Example Request for MTN Mobile Money

Payment Statuses

Handling Callbacks

Webhooks

Error Handling

Best Practices