API Reference · Payouts

Initiate a payout

Not available through the API at the moment: send payouts from the dashboard (Transactions → Payouts), where they are checked against and debited from your wallet. API pay-ins do not credit that wallet. Dashboard payouts are not working on production at the moment either: no payout gateway is configured, so they stop before reaching a provider. Calls to this endpoint from outside Klustar are refused with 403. The request and signing below are kept for reference; the same signing applies to Query payout status and Account enquiry.

POSThttps://payment.klustar.io/payment/merchant-api/payout

Headers

X-Tenant-ID

stringrequired

The environment of this call: test or live, ignoring case and surrounding spaces. It is not an account identifier, nothing issues it, and it is not signed. On Create a payin and Query payin status a missing or mistyped value means test, with no error. Account enquiry and Query payout status refuse a missing value and treat a mistyped one as test. live needs approval: until then a correctly signed live request gets 403 LIVE_NOT_ENABLED.

X-API-KEY

stringrequired

Public API key from the merchant dashboard. The same key serves test and live.

X-Merchant-ID

stringrequired

Your App ID, shown beside your API key on Profile & Settings → API Keys.

X-Nonce

stringrequired

A new value on every request (UUID recommended), including a retry after a failure. A nonce is recorded before the signature is checked and stays used, so a refused request burns it.

X-Timestamp

stringrequired

Unix epoch seconds when the request is signed, digits only. 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. Any other type gets a 502.

Defaults to application/json

Body params

amount

stringrequired

Payout amount as a string decimal.

currency

stringrequired

Currency code. Currently NGN.

beneficiaryAccount

stringrequired

Beneficiary NUBAN account number.

beneficiaryName

stringrequired

Account name returned from account enquiry.

beneficiaryBankCode

stringrequired

Bank code from List banks.

beneficiaryPhone

stringoptional

Beneficiary phone number.

reference

stringrequired

Unique payout reference from your system.

notifyUrl

stringoptional

Does not set your webhook: payout webhooks go only to the URL saved in Profile & Settings → API Keys. Leave this out.

narration

stringoptional

Transfer narration.

Request body

application/json

{
  "amount": "10000",
  "currency": "NGN",
  "beneficiaryAccount": "ACCOUNT_NUMBER",
  "beneficiaryName": "JANE DOE",
  "beneficiaryBankCode": "KBC-0007",
  "beneficiaryPhone": "08012345678",
  "narration": "Vendor settlement",
  "reference": "PO-<new UUID for every attempt>"
}

Responses

Every call from outside Klustar gets this, as plain text.

Response body

Forbidden

Forbidden