Getting Started#

Arrange a partner record and a sandbox API key with the integration team. The credentials include an apiKey and an apiSecret. The secret is shown when the key is issued; store it immediately in a secret manager on the server that will make requests.

Sandbox and production credentials must remain separate. Keep each environment's base URL, public key, secret, and callback configuration together so a deployment cannot accidentally combine a sandbox key with a production destination.

Generate x-api-key, x-timestamp, and x-signature on the server. The documented partner signing format combines the timestamp, uppercase HTTP method, versioned request path, and exact raw body with periods. See Authentication for the complete example.

Serialize the body once, sign those exact bytes, and send that same string. Signing one representation and sending another can change whitespace, property order, or numeric formatting and invalidate the signature.

import { createHmac } from "node:crypto";

const timestamp = Date.now().toString();
const method = "POST";
const path = "/v1/accounts/name-enquiry"; // Illustrative route.
const rawBody = JSON.stringify({ accountNumber: "0123456789", bankCode: "044" });
const signature = createHmac("sha256", process.env.KLEMPAY_PARTNER_API_SECRET)
  .update(`${timestamp}.${method}.${path}.${rawBody}`, "utf8")
  .digest("hex");

const response = await fetch(new URL(path, process.env.KLEMPAY_PARTNER_BASE_URL), {
  method,
  headers: {
    "Content-Type": "application/json",
    "x-api-key": process.env.KLEMPAY_PARTNER_API_KEY,
    "x-timestamp": timestamp,
    "x-signature": signature,
  },
  body: rawBody,
  signal: AbortSignal.timeout(15000),
});

Start with a non-debiting lookup so connectivity, signing, and response parsing can be checked before a financial operation. Use sandbox recipient data provided for the assigned environment. A lookup confirms recipient information; it does not reserve funds or guarantee that a later transfer will succeed.

POST /v1/accounts/name-enquiry
curl --request POST "https://sandbox.example.com/v1/accounts/name-enquiry" \
  --header "Content-Type: application/json" \
  --header "x-api-key: pk_sandbox_example" \
  --header "x-timestamp: <current-unix-time-in-milliseconds>" \
  --header "x-signature: <server-computed-signature>" \
  --data '{"accountNumber":"0123456789","bankCode":"044"}'

Check the HTTP status and the application response code independently. KlemPay's existing web transport recognises 00 and 000 as successful envelope codes; an HTTP 200 can still carry a rejected operation. Preserve the backend's responseMessage and errors when the result is unsuccessful.

Choose a published API category from the sidebar and use its live contract for required fields, formats, enums, and allowed transitions. Add input validation before the request, runtime validation after the response, and a visible recovery path for the customer.

1. Validate customer input and derive sensitive context on the backend.
2. Generate and persist a stable operation reference before a write request.
3. Submit the request using the documented authentication policy.
4. Store the returned reference and current state rather than only displaying a success message.
5. Reconcile pending outcomes through an approved status request or authenticated webhook.

An accepted request and a completed financial transaction are different states. A pending response should keep the original reference available, explain that processing continues, and offer a status check rather than a fresh payment.

Test validation errors, expired credentials, missing scope, duplicate submissions, timeouts, delayed webhooks, and successful reconciliation. Sandbox success alone does not exercise every provider or settlement path.

• Review Idempotency before retrying a write.
• Implement Webhooks with signature verification and durable processing.
• Add error handling from Errors, including business errors returned with HTTP 200.
• Configure server time synchronisation, bounded timeouts, and redacted request diagnostics.
• Verify the production base URL, issued credentials, scopes, and callback destination before enabling traffic.