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:
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. |
Cek Saldo & Profil Partner
Mendapatkan profil akun partner dan sisa saldo deposit aktif secara realtime.
curl -X POST "https://www.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"
{
"status": "success",
"message": "Profil partner.",
"data": {
"id": 1,
"name": "PT Maju Mandiri H2H",
"email": "[email protected]",
"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"
}
Katalog Produk Prabayar
Mengambil daftar produk aktif beserta harga modal H2H khusus Partner.
| 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.
|
curl -X POST "https://www.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"
}'
{
"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"
}
Order Prabayar (H2H Transaction)
Melakukan eksekusi pembelian produk prabayar secara instan dengan proteksi
idempotency berbasis ref_id.
| 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).
|
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 padacustomer_no.
• Free Fire:"customer_no": "198273645"
• PUBG Mobile:"customer_no": "5123456789"
• Valorant:"customer_no": "PlayerName#1234"
curl -X POST "https://www.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"
}'
curl -X POST "https://www.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"
}'
{
"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"
}
Cek Status Transaksi H2H
Memeriksa status mutakhir transaksi H2H menggunakan ref_id.
curl -X POST "https://www.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"
}'
{
"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"
}
Cek Akun Pengguna (Inquiry Nama)
Mengecek keberadaan akun member/pengguna aplikasi PunyaKios dan mendapatkan nama akun yang telah disensor (*masked*) sebelum melakukan transfer saldo.
| Field | Tipe | Sifat | Keterangan |
|---|---|---|---|
phone |
string |
Wajib | Nomor handphone atau email pengguna akun PunyaKios (contoh:
089876543210).
|
{
"phone": "089876543210"
}
curl -X POST "https://www.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"
}'
{
"status": "success",
"message": "Pengguna PunyaKios ditemukan.",
"data": {
"name": "B*** S***",
"phone": "089876543210"
},
"code": "2000000"
}
Topup Saldo Pengguna (Member PunyaKios)
Mengisi saldo akun pengguna/member aplikasi PunyaKios langsung dari saldo deposit Partner H2H secara instan dan realtime.
| 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. |
curl -X POST "https://www.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"
}'
{
"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"
}
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.
| 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:
|
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.
|
| 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) |
curl -X POST "https://www.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"
}'
{
"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"
}
curl -X POST "https://www.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"
}'
{
"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"
}
curl -X POST "https://www.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"
}'
{
"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"
}
{
"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"
}
{
"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"
}
Cek Status Saldo Partner
Mengecek status pembayaran permohonan deposit saldo Partner.
| Field | Tipe | Sifat | Keterangan |
|---|---|---|---|
external_id |
string |
Wajib | ID referensi unik deposit yang didapatkan saat membuat permohonan. |
curl -X POST "https://www.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"
}'
{
"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"
}
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.
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:
{
"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"
}
{
"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"
}
{
"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"
}
{
"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": "[email protected]",
"destination": "Nama Merchant / Store",
"product_name": "Pembayaran Tagihan Invoice #001",
"timestamp": "2026-10-21T16:04:31.000000Z"
}
{
"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": "[email protected]",
"destination": "Nama Merchant / Store",
"product_name": "Top Up Saldo Game #002",
"timestamp": "2026-10-21T16:16:02.000000Z"
}
payment_method akan
berisi kode channel VA yang dibayarkan pelanggan (contoh: VA_BCA,
VA_MANDIRI, VA_BRI, VA_BNI, VA_PERMATA,
VA_CIMB).
{
"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": "[email protected]",
"destination": "Nama Merchant / Store",
"product_name": "Pembayaran Tagihan Toko #003",
"timestamp": "2026-10-21T16:32:15.000000Z"
}
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:
|
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). |
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".
{
"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). |
Validasi Signature Webhook
Validasi integritas callback pada 1 URL Webhook Tunggal
menggunakan header
X-PunyaKios-Signature (HMAC-SHA256) dengan api_secret Anda:
- 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)
<?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;
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. |