Bagian 6–7

Payout

Mengajukan payout, membaca status, daftar, dan membatalkan payout.

Membuat payout

POST/api/v1/payoutspayouts:writeRespons 202

Dana ditahan dari available saat permintaan diterima, lalu menunggu persetujuan admin AntaraPay. Payout dapat ditujukan ke rekening merchant atau pengguna merchant.

Field	Wajib	Keterangan
`reference` / `amount` / `currency`	Ya	Reference unik payout, nominal positif, `IDR`.
`recipient.type`	Ya	`MERCHANT` atau `END_USER`.
`recipient.bank_code`	Ya	Kode bank yang mendukung payout dari `GET /channels`.
`recipient.account_number`	Ya	String nomor rekening; jangan dikonversi ke number agar nol awal tidak hilang.
`recipient.account_name`	Ya	Nama penerima yang diharapkan; hasil verifikasi dapat berbeda dan memerlukan pemeriksaan.
`recipient.customer_reference`	Ya*	Wajib untuk `END_USER`; ID pengguna pada sistem merchant.
`description` / `metadata`	Tidak	Description maksimum 255 karakter; metadata sesuai batas pada Format data.

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"
}

Contoh menggunakan fee payout sementara 0 sebagai usulan v1. total_reserved = amount + fee. Nominal amount adalah nilai yang diminta untuk diterima penerima. Fee efektif mengikuti kebijakan aktivasi. Saldo tidak cukup menghasilkan 409 INSUFFICIENT_BALANCE tanpa membuat payout atau hold parsial.

Detail dan status payout

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

Detail memuat field respons create ditambah updated_at, approved_at, completed_at, failure_code, failure_message, transfer_reference, dan resource_version. Nilai yang belum tersedia adalah null. Nomor rekening lengkap tidak dikembalikan.

Status	Dampak dan tindakan client
`PENDING_APPROVAL`	Saldo sudah ditahan; menunggu pemeriksaan admin.
`APPROVED`	Disetujui, belum tentu dana dikirim. Tidak ada debit available kedua.
`PROCESSING`	Eksekusi berlangsung; jangan kirim ulang atau batalkan.
`SUCCEEDED`	Transfer terkonfirmasi. Selesaikan pencairan pengguna tepat sekali.
`REJECTED` / `CANCELLED`	Tidak dikirim; dana tertahan dilepas.
`FAILED`	Kegagalan pasti; hold dilepas. Investigasi sebelum membuat pengajuan baru.
`UNKNOWN` / `NEEDS_REVIEW`	Hasil belum pasti; saldo tetap reserved. Jangan membuat payout pengganti sampai hasil jelas.

Daftar payout

GET/api/v1/payoutspayouts:read

Query opsional: reference, status, recipient_type, from, to, cursor, limit. from/to memfilter created_at. Envelope pagination sama dengan payin. Item daftar memuat id, reference, amount, fee, currency, status, recipient tersamarkan, created_at, dan completed_at.

Membatalkan payout

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

Idempotency-Key wajib. Body reason wajib, maksimum 255 karakter. Hanya PENDING_APPROVAL atau APPROVED yang belum diklaim execution dapat dibatalkan.

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"
}

Jika cancel beradu dengan execution, server menentukan satu pemenang secara atomik. Setelah execution dimulai, respons 409 INVALID_STATE dan hold tetap berlaku. Request cancel berulang dengan key sama tidak melepaskan dana dua kali. Payout yang sudah CANCELLED dapat dikembalikan sebagai 200 dengan resource yang sama tanpa efek tambahan.

Bukti transfer manual diperiksa AntaraPay sebelum payout menjadi SUCCEEDED. Client tidak memiliki endpoint untuk mengunggah bukti eksekusi, approve, atau menandai payout sukses.