External Payments-gateway API Reference

Base URL: your deployment's PUBLIC_BASE_URL (e.g. https://api.payprosolutionsltd.com/).

Authentication

Every /v1/payments* request must carry:

• X-Client-Key: <client_key> — issued once at onboarding.
• X-Signature: <hex HMAC-SHA256> — see table below for what to sign.
• Content-Type: application/json (for POST requests).

Example (Node.js), signing a creation request for amount 5000 and idempotency key order-123:

const crypto = require("crypto");
const signingKey = "..."; // given to you once at onboarding
const signature = crypto
  .createHmac("sha256", signingKey)
  .update("5000.order-123")
  .digest("hex");

POST /v1/payments

Create a payment. idempotency_key makes retries safe — the same key always returns the same record instead of creating a duplicate.

Request body:

{
  "amount": 5000,
  "payment_item": "Market stall renewal",
  "payer_name": "Amina Yusuf",
  "payer_email": "amina@example.com",
  "payer_reference": "stall-204",
  "idempotency_key": "order-123"
}

Response (201 Created, or 200 OK if idempotency_key already exists):

{
  "reference": "AB3DEFGH9J",
  "status": "unpaid",
  "amount": 5000,
  "payment_item": "Market stall renewal",
  "payer_name": "Amina Yusuf",
  "payer_reference": "stall-204",
  "created_at": "2026-10-20T10:00:00.000Z",
  "paid_at": null,
  "checkoutUrl": "https://api.payprosolutionsltd.com/pay/AB3DEFGH9J"
}

Send your payer to checkoutUrl to complete payment via Credo's hosted checkout.

GET /v1/payments/:reference

Poll a payment's current status. If still unpaid but a Credo session exists, this re-verifies directly with Credo before responding — a missed or delayed webhook won't leave you polling a stale row forever.

GET /v1/payments

List your own payments, paginated.

Query params: page, per_page (max 100), status, from, to (dates).

Webhooks

This service does not currently forward confirmed payments to a partner-provided webhook URL — poll GET /v1/payments/:reference for status. (Outbound partner notifications may be added in a future version.)