Developer documentation

Get payout information

Last updated:

The getPayout method returns the current state of a payout you previously created with createPayout: status, settled amount, fee, currency, and timestamps. Use it to reconcile when callbacks were missed, to display payout state to operators, or to retry decisions after a network blip.

Endpoint

Send the request to https://api.unitpay.net/api. POST over TLS is required — GET is rejected to keep the secret key out of URL logs.

Required parameters

ParameterTypeDescription
methodstringAlways getPayout.
params[payoutId]integerUnitPay's payout identifier returned by createPayout.
params[secretKey]stringProject secret key. Send only via TLS in the POST body.

Optional parameters

ParameterTypeDescription
params[merchantPayoutId]stringLook up by your idempotency key instead of payoutId. Useful when your system stored the merchant key but lost the UnitPay ID.

Either params[payoutId] or params[merchantPayoutId] must be present — not both.

Example request

POST https://api.unitpay.net/api
Content-Type: application/x-www-form-urlencoded

method=getPayout
&params[payoutId]=9871234
&params[secretKey]=<your-project-secret-key>

Successful response

{
  "result": {
    "payoutId": 9871234,
    "merchantPayoutId": "settlement-9821",
    "status": "success",
    "sum": 1500000.00,
    "fee": 5500.00,
    "currency": "IDR",
    "paymentType": "bank_idr",
    "account": "1234567890",
    "recipientBankCode": "014",
    "purpose": "Marketplace settlement order #9821",
    "createdDate": "2026-05-08T14:22:11+07:00",
    "completedDate": "2026-05-08T14:23:47+07:00"
  }
}
FieldDescription
statusOne of new, pending_review, in_progress, success, or error. See the table below.
sumPayout amount, identical to the params[sum] originally submitted.
feeDestination-rail fee debited from your balance, in the same currency as sum.
accountDestination identifier, masked according to the rail's policy (cards return only the last 4 digits).
completedDateISO 8601 timestamp of final state. Absent until status is success or error.

Status values

StatusMeaningTerminal?
newAccepted by UnitPay, not yet submitted to the destination rail. Typically observed for under a minute.No
pending_reviewAwaiting manual operator approval per project policy. Operators act in the merchant cabinet.No
in_progressSubmitted to the destination rail; awaiting confirmation. Card and SWIFT payouts can sit here for hours during banking-hour cutover.No
successSettled to the beneficiary. Funds have left UnitPay's correspondent account.Yes
errorRejected by the destination rail (closed account, insufficient KYC at the bank, blocked card). Funds are returned to your merchant balance net of any non-refundable rail fees.Yes

Error response

{
  "error": {
    "message": "Payout not found.",
    "code": -32001
  }
}
codeMeaning
-32000Invalid secret key. Rotate from Settings → Project → Secret key.
-32001Payout not found. Verify the ID belongs to a payout on the project that owns this secret key.
-32006Both payoutId and merchantPayoutId were sent, or neither was sent.

Polling and event-driven retrieval

Prefer the callback handler — the same handler that receives payment lifecycle events also receives payoutStatus events for state changes (new → in_progress → success or → error). Reuse signature verification.

If you must poll, follow these limits:

  • No more than once every 30 seconds per payout while status is non-terminal.
  • Stop polling as soon as status is success or error; the result will not change.
  • Per-project rate limit applies to all getPayout calls combined — 600 requests/min, beyond which UnitPay returns HTTP 429.

Test mode

Test-mode payouts use the project's test secret key and complete to success within seconds — useful for end-to-end validation of your reconciliation logic before going live.

Next steps