Part 6–7

Payout

Submit payouts, read their status, list them, and cancel a payout.

Create a payout

POST/api/v1/payoutspayouts:writeResponse 202

Funds are held from available when the request is accepted, then wait for AntaraPay admin approval. A payout can go to a merchant account or to a merchant's user.

Field	Required	Description
`reference` / `amount` / `currency`	Yes	Unique payout reference, positive amount, `IDR`.
`recipient.type`	Yes	`MERCHANT` or `END_USER`.
`recipient.bank_code`	Yes	A bank code that supports payouts, from `GET /channels`.
`recipient.account_number`	Yes	Account number as a string; do not convert it to a number so leading zeros are not lost.
`recipient.account_name`	Yes	Expected recipient name; the verification result may differ and require review.
`recipient.customer_reference`	Yes*	Required for `END_USER`; the user ID in the merchant's system.
`description` / `metadata`	No	Description up to 255 characters; metadata within the limits in Data formats.

Request

POST /api/v1/payouts
Authorization: Bearer <api_key>
Idempotency-Key: wd-0001-create
Content-Type: application/json

{
  "reference": "WD-0001",
  "amount": "40000",
  "currency": "IDR",
  "recipient": {
    "type": "END_USER",
    "bank_code": "BANK_CODE",
    "account_number": "1234567890",
    "account_name": "NAMA PENERIMA",
    "customer_reference": "CUST-100"
  },
  "description": "Pencairan pengguna"
}

Response 202

{
  "data": {
    "id": "pout_example_001",
    "reference": "WD-0001",
    "status": "PENDING_APPROVAL",
    "amount": "40000",
    "fee": "0",
    "total_reserved": "40000",
    "currency": "IDR",
    "recipient": {
      "type": "END_USER",
      "bank_code": "BANK_CODE",
      "account_number_masked": "******7890",
      "account_name": "NAMA PENERIMA"
    },
    "created_at": "2026-10-15T05:10:00Z",
    "resource_version": 1
  },
  "request_id": "req_example_004"
}

The example uses a temporary payout fee of 0 as a v1 proposal. total_reserved = amount + fee. amount is the value the recipient is requested to receive. The effective fee follows the activation policy. An insufficient balance returns 409 INSUFFICIENT_BALANCE without creating a payout or a partial hold.

Payout details and statuses

GET/api/v1/payouts/{id}payouts:readResponse 200

The details contain the create-response fields plus updated_at, approved_at, completed_at, failure_code, failure_message, transfer_reference, and resource_version. Values not yet available are null. The full account number is never returned.

Status	Impact and client action
`PENDING_APPROVAL`	Balance is already held; waiting for admin review.
`APPROVED`	Approved, but funds are not necessarily sent. No second debit from available.
`PROCESSING`	Execution in progress; do not resend or cancel.
`SUCCEEDED`	Transfer confirmed. Complete the user's withdrawal exactly once.
`REJECTED` / `CANCELLED`	Not sent; the held funds are released.
`FAILED`	Definite failure; the hold is released. Investigate before creating a new request.
`UNKNOWN` / `NEEDS_REVIEW`	Outcome uncertain; the balance stays reserved. Do not create a replacement payout until the outcome is clear.

List payouts

GET/api/v1/payoutspayouts:read

Optional query parameters: reference, status, recipient_type, from, to, cursor, limit. from/to filter on created_at. The pagination envelope is the same as for payins. List items contain id, reference, amount, fee, currency, status, the masked recipient, created_at, and completed_at.

Cancel a payout

POST/api/v1/payouts/{id}/cancelpayouts:writeResponse 200

Idempotency-Key is required. The body field reason is required, up to 255 characters. Only PENDING_APPROVAL or APPROVED payouts that have not been claimed for execution can be cancelled.

Request body

{ "reason": "Dibatalkan oleh pengguna" }

Response 200

{
  "data": {
    "id": "pout_example_001",
    "reference": "WD-0001",
    "status": "CANCELLED",
    "released_amount": "40000",
    "currency": "IDR",
    "resource_version": 3,
    "updated_at": "2026-10-15T05:11:00Z"
  },
  "request_id": "req_example_005"
}

If a cancel races with execution, the server atomically picks a single winner. Once execution has started, the response is 409 INVALID_STATE and the hold stays in place. Repeating the cancel request with the same key does not release the funds twice. A payout that is already CANCELLED may be returned as 200 with the same resource and no additional effect.

Manual transfer proof is reviewed by AntaraPay before the payout becomes SUCCEEDED. Clients have no endpoint to upload execution proof, approve, or mark a payout as successful.