Integrasikan layanan PPOB kami ke sistem Anda

Ringkasan

Semua endpoint merchant memakai path berawalan /v1, mengirim dan menerima JSON, dan dibungkus dalam satu bentuk respons yang konsisten (lihat Format Respons). Kecuali POST /v1/auth, setiap permintaan wajib menyertakan header Authorization: Bearer <token>.

Alur dasar

1. Tukar api_key + secret_key Anda menjadi token lewat POST /v1/auth.
2. (Khusus produk pascabayar) Cek tagihan lewat POST /v1/inquiry untuk tahu nominal sebenarnya.
3. Buat transaksi lewat POST /v1/transactions — dengan atau tanpa callback_url.
4. Pantau hasilnya: lewat respons langsung (mode sinkron), polling GET /v1/transactions/{id}, atau menerima webhook (mode asinkron).

Autentikasi

Tukarkan kredensial Anda dengan token bearer yang dipakai di semua permintaan berikutnya. Token berlaku singkat — desain ini sengaja agar token yang bocor cepat kedaluwarsa dengan sendirinya.

curl -X POST https://api.ppob-anda.co.id/v1/auth \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "mck_live_xxxxxxxxxxxxxxxx",
    "secret_key": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }'

{
  "success": true,
  "data": {
    "token": "7f3a...c91e",
    "expires_in": 30,
    "expires_at": "2026-08-19T04:12:03Z"
  },
  "error": null
}

Authorization: Bearer 7f3a...c91e

Format Respons

Setiap respons — berhasil maupun gagal — memakai bentuk yang sama persis. Anda tidak perlu menebak bentuk respons per endpoint; cukup periksa success.

{
  "success": boolean,
  "data": object | null,
  "error": { "code": string, "message": string } | null
}

Ketiga field selalu ada, termasuk yang bernilai null — data dan error tidak pernah keduanya terisi sekaligus. Lihat daftar lengkap kode error untuk arti tiap error.code.

Tipe Produk

Ada dua tipe produk, dan keduanya menempuh jalur berbeda — ini menentukan apakah Anda perlu memanggil /v1/inquiry sebelum membeli.

Daftar Produk

Katalog produk yang tersedia untuk akun Anda — hanya produk yang sudah di-entitle ke merchant Anda yang muncul di sini.

{
  "success": true,
  "data": {
    "products": [
      {
        "product_code": "V100AXS3a",
        "name": "AXIS 100K",
        "product_type": "prepaid",
        "price_type": "fixed",
        "sell_price": 10000,
        "is_active": true
      },
      {
        "product_code": "4156",
        "name": "PDAM ATB BATAM",
        "product_type": "postpaid",
        "price_type": "by_bill",
        "sell_price": 0,
        "is_active": true
      }
    ]
  },
  "error": null
}

Cek Tagihan

Khusus produk pascabayar. Mengembalikan nominal yang akan ditagihkan beserta informasi pelanggan dari biller — tanpa membuat transaksi apa pun.

{
  "success": true,
  "data": {
    "nominal": 254050,
    "customer_info": "NAMA: BUDI SANTOSO|TARIF/DAYA: R1/900 VA|...",
    "notice": "Bayar sebelum tanggal 20 untuk menghindari denda",
    "extra_info": "",
    "price_is_estimate": true
  },
  "error": null
}

Buat Transaksi

Endpoint inti — membeli produk prabayar atau membayar tagihan pascabayar. Perilakunya bercabang dua tergantung apakah Anda mengirim callback_url.

curl -X POST https://api.ppob-anda.co.id/v1/transactions \
  -H "Authorization: Bearer 7f3a...c91e" \
  -H "Idempotency-Key: order-88213" \
  -H "Content-Type: application/json" \
  -d '{
    "product_code": "4156",
    "bill_number": "119008812",
    "merchant_reference": "order-88213",
    "callback_url": "https://toko-anda.com/webhooks/ppob"
  }'

{
  "success": true,
  "data": {
    "transaction_id": "c2f7c9d1-ee5d-46ef-80c6-0fda54d4e63f",
    "merchant_reference": "order-88213",
    "status": "pending",
    "product_id": "5a65954f-e136-4736-b5f2-2bd3a7d5681c",
    "bill_number": "119008812",
    "nominal": null,
    "serial_number": "",
    "customer_info": "",
    "notice": "",
    "extra_info": "",
    "failure_reason": null,
    "submitted_at": "2026-08-19T04:12:05Z"
  },
  "error": null
}

Detail Transaksi

Ambil status transaksi kapan saja setelah dibuat — dipakai untuk polling pada mode sinkron, atau mengonfirmasi ulang isi webhook yang Anda terima.

Saldo

{
  "success": true,
  "data": {
    "available_balance": 480299,
    "held_balance": 25409
  },
  "error": null
}

Mutasi Saldo

{
  "success": true,
  "data": {
    "entries": [
      {
        "transaction_id": "c2f7c9d1-ee5d-46ef-80c6-0fda54d4e63f",
        "entry_type": "capture",
        "amount": 25409,
        "available_balance_after": 480299,
        "held_balance_after": 0,
        "created_at": "2026-08-18T05:48:48Z"
      }
    ],
    "limit": 20,
    "offset": 0
  },
  "error": null
}

Webhook

Bila Anda mengirim callback_url saat membuat transaksi, kami mengirim satu notifikasi POST ke URL tersebut begitu transaksi mencapai status final.

{
  "transaction_id": "c2f7c9d1-ee5d-46ef-80c6-0fda54d4e63f",
  "merchant_reference": "order-88213",
  "status": "success",
  "nominal": 254050,
  "serial_number": "a2d6adc50f9739d6cc24d019c8d08a43",
  "customer_info": "NAMA: BUDI SANTOSO|...",
  "failure_reason": null,
  "updated_at": "2026-08-19T04:12:41Z"
}

Percobaan ulang

Jika endpoint Anda tidak membalas dengan status 2xx (termasuk timeout), kami mencoba lagi hingga 5 kali dengan jeda sekitar 30 detik antar percobaan. Balas 200 OK secepatnya setelah menerima payload — proses lebih lanjut boleh dilakukan asinkron di sisi Anda, jangan buat kami menunggu.

Idempotency

Header Idempotency-Key pada POST /v1/transactions membuat pengiriman ulang aman.

Bila koneksi Anda putus setelah mengirim permintaan tapi sebelum menerima jawaban, Anda tidak tahu apakah transaksinya benar-benar terbuat. Kirim ulang permintaan yang persis sama dengan Idempotency-Key yang sama, dan Anda akan menerima transaksi yang sudah ada — bukan transaksi baru yang dobel. Gunakan satu key unik per percobaan pembelian (misalnya ID order Anda sendiri), dan jangan pernah memakai ulang key yang sama untuk transaksi yang benar-benar berbeda.

Kode Error

Semua error menjawab dengan error.code yang stabil untuk logika program, dan error.message berbahasa Indonesia untuk ditampilkan.

PRODUCT_NOT_ENTITLED sengaja dipakai untuk dua kondisi berbeda (produk tidak ada / produk ada tapi bukan hak akun Anda) — supaya kode produk milik merchant lain tidak bisa ditebak dengan mencoba satu per satu.

Checklist Integrasi

1. 01Simpan secret_key hanya di server, ambil token baru tepat sebelum tiap panggilan (TTL 30 detik).
2. 02Untuk produk pascabayar, selalu /v1/inquiry dulu dan tampilkan nominalnya ke pelanggan sebelum membayar.
3. 03Pakai Idempotency-Key yang unik per percobaan pembelian — simpan dan kirim ulang key yang sama saat retry.
4. 04Tangani status unknown sebagai "belum pasti", bukan gagal — jangan buat transaksi baru untuk pesanan yang sama.
5. 05Verifikasi X-Callback-Signature sebelum memproses isi webhook apa pun.
6. 06Balas webhook dengan 200 OK secepatnya, proses lanjutannya asinkron di sisi Anda.
7. 07Sediakan polling GET /v1/transactions/{id} sebagai cadangan kalau webhook Anda pernah gagal 5x.