PunyaKios Developer API v1.2.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://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,
    "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://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).
Contoh Request cURL
cURL Command 
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"
  }'
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": {
    "ref_id": "ORDER-TEST-1788576051",
    "ref": "ORDER-TEST-1788576051",
    "tujuan": "081234567890",
    "sku": "TD5",
    "produk": "Telkomsel 5.000",
    "kategori": "pulsa",
    "status": "Success",
    "message": "Transaksi berhasil.",
    "price": 5550,
    "sn": "0905123456789123456",
    "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 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://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": "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://api.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://api.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://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": "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://mail.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://mail.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": "customer@gmail.com"
  }'
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://api.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://mail.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 Notifikasi Callback

Ketika transaksi PPOB atau pembayaran QRIS/Payment Link berhasil dibayar, PunyaKios otomatis mengirimkan HTTP POST ke URL Webhook Anda.

CALLBACK /api/webhook
Contoh Incoming Webhook Payload:
{
  "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"
}
Docs › Callback & Keamanan › Validasi Signature

Validasi Signature Webhook

Validasi integritas callback menggunakan header X-PunyaKios-Signature (HMAC-SHA256) dengan api_secret Anda: 

$rawBody = file_get_contents('php://input');
$data = json_decode($rawBody, true);
$incomingSignature = $_SERVER['HTTP_X_PUNYAKIOS_SIGNATURE'] ?? '';

$stringToSign = ($data['ref_id'] ?? '') . '.' . ($data['status'] ?? '') . '.' . ($data['amount'] ?? '');
$expectedSignature = hash_hmac('sha256', $stringToSign, $yourApiSecret);

if (hash_equals($expectedSignature, $incomingSignature)) {
    // Signature VALID - proses update data di server partner
    http_response_code(200);
    echo json_encode(['status' => 'ok']);
} else {
    // Signature INVALID - tolak request
    http_response_code(400);
    echo json_encode(['status' => 'invalid_signature']);
}
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.