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.

  • Overview
  • Features
  • Getting Started

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

  • Test Environment
  • Live Environment

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

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

Need Help?

Ready to start building? Check out our Getting Started Guide to make your first API request.
I