PunyaKios Developer API v1.3.0

PunyaKios Partner API Reference

Dokumentasi resmi PunyaKios Partner API untuk integrasi transaksi digital dan pembayaran online. Terdiri dari 2 modul utama:

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.

2. Payment Link & QRIS Dinamis

Terima pembayaran otomatis dari pelanggan Anda melalui QRIS MPM Nasional atau tautan checkout/in-app deeplink.

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, status sandbox, dan sisa saldo deposit aktif secara realtime.

POST /api/v1/partner/profile
Contoh Request cURL
cURL Command 
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"
Hasil Response Live (HTTP 200)
JSON Response 
{
  "status": "success",
  "message": "Profil partner.",
  "data": {
    "id": 1,
    "name": "PT Maju Mandiri H2H",
    "email": "[email protected]",
    "phone": "081234567890",
    "saldo": 5000000,
    "is_sandbox": false,
    "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://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"
  }'
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).
Contoh Request cURL
cURL Command 
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"
  }'
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://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"
  }'
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://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"
  }'
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://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"
  }'
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 3 channel pembayaran independen: 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: qris (default, MDR 0.7%), punyakios (Bebas Biaya Admin Rp 0 via In-App deeplink), atau link (Payment Link checkout web Snap style).
Contoh Request cURL (Metode QRIS)
cURL Command 
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"
  }'
Hasil Response Live — QRIS (HTTP 200) 
{
  "status": "success",
  "message": "Permohonan deposit saldo berhasil dibuat. Silakan scan QRIS untuk menyelesaikan pembayaran.",
  "data": {
    "external_id": "17885761931337",
    "amount": 100000,
    "fee_amount": 700,
    "total_amount": 100700,
    "payment_method": "qris",
    "qr_string": "00020101021226590014ID.LINKAJA.WWW011893600914300000000002150000000000000005204581253033605802ID5918Punya Kios Payment6007JAKARTA61051234062070703A0163043B6F",
    "status": "pending",
    "sandbox": false,
    "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": "17885761931337",
    "amount": 100000,
    "fee_amount": 0,
    "total_amount": 100000,
    "payment_method": "app",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "deeplink": "punyakios.id://pay/r6Qwe3boW0BEGnXe",
    "status": "pending",
    "sandbox": false,
    "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": "17885761931337",
    "amount": 100000,
    "fee_amount": 0,
    "total_amount": 100000,
    "payment_method": "link",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "status": "pending",
    "sandbox": false,
    "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://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"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Status deposit partner.",
  "data": {
    "external_id": "17885761931337",
    "amount": 100000,
    "status": "paid",
    "payment_method": "paprika_qris",
    "created_at": "2026-09-05T02:43:13.000000Z",
    "updated_at": "2026-09-05T02:44:00.000000Z"
  },
  "code": "2000000"
}
Docs › Terima Pembayaran › QRIS Dinamis MPM

Terima Pembayaran — QRIS Dinamis (MPM)

Menghasilkan string payload QRIS MPM Dinamis resmi Nasional untuk discan menggunakan GoPay, OVO, DANA, ShopeePay, BCA Mobile, Livin', BRImo, dll.

POST /api/v1/partner/payment-request
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
external_id string Wajib ID referensi invoice unik dari sistem Anda (contoh: INV-QRIS-002).
amount number Wajib Nominal pembayaran (min: 1.000, max: 50.000.000).
description string Wajib Keterangan transaksi tagihan (max: 200 karakter).
payment_method string Wajib Isi dengan nilai qris untuk QRIS Dinamis.
fee_charge_to string Opsional user (MDR 0.7% ≤ Rp 100k atau 1.0% > Rp 100k + Rp 200 dibebankan ke pembeli) atau merchant (potong dari saldo Anda). Default: merchant.
Contoh Request cURL
cURL Command 
curl -X POST "https://www.punyakios.id/api/v1/partner/payment-request" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "external_id": "INV-QRIS-002",
    "amount": 25000,
    "description": "Pembelian Voucher Digital",
    "payment_method": "qris",
    "fee_charge_to": "user"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Payment request QRIS dinamis berhasil dibuat",
  "data": {
    "trx_id": "17885761931337",
    "external_id": "INV-QRIS-002",
    "amount": 25000,
    "base_amount": 25000,
    "fee_amount": 375,
    "total_amount": 25375,
    "payment_method": "qris",
    "qris_string": "00020101021226590014ID.LINKAJA.WWW011893600914300000000002150000000000000005204581253033605802ID5918Punya Kios Payment6007JAKARTA61051234062070703A0163043B6F",
    "status": "pending",
    "expires_at": "2026-09-18T06:45:00.000000Z"
  },
  "code": "2000000"
}
Docs › Terima Pembayaran › Tagihan Aplikasi PunyaKios

Terima Pembayaran — Tagihan Aplikasi PunyaKios (In-App)

Membuka pembayaran instan langsung di Aplikasi Punya Kios via deeplink punyakios.id://pay/{slug}. Bebas Biaya Admin (Rp 0 fee) dan tanpa QR Code.

POST /api/v1/partner/payment-request
Parameter Request Body (JSON)
Field Tipe Sifat Keterangan
external_id string Wajib ID referensi invoice unik dari sistem Anda (contoh: INV-APP-001).
amount number Wajib Nominal tagihan (min: 1.000, max: 50.000.000).
description string Wajib Deskripsi pembayaran atau rincian item (max: 200 karakter).
payment_method string Wajib Isi dengan nilai app (atau punyakios) untuk pembayaran via aplikasi PunyaKios.
payer_email string Opsional Email user terdaftar PunyaKios (otomatis dikirim push notifikasi).
Contoh Request cURL
cURL Command 
curl -X POST "https://www.punyakios.id/api/v1/partner/payment-request" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "external_id": "INV-APP-001",
    "amount": 50000,
    "description": "Pembayaran Tagihan Toko",
    "payment_method": "app",
    "payer_email": "[email protected]"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Payment request via Aplikasi PunyaKios berhasil dibuat",
  "data": {
    "trx_id": "1709260042449",
    "external_id": "INV-APP-001",
    "amount": 50000,
    "fee_amount": 0,
    "total_amount": 50000,
    "payment_method": "app",
    "checkout_url": "https://punyakios.id/pay/r6Qwe3boW0BEGnXe",
    "deeplink": "punyakios.id://pay/r6Qwe3boW0BEGnXe",
    "status": "pending",
    "expires_at": "2026-09-18T06:45:00.000000Z"
  },
  "code": "2000000"
}
Docs › Terima Pembayaran › Cek Status Pembayaran

Cek Status Pembayaran (Payment Request)

Mengecek status pembayaran invoice Payment Link atau QRIS secara langsung.

POST /api/v1/partner/check-status
Contoh Request cURL
cURL Command 
curl -X POST "https://www.punyakios.id/api/v1/partner/check-status" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "X-API-SECRET: YOUR_API_SECRET" \
  -d '{
    "external_id": "INV-QRIS-002"
  }'
Hasil Response Live (HTTP 200)
{
  "status": "success",
  "message": "Transaction retrieved successfully",
  "data": {
    "trx_id": "17885761931337",
    "external_id": "INV-QRIS-002",
    "slug": "KkSTU0KvEzIDZ3qR",
    "amount": 25375,
    "status": "paid",
    "description": "Pembelian Voucher Digital",
    "created_at": "2026-09-05T02:40:51.000000Z",
    "paid_at": "2026-09-05T02:41:10.000000Z",
    "qris_string": "00020101021226..."
  },
  "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 hanya perlu mendaftarkan satu URL Webhook Endpoint melalui Administrator PunyaKios (contoh: https://server-mitra.com/api/punyakios/webhook). Seluruh event (update transaksi dan update produk) otomatis dikirimkan ke URL tersebut. Server Anda dapat membedakan tipe event dari field JSON event atau keberadaan ref_id / trx_id.

Tipe Event 1: Notifikasi Transaksi (PPOB & Pembayaran)

Ketika transaksi PPOB selesai (sukses/gagal) atau pembayaran QRIS / Payment Link berhasil diselesaikan, 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: payment_update)
Contoh Incoming Webhook Payload (Payment Link / QRIS):
{
  "event": "payment_update",
  "trx_id": "PRQ-202609050930-ABCD",
  "external_id": "INV-20260905-001",
  "payment_id": "PRQ-202609050930-ABCD",
  "status": "success",
  "amount": 50000,
  "payment_method": "QRIS",
  "user_email": "[email protected]",
  "destination": "Nama Merchant / Store",
  "product_name": "Pembayaran Tagihan Invoice #001",
  "timestamp": "2026-09-05T09:34:31.000000Z"
}
Field Tipe Keterangan
event string Pembeda tipe callback: transaction_update (transaksi PPOB) atau payment_update (QRIS / Payment Link).
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 dibuat.
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).
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 'payment_update':
    default:
        // 2. Tipe Callback: Transaksi PPOB / Pembayaran 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 di database partner
        // if ($status === 'success') { ... }
        http_response_code(200);
        echo json_encode(['status' => 'ok', 'message' => 'Transaction processed']);
        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.