PunyaKios Developer API v1.4.0
Login Partner Daftar Mitra

PunyaKios Partner API Reference

Dokumentasi resmi PunyaKios Partner API untuk integrasi transaksi digital (Host-to-Host) dan pengelolaan saldo Partner.

1. Host-to-Host (H2H) PPOB

Otomasi transaksi Pulsa, Data, Token PLN, Voucher Game, dan Saldo E-Money dengan saldo deposit Partner dan eksekusi instan.

Base Path API

Gunakan Base Path berikut untuk seluruh pemanggilan endpoint API Partner:

BASE PATH /api/v1/partner

Autentikasi & Header Request

Setiap request yang dikirimkan wajib menyertakan kredensial API Partner melalui HTTP Request Header.

Header Key Tipe Sifat Deskripsi
X-API-KEY string Wajib API Key akun partner (contoh: pk_live_xxxxxx).
X-API-SECRET string Wajib API Secret rahasia partner (contoh: ps_live_xxxxxx).
Content-Type string Wajib Harus selalu bernilai application/json.
Accept string Wajib Harus selalu bernilai application/json.
Docs › H2H PPOB › Profil & Saldo

Cek Saldo & Profil Partner

Mendapatkan profil akun partner dan sisa saldo deposit aktif secara realtime.

POST /api/v1/partner/profile
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/profile" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET"
Hasil Response Live (HTTP 200)
JSON Response
{
  "status": "success",
  "message": "Profil partner.",
  "data": {
    "id": 1,
    "name": "PT Maju Mandiri H2H",
    "email": "partner@example.com",
    "phone": "081234567890",
    "saldo": 5000000,
    "webhook_url": "https://server-partner.com/api/webhook",
    "created_at": "2026-09-05T02:32:30.000000Z",
    "updated_at": "2026-09-05T02:32:30.000000Z"
  },
  "code": "2000000"
}
Docs › H2H PPOB › Katalog Produk

Katalog Produk Prabayar

Mengambil daftar produk aktif beserta harga modal H2H khusus Partner.

POST /api/v1/partner/products
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
type string Opsional Tipe produk: prepaid (default) atau pasca.
category string Opsional Filter kategori: pulsa, data, game, pln, emoney.
provider string Opsional Filter provider: TELKOMSEL, DANA, PLN, dll.
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/products" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "type": "prepaid",
    "category": "pulsa"
  }'
Hasil Response Live (HTTP 200)
JSON Response
{
  "status": "success",
  "message": "Daftar produk prabayar partner.",
  "data": {
    "maintenance": false,
    "currency": "IDR",
    "count": 2,
    "products": [
      {
        "sku": "TD5",
        "nama": "Telkomsel 5.000",
        "category": "pulsa",
        "provider": "TELKOMSEL",
        "price": 5550
      },
      {
        "sku": "DANA20",
        "nama": "DANA Rp 20.000",
        "category": "emoney",
        "provider": "DANA",
        "price": 20350
      }
    ]
  },
  "code": "2000000"
}
Docs › H2H PPOB › Order Transaksi

Order Prabayar (H2H Transaction)

Melakukan eksekusi pembelian produk prabayar secara instan dengan proteksi idempotency berbasis ref_id.

POST /api/v1/partner/prepaid/order
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
ref_id string Wajib Nomor referensi unik dari server Anda (max 64 karakter) untuk menjamin idempotency.
sku string Wajib Kode SKU produk (contoh: TD5, DANA20).
customer_no string Wajib Nomor tujuan pengisian (HP / No Meter / ID Akun Game). Untuk game ber-server: [ID],[SERVER].
zone_id / server string Opsional Zone ID atau Server ID game (opsional jika sudah digabung di customer_no).
Panduan Format Tujuan (customer_no) Top Up Game Online
Untuk produk kategori Game, format customer_no disesuaikan dengan kebutuhan game target:
  • Game dengan User ID + Zone ID / Server (Contoh: Mobile Legends, Genshin Impact, Ragnarok):
    Gunakan format [User_ID],[Zone_ID] (dipisahkan tanda koma , tanpa spasi).
    • Mobile Legends: "customer_no": "12345678,1234"
    • Genshin Impact: "customer_no": "801234567,os_asia"
    Tips: Anda juga bisa mengirim field terpisah "zone_id": "1234" atau "server": "1234", sistem akan otomatis menggabungkannya.
  • Game Tanpa Server (Contoh: Free Fire, PUBG Mobile, Valorant):
    Cukup kirimkan User ID murni langsung pada customer_no.
    • Free Fire: "customer_no": "198273645"
    • PUBG Mobile: "customer_no": "5123456789"
    • Valorant: "customer_no": "PlayerName#1234"
Contoh Request cURL (Pulsa / E-Wallet)
cURL Command - Pulsa / E-Wallet
curl -X POST "https://mail.punyakios.id/api/v1/partner/prepaid/order" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "ref_id": "ORDER-TEST-1788576051",
    "sku": "TD5",
    "customer_no": "081234567890"
  }'
Contoh Request cURL (Top Up Game MLBB / Ber-Server)
cURL Command - Game Top Up
curl -X POST "https://mail.punyakios.id/api/v1/partner/prepaid/order" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "ref_id": "ORDER-MLBB-1788576052",
    "sku": "MOBILE_LEGEND86",
    "customer_no": "12345678,1234"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Transaksi diproses.",
  "data": {
    "ref_id": "ORDER-TEST-1788576051",
    "sku": "TD5",
    "customer_no": "081234567890",
    "status": "success",
    "sn": "0905123456789123456",
    "amount": 5550,
    "message": "Transaksi berhasil."
  },
  "code": "2000000"
}
Docs › H2H PPOB › Status Transaksi

Cek Status Transaksi H2H

Memeriksa status mutakhir transaksi H2H menggunakan ref_id.

POST /api/v1/partner/transaction/status
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/transaction/status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "ref_id": "ORDER-TEST-1788576051"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Status transaksi.",
  "data": {
    "trx_id": "2909260062758190",
    "ref_id": "ORDER-TEST-1788576051",
    "customer_no": "081234567890",
    "sku": "TD5",
    "product_name": "Telkomsel 5.000",
    "category": "pulsa",
    "amount": 5550,
    "status": "success",
    "sn": "0905123456789123456",
    "message": "Transaksi berhasil.",
    "created_at": "2026-09-05T09:40:51+07:00"
  },
  "code": "2000000"
}
Docs › H2H PPOB & Produk › Cek Akun Pengguna

Cek Akun Pengguna (Inquiry Nama)

Mengecek keberadaan akun member/pengguna aplikasi PunyaKios dan mendapatkan nama akun yang telah disensor (*masked*) sebelum melakukan transfer saldo.

POST /api/v1/partner/user/inquiry
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
phone string Wajib Nomor handphone atau email pengguna akun PunyaKios (contoh: 089876543210).
Contoh Request Body (JSON)
{
  "phone": "089876543210"
}
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/user/inquiry" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "phone": "089876543210"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Pengguna PunyaKios ditemukan.",
  "data": {
    "name": "B*** S***",
    "phone": "089876543210"
  },
  "code": "2000000"
}
Docs › H2H PPOB & Produk › Topup Saldo User

Topup Saldo Pengguna (Member PunyaKios)

Mengisi saldo akun pengguna/member aplikasi PunyaKios langsung dari saldo deposit Partner H2H secara instan dan realtime.

POST /api/v1/partner/topup-user-balance
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
phone string Wajib Nomor handphone atau email pengguna akun PunyaKios yang akan ditopup.
amount number Wajib Nominal saldo yang akan ditransfer ke akun pengguna (min: 1.000, max: 10.000.000).
ref_id string Wajib ID referensi unik transaksi dari sistem Partner (idempotent).
note string Opsional Catatan / keterangan transaksi topup.
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/topup-user-balance" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "phone": "089876543210",
    "amount": 50000,
    "ref_id": "TOPUP-USER-20260905-001",
    "note": "Hadiah Cashback Member"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Topup saldo pengguna berhasil diproses.",
  "data": {
    "ref_id": "TOPUP-USER-20260905-001",
    "target_user": {
      "name": "B*** S***",
      "phone": "089876543210"
    },
    "amount": 50000,
    "partner_balance": 4950000,
    "status": "success",
    "sn": "SN-TOPUP-USER-20260905-001",
    "message": "Topup saldo pengguna berhasil.",
    "created_at": "2026-09-05T09:47:08.320290Z"
  },
  "code": "2000000"
}
Docs › Topup Saldo Deposit › Deposit Saldo Partner

Topup Saldo Partner (Deposit)

Membuat permohonan pengisian saldo deposit Partner. Mendukung beragam channel pembayaran: Virtual Account (BCA, Mandiri, BRI, BNI, Permata, CIMB, dll), Gerai Retail (Indomaret & Alfamart), QRIS Dinamis, Saldo PunyaKios (Bebas Biaya Admin), atau Payment Link Snap UI.

POST /api/v1/partner/deposit
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
amount number Wajib Nominal deposit yang diinginkan (min: 10.000, max: 50.000.000).
payment_method string Opsional Pilihan channel deposit:
  • : Pembayaran via Gateway untuk Virtual Account dan Gerai Retail (wajib menyertakan parameter payment_channel). Format shorthand seperti _bc, _m2, _ir juga didukung.
  • qris : (Default) QRIS Dinamis Nasional via (MDR 0.7% + Rp 200). Mengembalikan raw payload qr_string.
  • punyakios / app : Saldo PunyaKios (Bebas Biaya Admin Rp 0 via In-App Deeplink).
  • link : Multi-channel Payment Link (halaman web checkout Snap UI).
payment_channel string Kondisional Wajib diisi jika payment_method = . Kode saluran spesifik Bank VA atau Gerai Retail (contoh: BC, M2, BR, I1, IR, FT). Lihat daftar lengkap kode channel pada tabel di bawah.
Daftar Kode Saluran (Channel Code)
Kategori Nama Saluran Kode (payment_channel) Biaya Admin Settlement
Virtual Account BCA Virtual Account BC Rp 5.000 Otomatis (H+2)
Virtual Account Mandiri Virtual Account M2 Rp 4.000 Otomatis (H+1)
Virtual Account BRI Virtual Account BR Rp 3.000 Otomatis (H+1)
Virtual Account BNI Virtual Account I1 Rp 3.000 Otomatis (H+1)
Virtual Account Permata Bank Virtual Account BT Rp 3.000 Otomatis (H+1)
Virtual Account CIMB Niaga Virtual Account B1 Rp 3.000 Otomatis (H+1)
Virtual Account BSI (Bank Syariah Indonesia) VA BV Rp 3.000 Otomatis (H+2)
Virtual Account Danamon Virtual Account DN Rp 3.000 Otomatis (H+1)
Virtual Account Maybank Virtual Account VA Rp 3.000 Otomatis (H+1)
Virtual Account Bank Neo Commerce (BNC) VA NC Rp 3.000 Otomatis (H+1)
Gerai Retail Indomaret IR 1.5% + Rp 1.000 (Min. Rp 2.500) Otomatis (H+2)
Gerai Retail Alfamart / Alfamidi FT Rp 2.500 Otomatis (H+2)
Gerai Retail POS Indonesia PI Rp 2.500 Otomatis (H+2)
Gerai Retail Pegadaian PG Rp 2.500 Otomatis (H+2)
Contoh Request cURL (Virtual Account — BCA)
cURL Command — Virtual Account BCA
curl -X POST "https://mail.punyakios.id/api/v1/partner/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "amount": 100000,
    "payment_method": "",
    "payment_channel": "BC"
  }'
Hasil Response Live — Virtual Account (HTTP 200)
{
  "status": "success",
  "message": "Permohonan deposit  berhasil dibuat.",
  "data": {
    "external_id": "17885761931337",
    "amount": 100000,
    "fee_amount": 5000,
    "total_amount": 105000,
    "payment_method": "",
    "payment_channel": "BC",
    "channel_name": "BCA Virtual Account",
    "va_number": "8077708123456789",
    "payment_url": null,
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "reference": "D12345BCA001",
    "status": "unpaid",
    "created_at": "2026-09-17T06:45:00.000000Z"
  },
  "code": "2000000"
}
Contoh Request cURL (Gerai Retail — Indomaret)
cURL Command — Gerai Retail Indomaret
curl -X POST "https://mail.punyakios.id/api/v1/partner/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "amount": 100000,
    "payment_method": "",
    "payment_channel": "IR"
  }'
Hasil Response Live — Gerai Retail (HTTP 200)
{
  "status": "success",
  "message": "Permohonan deposit  berhasil dibuat.",
  "data": {
    "external_id": "17885761931338",
    "amount": 100000,
    "fee_amount": 2500,
    "total_amount": 102500,
    "payment_method": "",
    "payment_channel": "IR",
    "channel_name": "Indomaret",
    "va_number": "70070123456789",
    "payment_url": "https://app-sandbox..com/redirect.aspx?reference=D12345IR002",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "reference": "D12345IR002",
    "status": "unpaid",
    "created_at": "2026-09-17T06:45:00.000000Z"
  },
  "code": "2000000"
}
Contoh Request cURL (QRIS Dinamis)
cURL Command — QRIS
curl -X POST "https://mail.punyakios.id/api/v1/partner/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "amount": 100000,
    "payment_method": "qris"
  }'
Hasil Response Live — QRIS (HTTP 200)
{
  "status": "success",
  "message": "Permohonan deposit saldo berhasil dibuat. Silakan scan QRIS untuk menyelesaikan pembayaran.",
  "data": {
    "external_id": "17885761931339",
    "amount": 100000,
    "fee_amount": 900,
    "total_amount": 100900,
    "payment_method": "qris",
    "qr_string": "00020101021226590014ID.LINKAJA.WWW011893600914300000000002150000000000000005204581253033605802ID5918Punya Kios Payment6007JAKARTA61051234062070703A0163043B6F",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "status": "unpaid",
    "created_at": "2026-09-17T06:45:00.000000Z"
  },
  "code": "2000000"
}
Hasil Response Live — Saldo PunyaKios (Bebas Biaya Admin - Rp 0, Deeplink)
{
  "status": "success",
  "message": "Permohonan deposit via Saldo PunyaKios berhasil dibuat.",
  "data": {
    "external_id": "17885761931340",
    "amount": 100000,
    "fee_amount": 0,
    "total_amount": 100000,
    "payment_method": "app",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "deeplink": "punyakios.id://pay/r6Qwe3boW0BEGnXe",
    "status": "unpaid",
    "created_at": "2026-09-17T06:45:00.000000Z"
  },
  "code": "2000000"
}
Hasil Response Live — Payment Link Snap UI
{
  "status": "success",
  "message": "Permohonan payment link deposit berhasil dibuat.",
  "data": {
    "external_id": "17885761931341",
    "amount": 100000,
    "fee_amount": 0,
    "total_amount": 100000,
    "payment_method": "link",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "status": "unpaid",
    "created_at": "2026-09-17T06:45:00.000000Z"
  },
  "code": "2000000"
}
Docs › Topup Saldo Deposit › Cek Status Deposit

Cek Status Saldo Partner

Mengecek status pembayaran permohonan deposit saldo Partner.

POST /api/v1/partner/deposit/status
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
external_id string Wajib ID referensi unik deposit yang didapatkan saat membuat permohonan.
Contoh Request cURL
cURL Command
curl -X POST "https://mail.punyakios.id/api/v1/partner/deposit/status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "external_id": "17885761931337"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Status deposit partner.",
  "data": {
    "external_id": "17885761931337",
    "amount": 100000,
    "status": "paid",
    "payment_method": "qris",
    "created_at": "2026-09-05T02:43:13.000000Z",
    "updated_at": "2026-09-05T02:44:00.000000Z"
  },
  "code": "2000000"
}
Docs › Callback & Keamanan › Webhook Notifikasi

Webhook Callback (1 URL Terpadu)

PunyaKios menerapkan Arsitektur 1 URL Webhook Terpadu. Seluruh notifikasi pembaruan transaksi (PPOB & Pembayaran) dan pembaruan katalog produk dikirimkan ke 1 URL Webhook yang sama di server Anda.

Arsitektur 1 URL Webhook Callback Terpadu

Mitra dapat mendaftarkan dan memperbarui satu URL Webhook Endpoint secara mandiri melalui Panel Partner di menu API & Webhook (contoh: https://server-mitra.com/api/punyakios/webhook). Seluruh event (update transaksi PPOB, topup saldo user, deposit saldo partner, pembayaran QRIS, serta update katalog produk) otomatis dikirimkan ke URL tersebut. Server Anda dapat membedakan tipe event dari field JSON event atau keberadaan ref_id / external_id / trx_id.

Tipe Event Notifikasi Webhook

Ketika transaksi selesai, topup diproses, pembayaran diterima, atau deposit saldo partner terkonfirmasi, sistem PunyaKios otomatis mengirimkan HTTP POST ke URL Webhook Anda:

POST {URL_WEBHOOK_ANDA} (Event: transaction_update)
Contoh Incoming Webhook Payload (Transaksi PPOB):
{
  "event": "transaction_update",
  "trx_id": "17885761931337",
  "ref_id": "ORDER-TEST-1788575671",
  "sku": "TD5",
  "customer_no": "081234567890",
  "amount": 5550,
  "status": "success",
  "sn": "0905123456789123456",
  "message": "Transaksi berhasil.",
  "timestamp": "2026-09-05T09:34:31.000000Z"
}
POST {URL_WEBHOOK_ANDA} (Event: user_topup)
Contoh Incoming Webhook Payload (Topup Saldo Pengguna PunyaKios):
{
  "event": "user_topup",
  "trx_id": "17885761931338",
  "ref_id": "TOPUP-USER-20261020-001",
  "sku": "TOPUP_USER_BALANCE",
  "customer_no": "081234567890",
  "target_user_name": "B*** S***",
  "target_user_phone": "081234567890",
  "amount": 50000,
  "status": "success",
  "sn": "SN-TOPUP-USER-20261020-001",
  "message": "Topup saldo pengguna berhasil.",
  "timestamp": "2026-10-20T16:15:00.000000Z"
}
POST {URL_WEBHOOK_ANDA} (Event: deposit_update)
Contoh Incoming Webhook Payload (Deposit Saldo Partner via API):
{
  "event": "deposit_update",
  "trx_id": "DEP-20261020161500",
  "ref_id": "DEP-20261020-001",
  "external_id": "DEP-20261020-001",
  "amount": 100000,
  "status": "success",
  "payment_method": "qris",
  "message": "Deposit saldo partner berhasil via QRIS.",
  "timestamp": "2026-10-20T16:15:00.000000Z"
}
POST {URL_WEBHOOK_ANDA} (Event: payment_update — QRIS)
Contoh Incoming Webhook Payload (QRIS Dinamis & Statis):
{
  "event": "payment_update",
  "trx_id": "PRQ-202610211600-ABCD",
  "external_id": "INV-20261021-001",
  "payment_id": "PRQ-202610211600-ABCD",
  "status": "success",
  "amount": 50000,
  "payment_method": "QRIS",
  "user_email": "pelanggan@example.com",
  "destination": "Nama Merchant / Store",
  "product_name": "Pembayaran Tagihan Invoice #001",
  "timestamp": "2026-10-21T16:04:31.000000Z"
}
POST {URL_WEBHOOK_ANDA} (Event: payment_update — Virtual Account / VA Bank)
Contoh Incoming Webhook Payload (Virtual Account Bank: BCA, Mandiri, BRI, BNI, Permata, CIMB):
{
  "event": "payment_update",
  "trx_id": "PRQ-202610211615-VA01",
  "external_id": "INV-20261021-002",
  "payment_id": "PRQ-202610211615-VA01",
  "status": "success",
  "amount": 125000,
  "payment_method": "VA_BCA",
  "va_number": "8077708123456789",
  "user_email": "pelanggan@example.com",
  "destination": "Nama Merchant / Store",
  "product_name": "Top Up Saldo Game #002",
  "timestamp": "2026-10-21T16:16:02.000000Z"
}
Nilai payment_method akan berisi kode channel VA yang dibayarkan pelanggan (contoh: VA_BCA, VA_MANDIRI, VA_BRI, VA_BNI, VA_PERMATA, VA_CIMB).
POST {URL_WEBHOOK_ANDA} (Event: payment_update — Gerai Retail Indomaret & Alfamart)
Contoh Incoming Webhook Payload (Gerai Retail: Indomaret, Alfamart, Alfamidi):
{
  "event": "payment_update",
  "trx_id": "PRQ-202610211630-RET01",
  "external_id": "INV-20261021-003",
  "payment_id": "PRQ-202610211630-RET01",
  "status": "success",
  "amount": 80000,
  "payment_method": "RETAIL_INDOMARET",
  "payment_code": "8999812345678",
  "user_email": "pelanggan@example.com",
  "destination": "Nama Merchant / Store",
  "product_name": "Pembayaran Tagihan Toko #003",
  "timestamp": "2026-10-21T16:32:15.000000Z"
}
Nilai payment_method akan berisi kode gerai retail: RETAIL_INDOMARET atau RETAIL_ALFAMART.
Field Tipe Keterangan
event string Pembeda tipe callback: transaction_update (transaksi PPOB), user_topup (topup saldo member), deposit_update (deposit saldo partner), atau payment_update (QRIS, VA Bank, & Gerai Retail).
trx_id string Nomor referensi / ID unik transaksi dari sistem PunyaKios.
ref_id / external_id string Nomor invoice / referensi unik transaksi dari sistem Anda saat order/deposit dibuat.
payment_method string Metode/Channel pembayaran yang digunakan pelanggan:
  • QRIS: QRIS
  • Virtual Account (VA): VA_BCA, VA_MANDIRI, VA_BRI, VA_BNI, VA_PERMATA, VA_CIMB
  • Gerai Retail: RETAIL_INDOMARET, RETAIL_ALFAMART
  • E-Wallet: EWALLET_OVO, EWALLET_SHOPEEPAY, EWALLET_DANA
  • Aplikasi: PUNYAKIOS_APP (Saldo internal)
amount number Nominal riil transaksi yang didebit atau dibayarkan.
status string Status akhir transaksi: success, failed, atau pending.
sn string Serial number (SN) dari pihak biller / provider (khusus PPOB & topup saldo).
timestamp string Waktu eksekusi status transaksi (ISO 8601).
Docs › Callback & Keamanan › Webhook Update Produk

Tipe Event 2: Webhook Update Produk

Notifikasi katalog produk dikirimkan ke URL Webhook yang sama dengan transaksi. Setiap kali produk ditambahkan, harga berubah, mengalami gangguan, atau dinonaktifkan, PunyaKios mengirimkan HTTP POST dengan parameter "event": "product_update".

POST {URL_WEBHOOK_ANDA} (Event: product_update)
Contoh Incoming Webhook Payload (Katalog Produk):
{
  "event": "product_update",
  "action": "upsert",
  "products": [
    {
      "sku": "TELKOMSEL50",
      "nama": "Voucher Telkomsel 50K",
      "provider": "Telkomsel",
      "category": "Pulsa",
      "type": "Prepaid",
      "harga": 50000,
      "active": true,
      "problem": false
    }
  ],
  "count": 1,
  "timestamp": "2026-09-26T16:12:05.000000+07:00"
}
Field Tipe Keterangan
event string Pembeda event. Selalu bernilai product_update untuk pembaruan katalog produk.
action string Jenis perubahan: upsert (ditambah/diubah), delete (dihapus), atau sync (perintah sinkronisasi penuh, products kosong).
products array Daftar objek produk yang berubah. Berisi daftar SKU jika action = delete. Kosong saat sinkronisasi penuh katalog.
count int Jumlah item pada products.
timestamp string Waktu kejadian (ISO 8601, WIB / Asia/Jakarta, UTC+7).
Docs › Callback & Keamanan › Validasi Signature

Validasi Signature Webhook

Validasi integritas callback pada 1 URL Webhook Tunggal menggunakan header X-PunyaKios-Signature (HMAC-SHA256) dengan api_secret Anda:

Formula Validasi Berdasarkan Tipe Event
  • Event Update Produk: HMAC-SHA256("product_update.{action}.{count}.{timestamp}", api_secret)
  • Event Transaksi: HMAC-SHA256("{ref_id atau external_id}.{status}.{amount}", api_secret)
Contoh Script Handler Terpadu 1 Webhook (PHP):
<?php
// Endpoint Webhook Tunggal Partner (contoh: /api/punyakios/webhook)
$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);
$incomingSignature = $_SERVER['HTTP_X_PUNYAKIOS_SIGNATURE'] ?? '';
$yourApiSecret = 'ps_live_your_partner_secret_here';

if (empty($data) || empty($incomingSignature)) {
    http_response_code(400);
    echo json_encode(['status' => false, 'message' => 'Payload kosong atau signature tidak disertakan']);
    exit;
}

$event = $data['event'] ?? '';

switch ($event) {
    case 'product_update':
        // 1. Tipe Callback: Update Katalog Produk
        $stringToSign = 'product_update.' . ($data['action'] ?? '') . '.' . ($data['count'] ?? 0) . '.' . ($data['timestamp'] ?? '');
        $expectedSignature = hash_hmac('sha256', $stringToSign, $yourApiSecret);

        if (!hash_equals($expectedSignature, $incomingSignature)) {
            http_response_code(401);
            echo json_encode(['status' => false, 'message' => 'Invalid product signature']);
            exit;
        }

        // Update database produk partner
        // foreach ($data['products'] as $product) { ... }
        http_response_code(200);
        echo json_encode(['status' => 'ok', 'message' => 'Product update processed']);
        break;

    case 'transaction_update':
    case 'user_topup':
    case 'deposit_update':
    case 'payment_update':
    default:
        // 2. Tipe Callback: Transaksi PPOB / Topup User / Deposit Partner / QRIS / Payment Link
        $referenceId = $data['ref_id'] ?? ($data['external_id'] ?? '');
        $status = $data['status'] ?? '';
        $amount = $data['amount'] ?? '';

        $stringToSign = $referenceId . '.' . $status . '.' . $amount;
        $expectedSignature = hash_hmac('sha256', $stringToSign, $yourApiSecret);

        if (!hash_equals($expectedSignature, $incomingSignature)) {
            http_response_code(401);
            echo json_encode(['status' => false, 'message' => 'Invalid transaction signature']);
            exit;
        }

        // Update status transaksi atau deposit di database partner
        // if ($event === 'deposit_update') { /* Tambah saldo lokal partner */ }
        // elseif ($status === 'success') { /* Order sukses */ }
        http_response_code(200);
        echo json_encode(['status' => 'ok', 'message' => 'Event processed successfully']);
        break;

    case 'test_ping':
        // 3. Tipe Callback: Test Ping dari Partner Portal
        http_response_code(200);
        echo json_encode(['status' => 'ok', 'message' => 'Ping connection verified']);
        break;
}
exit;
Docs › Callback & Keamanan › Kode Respon HTTP

Kode Respon HTTP Standar

Daftar kode respon standar API PunyaKios:

HTTP Code Status String Penjelasan & Tindakan
200 OK success Permintaan berhasil dieksekusi atau sedang diproses.
400 Bad Request TRX_INSUFFICIENT_BALANCE / VALIDATION_FAILED Saldo tidak mencukupi atau format parameter request salah.
401 Unauthorized MERCHANT_API_KEY_INVALID / AUTH_UNAUTHORIZED API Key atau API Secret Partner tidak valid / tidak disertakan pada header.
404 Not Found TRX_NOT_FOUND Produk tidak ditemukan atau transaksi tidak ada.
422 Unprocessable Entity TRX_DUPLICATE Nomor ref_id / external_id sudah pernah digunakan.
429 Too Many Requests RATE_LIMIT_EXCEEDED Jumlah request per menit melebihi batas batas rate limit.
503 Service Unavailable MAINTENANCE Layanan atau biller sedang dalam pemeliharaan rutin.