Skip to main content

​
API Reference

​
Complete Notch Pay API Documentation

This reference provides detailed information about all endpoints, request parameters, and response formats for the Notch Pay API.

The Notch Pay API is organized around REST principles. It uses standard HTTP verbs, returns JSON-encoded responses, and uses standard HTTP response codes to indicate API errors.

Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients.

​
Getting Started

Base URL

All API requests should be made to:
https://api.notchpay.co

Authentication

Include your API key in the Authorization header:
Authorization: YOUR_PUBLIC_KEY
Learn more about authentication →

​
API Environments

​
Development & Testing

Use test API keys that start with test_

Test transactions don’t affect real money and are only visible in test mode.

Test cards and accounts are available in the Testing Guide.

​
Response Format

{
  "code": 200,
  "status": "OK",
  "message": "Descriptive message",
  "data": {
    "id": "pay_123456789",
    "amount": 5000,
    "currency": "XAF",
    "status": "complete"
  }
}

​
HTTP Status Codes

Success Codes (2xx)

​
200
OK
The request was completed
​
201
Created
A new resource was created
​
202
Accepted
The request has been accepted for processing
​
400
Bad Request
The request was invalid or cannot be served
​
401
Unauthorized
Authentication credentials are missing or invalid
​
403
Forbidden
The authenticated user doesn’t have permission
​
404
Not Found
The requested resource doesn’t exist
​
422
Unprocessable Entity
The request was well-formed but contains semantic errors
​
429
Too Many Requests
Rate limit exceeded
​
500
Internal Server Error
An error occurred on the server
​
503
Service Unavailable
The server is temporarily unavailable

​
Rate Limiting

The Notch Pay API implements rate limiting to protect against abuse. If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.
1

Rate Limit Headers

Each response includes headers that provide information about your current rate limit status:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 98
X-RateLimit-Reset: 1620000000
2

Handling Rate Limits

When you receive a 429 response, the Retry-After header indicates how many seconds to wait before making another request.
Retry-After: 30
Implement exponential backoff in your code to handle rate limiting gracefully.

​
API Resources

Payments

Create, retrieve, and manage payments

Transfers

Send money to beneficiaries

Customers

Create and manage customer information

Beneficiaries

Manage recipients for money transfers

Webhooks

Configure and manage webhook endpoints

Balance

Check your account balance

Resources

Get information about payment channels, countries, and currencies

Authentication

Learn about authentication methods and security

​
API Versioning

The current version of the API does not require a version specifier in the URL. Future versions may be accessed by including a version number in the URL or headers.

​
SDKs and Libraries

JavaScript

Node.js and browser SDK

PHP

PHP SDK for server-side integration

Python

Python SDK for server-side integration

Mobile

iOS and Android SDKs

​
Need Help?

API Errors

Troubleshoot common API errors

Support Team

Contact our technical support team

Developer Community

Connect with other developers
Ready to start building? Check out our Getting Started Guide to make your first API request.