Developer documentation

Create a payout

Last updated:

The createPayout method disburses funds from your UnitPay merchant balance to an external destination — a card, an Indonesian bank account, an international SWIFT beneficiary, or a USDT (TRC-20) wallet. Payouts are server-to-server only; never expose the secret key in client-side code or logs.

When to use it

  • Marketplace seller settlement — pay out to seller bank accounts after their orders complete.
  • Payroll and contractor disbursement — bulk-pay payees by uploading a batch and submitting one row per beneficiary.
  • Out-of-band refunds — when the original payment cannot be reversed (window expired, channel unsupported), issue an equivalent payout to the customer's account.
  • Treasury moves and partner settlement — cross-border USD/EUR via SWIFT or USDT on Tron.

For reversing an in-window card or VA payment, prefer refundPayment — it preserves the original payment-method audit trail. Use createPayout only when refund is not possible.

Prerequisites

  • Project KYC must be in active state. Payouts are blocked while KYC is pending or under review.
  • Merchant balance in the requested currency must cover the payout sum plus the destination-rail fee. Available balance is visible in the merchant cabinet under Balance → Available for payout.
  • Destination type must be enabled on your project. Card and Indonesian bank payouts are enabled by default; SWIFT and USDT (TRC-20) require an explicit enablement request to onboarding.
  • Payout limits (per-transaction and per-day) are set by merchant tier. Submit a request through the cabinet to raise them.

Endpoint

Send the request to https://api.unitpay.net/api. POST over TLS is required — GET is rejected for payout methods because the secret key would otherwise leak into URL logs and proxy buffers.

Required parameters

ParameterTypeDescription
methodstringAlways createPayout.
params[projectId]integerYour project ID, visible in the merchant cabinet under Settings → Project.
params[paymentType]stringDestination rail: card, bank_idr, bank_swift, or usdt_trc20. See Supported destinations below.
params[sum]numberPayout amount in major currency units (for example, 1500000.00 for IDR 1,500,000). Two decimal places maximum. Must be greater than zero and not exceed your available balance net of fee.
params[purpose]stringHuman-readable purpose of the payout (for example, Marketplace settlement, order #9821). Stored in the audit trail and shown to the recipient where the rail supports it.
params[account]stringDestination identifier: card number for card, IDR account number for bank_idr, IBAN/account number for bank_swift, wallet address for usdt_trc20. Allowlists for travel-rule controls apply to crypto rails.
params[signature]stringHMAC signature of the request. See Signing the request below.

Optional parameters

ParameterTypeDescription
params[currency]stringISO 4217 currency code: IDR, USD, EUR, or USDT. Defaults to the project's primary currency. Must match a balance you hold.
params[merchantPayoutId]stringYour idempotency key (max 64 chars). Two requests with the same merchantPayoutId create only one payout — the second call returns the original payoutId. Strongly recommended for production traffic.
params[recipientName]stringBeneficiary full name. Required for bank_swift; optional but recommended for card and bank_idr.
params[recipientBankCode]stringBank routing code: BIC/SWIFT for bank_swift, BI bank code for bank_idr. Required where the destination rail cannot infer the bank from the account number alone.

Supported destinations

paymentTypeCurrenciesAccount formatSettlement window
cardIDR, USD, EUR13–19-digit PAN (Visa, Mastercard, JCB)Same business day for IDR cards; 1–3 business days for international cards
bank_idrIDRIndonesian bank account number + BI bank codeReal-time via BI-FAST when supported by destination bank; otherwise next-day SKNBI
bank_swiftUSD, EURIBAN or local account number + BIC/SWIFT code1–3 business days, depending on correspondent banking chain
usdt_trc20USDTTron (TRC-20) wallet addressMinutes, subject to network congestion

Use getBinInfo to validate a card destination before submitting a payout — it returns the card brand, type, country, and issuing bank so you can reject ineligible cards before they hit limits.

Signing the request

UnitPay signs payout requests with HMAC-SHA-256 using your project secret key. The algorithm matches createPayment:

  1. Take all params[*] values except params[signature] and sort them by parameter name.
  2. Concatenate the values, separated by the literal four-character delimiter {up}, in this order: method, then each sorted parameter value, then your project secret key.
  3. Hash the resulting string with SHA-256 and lowercase the hex digest.
  4. Pass the digest as params[signature].

Rotate the secret key from Settings → Project → Secret key if you suspect compromise. Never commit it to source control.

Example request

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

method=createPayout
&params[projectId]=123456
&params[paymentType]=bank_idr
&params[sum]=1500000.00
&params[currency]=IDR
&params[purpose]=Marketplace%20settlement%20order%20%239821
&params[account]=1234567890
&params[recipientBankCode]=014
&params[recipientName]=Andi%20Pratama
&params[merchantPayoutId]=settlement-9821
&params[signature]=<sha256-hex-digest>

Successful response

UnitPay replies with HTTP 200 and a JSON body once the payout is queued. Settlement to the beneficiary follows the destination rail's window — the response only confirms acceptance.

{
  "result": {
    "payoutId": 9871234,
    "status": "new",
    "sum": 1500000.00,
    "fee": 5500.00,
    "currency": "IDR",
    "createdDate": "2026-05-08T14:22:11+07:00",
    "merchantPayoutId": "settlement-9821"
  }
}
FieldDescription
payoutIdUnitPay's unique payout identifier. Store it alongside your merchantPayoutId for reconciliation and status queries.
statusInitial state, almost always new. Final state is delivered via callback or polled with getPayout.
feeDestination-rail fee in the same currency as sum. Already deducted from your balance.
createdDateISO 8601 timestamp in Asia/Jakarta (WIB) timezone.

Error response

{
  "error": {
    "message": "Insufficient balance for this payout.",
    "code": -32100
  }
}
codeMeaning
-32000Invalid signature or secret key.
-32100Insufficient balance net of fee.
-32101Destination rail (paymentType) is not enabled for this project.
-32102Per-transaction or daily payout limit exceeded.
-32103Account format invalid for the requested rail (for example, IBAN missing for bank_swift).
-32104Destination card or wallet failed prevalidation (closed card, blocked wallet, sanctioned country).
-32105Project KYC is not in active state.

Treat any error response as a hard failure: do not retry blindly. If you receive a network timeout or HTTP 5xx, retry with the same merchantPayoutId — the idempotency key prevents duplicate disbursement.

Test mode

Each project has a separate test secret key and a sandbox createPayout endpoint that mirrors production behaviour without moving real funds. Test payouts always reach success within seconds and emit the same callback shape, so you can validate your handler end-to-end before going live.

Important constraints

  • Idempotency. Always send merchantPayoutId. Network timeouts and intermediary retries can cause UnitPay to receive your request more than once; only the idempotency key prevents duplicate disbursement.
  • Travel rule for crypto. USDT (TRC-20) payouts are subject to wallet-allowlist enforcement and source-of-funds checks. Allowlist your treasury and partner wallets in the cabinet before relying on automated USDT disbursement.
  • Sanctions screening. Beneficiaries are screened against UN, EU, OFAC, and OFSI lists at submission. A match returns error code -32104 and the payout is not queued.
  • Operator approval. Project policy may require manual operator approval for payouts above a configurable threshold. The payout sits in pending_review until an operator approves it in the cabinet.

Next steps