API Reference · Payins

Create a payin

Initiate a payment collection. The customer is redirected to complete payment on the selected gateway. Sign every request with HMAC-SHA256.

POSThttps://payment.klustar.io/payment/api/payins

Headers

X-Tenant-ID

stringrequired

Your tenant identifier (provided during onboarding).

X-API-KEY

stringrequired

Public API key from the merchant dashboard.

X-Merchant-ID

stringrequired

Your business profile / merchant ID (same as appId).

X-Nonce

stringrequired

Unique per-request value (UUID recommended). Never reuse.

X-Timestamp

stringrequired

Unix epoch seconds when the request is signed. Must be within ±300s of server time.

X-Signature

stringrequired

Lowercase hex HMAC-SHA256 of the signature base string, using your secret key.

Content-Type

stringrequired

Must be application/json for JSON bodies.

Defaults to application/json

X-API-Version

stringoptional

Contract version: 1 (legacy, no paymentMethod) or 2 (paymentMethod required and signed). Optional, and there is no default - when omitted the version is inferred from whether paymentMethod is present, so sending version 1 alongside paymentMethod is rejected with 400.

Body params

reference

stringrequired

Unique transaction reference generated by your system. Echoed in webhooks.

amount

numberrequired

Transaction amount in the specified currency.

currency

stringrequired

ISO currency code. Currently NGN.

Defaults to NGN

customerName

stringoptional

Customer full name.

customerEmail

stringoptional

Customer email address.

redirectUrl

stringoptional

URL to redirect the customer after payment.

notifyUrl

stringoptional

Webhook URL for asynchronous status updates.

gateway

stringoptional

Payment gateway. Example: PALMPAY. Overrides paymentMethod when both are sent.

paymentMethod

stringoptional

CARD or BANK_TRANSFER. Routes the pay-in to the providers configured for that method, with failover. Must be included in the signed canonical body when sent.

narration

stringoptional

Short description shown on the payment flow.

Request body

application/json

{
  "reference": "REF-a1b2c3d4e5",
  "amount": 2000,
  "currency": "NGN",
  "customerName": "Jane Doe",
  "customerEmail": "jane@example.com",
  "redirectUrl": "https://merchant.example/return",
  "notifyUrl": "https://merchant.example/webhooks/klustar",
  "paymentMethod": "BANK_TRANSFER",
  "narration": "Order #1042"
}

Responses

Payin created. Redirect the customer using the returned payment URL when present.

Response body

{
  "success": true,
  "reference": "REF-a1b2c3d4e5",
  "status": "pending",
  "paymentUrl": "https://checkout.example/session/...",
  "message": "Payment initiated"
}

{
  "success": true,
  "reference": "REF-a1b2c3d4e5",
  "status": "pending",
  "paymentUrl": "https://checkout.example/session/...",
  "message": "Payment initiated"
}