Referensi API#

API merchant RAGH Reader dipakai server Anda untuk membuat tagihan dan payout, membaca statusnya, dan mengelola webhook. Halaman ini memuat semua endpoint, field, batas validasi, dan kode error.

Spesifikasi mesin (OpenAPI 3.1) tersedia di /docs/openapi.yaml. File itu bisa diimpor ke Postman, Insomnia, atau generator klien.

Dasar#

Autentikasi#

Setiap request membawa API key di header Authorization:

Authorization: Bearer rk_live_AbCdEf0123456789AbCdEf0123456789AbCdEf01

• Kunci dibuat per aplikasi di dashboard. Pembuatannya meminta OTP email.
• Bentuk kunci: rk_live_ atau rk_test_, diikuti 40 huruf dan angka.
• Kunci hanya ditampilkan sekali saat dibuat. Server kami hanya menyimpan hash-nya.
• Simpan kunci di server Anda (variabel lingkungan atau secret manager). Jangan menaruhnya di app HP, kode frontend, atau repo git.
• Dashboard menampilkan kapan setiap kunci terakhir dipakai dan dari IP mana. Cabut kunci yang tidak dipakai atau dicurigai bocor.

Kunci yang salah bentuk, tidak dikenal, atau sudah dicabut ditolak dengan 401 invalid_api_key.

Kunci uji dan kunci live#

Setiap endpoint hanya melihat data dengan mode yang sama dengan kuncinya. Tagihan uji tidak bisa dibaca dengan kunci live, dan sebaliknya. Rinciannya di Konsep: mode uji.

Scope#

Setiap kunci punya daftar scope. Request ke endpoint di luar scope kunci ditolak dengan 403 insufficient_scope.

Berikan scope seminimal mungkin. Contoh: server toko cukup payments:read dan payments:write.

Allowlist IP#

Kunci bisa dibatasi ke daftar IP atau rentang CIDR (IPv4 dan IPv6), misalnya 203.0.113.10, 198.51.100.0/24. Request dari IP lain ditolak dengan 403 ip_not_allowed.

Kunci live dengan scope payouts:write wajib memakai allowlist IP. Kunci itu bisa membuat instruksi "transfer ke rekening X". Kalau bocor tanpa batasan, penyerang bisa menyisipkan instruksi transfer ke rekeningnya sendiri. Pakai kunci terpisah khusus payout, dan batasi ke IP server yang membuat payout. Aturan ini juga diperiksa di setiap request: kunci live payouts:write tanpa allowlist ditolak dengan 403 ip_allowlist_required.

Batas kecepatan#

Paling banyak 300 request per menit per API key. Kelebihannya ditolak dengan 429 rate_limited. Tunggu sekitar satu menit, lalu coba lagi.

Jangan memakai polling cepat untuk menunggu status tagihan. Pakai webhook, dan pakai GET hanya untuk rekonsiliasi atau cadangan.

Format error#

Semua error API memakai bentuk yang sama:

{
  "error": {
    "code": "validation_failed",
    "message": "Ada isian yang tidak valid.",
    "fields": {
      "amount": ["The amount field must be at least 1000."]
    }
  }
}

• code stabil dan aman dipakai di kode Anda.
• message berbahasa Indonesia untuk dibaca manusia. Isinya bisa berubah.
• Beberapa error membawa data tambahan: fields (validasi), payment, atau payout (lihat tabel).

Daftar kode error#

Error 5xx dari server kami tidak selalu memakai format di atas. Aman untuk mengulang POST /payments dan POST /payouts dengan reference_id yang sama (lihat Aturan pemanggilan ulang).

ID dan format data#

ID berupa awalan + 26 karakter huruf kecil dan angka. Perlakukan ID sebagai string utuh dengan panjang maksimal 40 karakter.

Nomor transaksi (tx_number) berbentuk <PREFIX>-<YYMMDD>-<urutan>, misalnya TKO-260928-0042. Lihat Konsep.

Ringkasan endpoint#

Tagihan#

POST /api/v1/payments#

Membuat tagihan (uang masuk). Balasan 201 untuk tagihan baru, atau 200 bila tagihan yang sudah ada dipakai lagi (reused: true).

Body:

Mode uji atau live ditentukan oleh kunci, bukan oleh field di body.

Pemilihan rekening bila bank_code tidak dikirim:

1. rekening utama, bila terpantau;
2. rekening lain yang terpantau;
3. rekening utama, meskipun tidak terpantau (tagihan dibuat dengan confirmation_delayed: true).

Bila bank_code dikirim tetapi rekening itu tidak aktif atau belum terverifikasi, balasannya 422 validation_failed dengan error.fields.bank_code.

Contoh request:

curl -X POST https://payment-reader.ragh.co.id/api/v1/payments \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "ORDER-123",
    "amount": 200000,
    "bank_code": "BCA",
    "expires_in_minutes": 1440,
    "description": "Kursus A",
    "customer": { "ref": "CUST-9", "name": "Budi", "contact": "081234567890" },
    "tags": ["produk:kursus-a", "kanal:instagram"],
    "return_url": "https://toko.contoh.id/order/123",
    "metadata": { "cart_id": "C-77" }
  }'

Contoh balasan 201:

{
  "id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna",
  "tx_number": "TKO-260928-0042",
  "reference_id": "ORDER-123",
  "amount": 200000,
  "unique_code": 123,
  "total_amount": 200123,
  "bank": {
    "code": "BCA",
    "name": "BCA",
    "account_number": "1234567890",
    "account_holder": "PT CONTOH JAYA"
  },
  "status": "pending",
  "confirmation_delayed": false,
  "late": false,
  "paid_after_cancel": false,
  "match_type": null,
  "test": false,
  "description": "Kursus A",
  "customer": { "ref": "CUST-9", "name": "Budi", "contact": "081234567890" },
  "tags": ["produk:kursus-a", "kanal:instagram"],
  "metadata": { "cart_id": "C-77" },
  "expires_at": "2026-09-29T10:15:00+07:00",
  "paid_at": null,
  "expired_at": null,
  "cancelled_at": null,
  "created_at": "2026-09-28T10:15:00+07:00",
  "payment_url": "https://payment-reader.ragh.co.id/pay/pay_01j8zq5v3m7c2k9x4h6t1r0bna",
  "reused": false
}

Tampilkan ke pembeli: total_amount (bukan amount), bank, dan batas waktu. Atau cukup arahkan pembeli ke payment_url.

Error yang mungkin: 402 balance_low, 402 subscription_expired, 403 account_suspended, 403 account_terminated, 403 kyc_required, 403 volume_cap_reached, 409 order_already_paid, 409 unique_code_exhausted, 422 validation_failed, 422 no_bank_account.

Aturan pemanggilan ulang#

Memanggil POST /api/v1/payments berulang kali dengan reference_id yang sama selalu aman. Ulangi saja bila koneksi putus atau server Anda tidak yakin apakah request sebelumnya berhasil.

reference_id unik per aplikasi dan per mode (uji/live). Hasilnya bergantung pada tagihan yang sudah ada:

Aturan yang sama berlaku untuk payout, dengan payout_already_sent sebagai pengganti order_already_paid.

Bila satu tagihan untuk sebuah reference_id lunas, tagihan lain yang masih pending untuk reference_id yang sama otomatis dibatalkan.

Saat tagihan lama dipakai lagi (reused: true), field lain di body (bank_code, description, dan seterusnya) diabaikan. Satu-satunya pengecualian: expires_in_minutes dipakai sebagai batas baru saat tagihan kedaluwarsa dibuka lagi.

GET /api/v1/payments/{id}#

Membaca satu tagihan. Balasannya objek tagihan seperti di atas, tanpa field reused.

curl https://payment-reader.ragh.co.id/api/v1/payments/pay_01j8zq5v3m7c2k9x4h6t1r0bna \
  -H "Authorization: Bearer rk_live_…"

Tagihan milik aplikasi lain atau beda mode menghasilkan 404 not_found.

GET /api/v1/payments?reference_id=…#

Semua tagihan untuk satu reference_id, terbaru dulu, paling banyak 50. Berguna untuk melihat riwayat satu order (misalnya tagihan lama yang dibatalkan karena nominal berubah).

{
  "data": [
    { "id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna", "reference_id": "ORDER-123", "status": "paid", "…": "…" },
    { "id": "pay_01j8zp0a1b2c3d4e5f6g7h8j9k", "reference_id": "ORDER-123", "status": "cancelled", "…": "…" }
  ]
}

POST /api/v1/payments/{id}/extend#

Memperpanjang tagihan yang sama. Kode unik dan total tetap. Ini cara yang benar untuk "bayar lagi" (lihat Konsep).

• Bisa untuk tagihan pending, atau expired yang masih dalam masa jeda.
• Selain itu: 409 not_extendable.
• Balasan: objek tagihan terbaru.

POST /api/v1/payments/{id}/cancel#

Membatalkan tagihan pending. Body kosong.

• Totalnya tetap terkunci 48 jam. Bila pembeli tetap mentransfer dalam masa itu, tagihan menjadi lunas dengan late: true dan paid_after_cancel: true, lalu masuk daftar perlu tindakan.
• Tagihan yang bukan pending: 409 not_cancellable.
• Balasan: objek tagihan terbaru.

POST /api/v1/payments/{id}/mark-paid#

Menandai lunas dari sistem Anda, misalnya admin sudah melihat uangnya di mutasi bank sendiri. Body kosong. Sama dengan tombol Tandai lunas di dashboard:

• Tagihan menjadi paid dengan match_type: "manual_unverified", dan webhook payment.paid tetap dikirim.
• Bila notifikasi bank untuk total itu datang belakangan, tagihan menjadi terverifikasi (match_type: "manual") dan Anda menerima payment.verified, bukan uang dobel.
• Tidak terverifikasi dalam 24 jam → masuk daftar perlu tindakan.
• Sudah lunas: 409 already_paid.

Objek tagihan#

Payout#

Payout mencatat transfer keluar yang akan Anda lakukan sendiri. Reader membuktikannya dari notifikasi uang keluar. Payout aktif per rekening setelah transfer uji keluar di app RAGH Reader (lihat Pasang RAGH Reader).

POST /api/v1/payouts#

Body:

Contoh request:

curl -X POST https://payment-reader.ragh.co.id/api/v1/payouts \
  -H "Authorization: Bearer rk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "WD-456",
    "amount": 150000,
    "recipient": {
      "bank_code": "BCA",
      "account_number": "9876543210",
      "account_name": "BUDI SANTOSO"
    },
    "description": "Pencairan komisi September"
  }'

Contoh balasan 201:

{
  "id": "po_01j8zr1c2d3e4f5g6h7j8k9m0n",
  "tx_number": "TKO-260928-0043",
  "reference_id": "WD-456",
  "amount": 150000,
  "unique_code": 123,
  "total_amount": 150123,
  "source_bank": {
    "code": "MANDIRI",
    "name": "Livin' by Mandiri",
    "account_number": "1230000123456",
    "account_holder": "PT CONTOH JAYA"
  },
  "recipient": {
    "bank_code": "BCA",
    "account_number": "9876543210",
    "account_name": "BUDI SANTOSO"
  },
  "status": "pending",
  "confirmation_delayed": false,
  "late": false,
  "sent_after_cancel": false,
  "recipient_check": null,
  "match_type": null,
  "test": false,
  "description": "Pencairan komisi September",
  "tags": [],
  "metadata": {},
  "instruction": "Transfer tepat Rp 150.123 ke BCA 9876543210 a.n. BUDI SANTOSO",
  "expires_at": "2026-09-29T10:20:00+07:00",
  "sent_at": null,
  "expired_at": null,
  "cancelled_at": null,
  "reversed_at": null,
  "created_at": "2026-09-28T10:20:00+07:00",
  "reused": false
}

Tampilkan instruction ke admin yang mentransfer. Admin harus:

1. mentransfer tepat total_amount dari rekening source_bank;
2. memakai app bank di HP yang dibaca Reader;
3. melakukan satu transfer per payout (bukan transfer massal).

Error yang mungkin: 402 balance_low, 402 subscription_expired, 403 account_suspended, 403 account_terminated, 403 kyc_required, 409 payout_already_sent, 409 payout_not_enabled, 409 unique_code_exhausted, 422 validation_failed.

GET /api/v1/payouts/{id}#

Membaca satu payout. Balasannya objek payout tanpa reused.

GET /api/v1/payouts?reference_id=…#

Semua payout untuk satu reference_id, terbaru dulu, paling banyak 50. Balasan: { "data": [ … ] }.

POST /api/v1/payouts/{id}/extend#

Sama dengan perpanjangan tagihan. Body opsional expires_in_minutes (15 – 10.080). Kode dan total tetap. Selain pending atau expired dalam masa jeda: 409 not_extendable.

POST /api/v1/payouts/{id}/cancel#

Membatalkan payout pending. Totalnya tetap terkunci 48 jam. Bila transfer tetap terjadi dalam masa itu, payout menjadi sent dengan late: true dan sent_after_cancel: true, lalu masuk perlu tindakan. Selain pending: 409 not_cancellable.

POST /api/v1/payouts/{id}/mark-sent#

Menandai terkirim dari sistem Anda (cadangan bila notifikasi uang keluar tidak terbaca). Body kosong. Payout menjadi sent dengan match_type: "manual_unverified"; notifikasi uang keluar yang datang belakangan memverifikasinya (payout.verified). Sudah terkirim: 409 already_sent.

Objek payout#

Mutasi#

GET /api/v1/mutations#

Semua mutasi (notifikasi transaksi) yang tercatat di seluruh rekening akun Anda, terbaru dulu. Berguna untuk pembukuan dan rekonsiliasi. Mutasi ignored tidak ditampilkan.

Tulis from dan to dalam WIB, dengan format 2026-09-28 atau 2026-09-28 14:00:00. Tanggal tanpa jam berarti pukul 00.00, jadi untuk "sampai akhir 28 September" pakai to=2026-09-28 23:59:59.

{
  "data": [
    {
      "id": "mut_01j8zqb7r2s3t4v5w6x7y8z9a0",
      "bank": "BCA",
      "direction": "credit",
      "kind": "transfer_in",
      "amount": 200123,
      "fee_amount": null,
      "counterparty_name": "BUDI SANTOSO",
      "match_status": "matched",
      "is_match": true,
      "payment_id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna",
      "payout_id": null,
      "transaction_at": "2026-09-28T10:31:00+07:00",
      "received_at": "2026-09-28T10:31:04+07:00",
      "test": false
    }
  ]
}

Rekening#

GET /api/v1/bank-accounts#

Rekening terverifikasi milik akun Anda, beserta status pemantauan dan payout. Bisa dipanggil dengan kunci apa pun.

{
  "data": [
    {
      "code": "BCA",
      "name": "BCA",
      "account_number": "1234567890",
      "account_holder": "PT CONTOH JAYA",
      "kind": "bank",
      "is_default": true,
      "monitored": true,
      "payout_enabled": false
    }
  ]
}

Event webhook#

GET /api/v1/webhook-events#

Event webhook aplikasi ini beserta percobaan kirim terakhirnya, terbaru dulu. Kunci uji hanya melihat event uji dan kunci live hanya melihat event live; event ping terlihat di keduanya. Aturan yang sama berlaku untuk POST /webhook-events/{id}/resend.

{
  "data": [
    {
      "id": "evt_01j8zqa2b3c4d5e6f7g8h9j0km",
      "type": "payment.paid",
      "status": "pending",
      "attempts": 3,
      "last_error_code": "INVALID_ACK",
      "next_attempt_at": "2026-09-28T10:52:05+07:00",
      "delivered_at": null,
      "created_at": "2026-09-28T10:31:05+07:00",
      "last_delivery": {
        "status_code": 200,
        "error_code": "INVALID_ACK",
        "ack_status": "invalid",
        "duration_ms": 184,
        "at": "2026-09-28T10:37:05+07:00"
      }
    }
  ]
}

Arti error_code ada di Webhook: pemetaan respons.

POST /api/v1/webhook-events/{id}/resend#

Mengirim ulang satu event seketika, sama dengan tombol "Kirim ulang sekarang" di dashboard.

• Berlaku untuk event berapa pun umurnya, termasuk yang sudah failed atau rejected.
• Melewati jadwal otomatis, pemutus sirkuit, dan jeda pengiriman.
• Paling banyak 1 kali per 60 detik per event. Lebih cepat dari itu: 429 resend_cooldown.
• Balasan selalu 200 dengan objek event terbaru. Periksa last_delivery.error_code untuk tahu hasilnya: null berarti berhasil.
• Bila gagal, jadwal otomatis event itu tetap berjalan. Batas 72 jam tidak diperpanjang.

Kirim ulang massal ("semua yang gagal dalam 30 menit terakhir") hanya tersedia di dashboard. Lihat Webhook.

Mode uji#

POST /api/v1/test/simulate#

Memalsukan notifikasi bank untuk tagihan atau payout uji, supaya Anda bisa menguji semua cabang webhook tanpa transfer sungguhan. Hanya bisa dengan kunci rk_test_. Kunci live: 403 test_key_required.

Balasan 200:

{
  "mutation": {
    "id": "mut_01j8zqb7r2s3t4v5w6x7y8z9a0",
    "bank": "UJI",
    "direction": "credit",
    "kind": "transfer_in",
    "amount": 150123,
    "fee_amount": null,
    "counterparty_name": "PEMBELI SIMULASI",
    "match_status": "matched",
    "is_match": true,
    "payment_id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna",
    "payout_id": null,
    "transaction_at": null,
    "received_at": "2026-09-28T10:31:04+07:00",
    "test": true
  },
  "payment": { "id": "pay_01j8zq5v3m7c2k9x4h6t1r0bna", "status": "paid", "late": false, "test": true, "…": "…" }
}

Untuk payout, kunci kedua bernama payout, bukan payment.

Skenario yang bisa diuji:

Pengembalian dana bank (payout.reversed) belum bisa disimulasikan lewat API.

Riwayat versi#