Skip to content
HitchPay API Docs

Getting Started

Overview

Welcome to the HitchPay Public API — a secure, modern, and developer-friendly API that allows businesses, merchants, and fintech platforms to seamlessly connect with HitchPay's payment infrastructure.

With this API, you can:

  • Authenticate securely using OAuth 2.0
  • Initiate and verify domestic payments
  • Enroll and KYC-verify customers for cross-border services
  • Send and collect money internationally across Africa and the US
  • Receive real-time webhook updates
  • Manage transaction workflows programmatically

Environments

Environment Base URL
Sandbox (Testing) https://sandbox.hitchpay.ng
Production (Live) https://api.hitchpay.ng

The sandbox environment lets you test all services without affecting live data. Use it for development and integration before going live.

All endpoints are versioned under /v1/.

Example:

POST https://sandbox.hitchpay.ng/v1/payments/initiate

Authentication

HitchPay uses OAuth 2.0 (Client Credentials Grant). Each business is issued a client_id and client_secret from the HitchPay Merchant Dashboard.

  1. Send a POST request to /v1/oauth/token with your credentials
  2. Receive a Bearer access token (expires in 3600 seconds)
  3. Pass the token in every subsequent request:
Authorization: Bearer {access_token}

⚠️ Your client_secret is displayed only once after merchant creation. Store it securely.

Response Format

All API responses are returned as JSON.

Success:

{
  "status": "success",
  "message": "Operation completed successfully.",
  "data": {}
}

Error:

{
  "status": "error",
  "code": "INVALID_REQUEST",
  "message": "Missing required fields."
}

Glossary

Term Definition
client_id Your unique merchant identifier from the HitchPay Dashboard
client_secret Your secret key used to generate access tokens. Never expose publicly
access_token Short-lived Bearer token (1 hour) for authenticating API requests
refresh_token Token used to obtain a new access token without re-supplying credentials
reference A unique identifier you generate per transaction for idempotency and tracking
customer_uuid HitchPay-assigned ID for an enrolled cross-border customer
customerid Your own internal identifier for a customer, passed during enrollment
channel_id Identifier for a payment channel (bank or mobile money), from GET /v1/crossborder/channels
network_id Identifier for a specific bank or mobile money operator, from GET /v1/crossborder/networks
kyc_status Current KYC state of a customer: pending_kyc, pending, approved, or rejected
ramptype Direction of a cross-border channel — deposit (collection) or withdrawal (transfer)
account_type Type of beneficiary or sender account — bank or momo
dial_code International dialling prefix, e.g. +254 for Kenya
webhook_secret Secret key used to sign and verify HMAC SHA256 webhook payloads
provider_reference Reference assigned by the underlying payment provider

HTTP Status Codes

Code Meaning Description
200 OK Request successful
201 Created Resource successfully created
400 Bad Request Invalid or missing parameters
401 Unauthorized Invalid credentials or expired token
403 Forbidden Access denied — e.g. KYC not approved
404 Not Found The requested resource does not exist
409 Conflict Duplicate reference or resource already exists
500 Server Error Unexpected internal server error

Application-level error codes:

Code Description
INVALID_REQUEST Missing or invalid request parameters
INVALID_TOKEN Access token is missing, invalid, or expired
INVALID_CLIENT Client credentials are incorrect
KYC_REQUIRED Customer KYC must be approved before this action
DUPLICATE_REQUEST A transaction with this reference already exists
NOT_FOUND The requested resource was not found
SERVER_ERROR An unexpected server error occurred

Best Practices

  • Always use HTTPS for all API calls
  • Keep your client_secret and webhook_secret confidential — never expose them in frontend code
  • Always verify webhook signatures using HMAC SHA256 before processing any event
  • Handle token expiry gracefully — auto-refresh your access token before it expires
  • Use unique references per transaction to ensure idempotency
  • Always confirm final transaction status via GET /v1/crossborder/global-transfer/{reference} or webhooks
  • Fetch live rates immediately before initiating a transfer — rates change frequently

Test Cards (Sandbox)

Use these card numbers in the sandbox to simulate different payment scenarios. Use any future expiry, any 3-digit CVC, and any postal code.

Card Number Scenario
4242 4242 4242 4242 Payment succeeds without authentication
4000 0025 0000 3155 Payment requires 3D Secure authentication
4000 0000 0000 9995 Card declined — insufficient funds

Support

📧 [email protected]

Questions? Email [email protected]. Also on GitBook.