API Reference#

An endpoint contract describes the method, path, media type, authentication, permissions, input schema, response schema, and possible states. Use all of those together. A JSON example shows one valid shape; it does not replace required-field rules, enum definitions, length limits, or conditional requirements.

Some KlemPay controllers use action routes with POST for reads or updates. Follow the actual method rather than converting it to a preferred REST convention. Encode path parameters safely and omit unavailable optional query parameters instead of sending empty placeholder values.

GET /v1/customers
curl --request GET "https://sandbox.example.com/v1/customers?page=0&size=20" \
  --header "Accept: application/json" \
  --header "x-api-key: pk_sandbox_example" \
  --header "x-timestamp: <current-milliseconds>" \
  --header "x-signature: <computed-signature>"

This illustrative transfer request contains a nested recipient, an array of allocations, an enum, a boolean, an optional note, and a stable operation reference. Financial units and precision must be defined by the endpoint; never assume that an amount is expressed in major or minor units.

POST /v1/transfers
{
  "externalRefNo": "7f66eb2e-667c-4e32-9da0-c01822c20432",
  "accountType": "BUSINESS",
  "ccy": "NGN",
  "amount": "2500.00",
  "recipient": {
    "recipientRef": "RCP-example",
    "channel": "BANK"
  },
  "allocations": [{ "reference": "order-example", "amount": "2500.00" }],
  "notifyRecipient": false,
  "note": "Invoice settlement"
}

Strings preserve references, exact codes, phone numbers, and values with leading zeros. Numbers represent numeric values only when the schema says so. Use integers for counts and pagination where specified. Booleans are true or false; arrays retain their element schema; objects retain their nested fields.

An enum is a closed list supplied by the contract. Preserve its exact case and spelling. A UI label can be friendly, but the submitted value must match the backend enum.

An absent optional field, an empty string, and null have different meanings. Omit an unavailable optional value. Send null only when the schema allows it and the intended action is clear. Do not substitute zero for a missing amount or an empty string for a missing reference.

The existing KlemPay web transport consumes responseCode, responseMessage, errors, and responseData. Codes 00 and 000 are treated as success. Data must still pass the endpoint's runtime parser before it is used.

{
  "responseCode": "00",
  "responseMessage": "Successful operation",
  "errors": [],
  "responseData": {
    "transferRef": "TRF-example",
    "externalRefNo": "7f66eb2e-667c-4e32-9da0-c01822c20432",
    "status": "PENDING",
    "ccy": "NGN",
    "amount": "2500.00",
    "createdAt": "2026-09-27T12:00:00Z"
  }
}

Validate the documented collection shape rather than assuming every response is a plain array. Some controllers return an object containing records and page metadata. The record key, page base, totals, and continuation strategy must come from that controller.

{
  "responseCode": "00",
  "responseMessage": "Successful operation",
  "errors": [],
  "responseData": {
    "items": [{ "customerRef": "CUS-example", "customerName": "Ada Obi" }],
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "hasNext": false
  }
}

Keep a resource identifier immutable unless the endpoint explicitly allows changing it. A full update may require fields that a partial update omits. Do not infer destructive semantics from the HTTP method alone: deletion can be restricted by linked resources, permissions, or workflow state.

PUT /v1/customers/CUS-example
{
  "customerName": "Ada Obi Enterprises",
  "customerEmail": "billing@example.com",
  "customerPhoneCountryCode": "+234",
  "customerPhoneNumber": "8012345678",
  "customerAddress": "Example business address"
}

DELETE /v1/customers/CUS-example
curl --request DELETE "https://sandbox.example.com/v1/customers/CUS-example" \
  --header "x-api-key: pk_sandbox_example" \
  --header "x-timestamp: <current-milliseconds>" \
  --header "x-signature: <computed-signature>"

A successful envelope means that the request was handled successfully at the application boundary. It does not necessarily mean a payment has settled. Read the resource state, persist its reference, and follow the documented status or webhook workflow until a terminal outcome is confirmed.

Treat financial values, eligibility flags, and allowed actions returned by the backend as authoritative. A frontend may display an estimate, but it must not replace the server's confirmed amount, fee, currency, or permission decision.

Unknown optional response fields can be ignored, but a missing required field or an unknown state that affects financial behaviour needs a deliberate recovery path. Keep raw response access restricted, record a sanitised protocol failure, and avoid guessing the meaning of a new enum.

Review Errors for failure parsing and Idempotency for safe retries. Choose a published category from API Endpoints in the sidebar for live operation contracts, schemas, and examples.