Dokumentasi API

1. Autentikasi & Keamanan

Untuk menjaga keamanan data dan transaksi, sistem kami menerapkan beberapa lapisan keamanan yang WAJIB dipatuhi:

Headers yang Diperlukan:

Cara Membuat X-Signature (HMAC-SHA256):

X-Signature dibuat menggunakan algoritma HMAC-SHA256 dengan format:

HMAC-SHA256(json_string, api_key)

Langkah-langkah:

1. Konversi request body menjadi JSON string (tanpa whitespace tambahan, tanpa escape slash)
2. Gunakan API Key sebagai secret key
3. Hitung HMAC-SHA256 dari JSON string menggunakan API Key
4. Hasil hex string adalah X-Signature

Contoh Implementasi:

<?php
$api_key = 'YOUR_API_KEY';
$data = [
    'kode_produk' => 'DN05',
    'tujuan' => '081234567890'
];

$json_string = json_encode($data, JSON_UNESCAPED_SLASHES);
$signature = hash_hmac('sha256', $json_string, $api_key);

echo "X-Signature: " . $signature;
?>

const crypto = require('crypto');

const apiKey = 'YOUR_API_KEY';
const data = {
    kode_produk: 'DN05',
    tujuan: '081234567890'
};

const jsonString = JSON.stringify(data);
const signature = crypto
    .createHmac('sha256', apiKey)
    .update(jsonString)
    .digest('hex');

console.log('X-Signature:', signature);

import hmac
import hashlib
import json

api_key = 'YOUR_API_KEY'
data = {
    'kode_produk': 'DN05',
    'tujuan': '081234567890'
}

json_string = json.dumps(data, separators=(',', ':'))
signature = hmac.new(
    api_key.encode('utf-8'),
    json_string.encode('utf-8'),
    hashlib.sha256
).hexdigest()

print(f'X-Signature: {signature}')

2. Endpoint: Beli Produk

Endpoint ini digunakan untuk membeli produk yang tersedia di sistem. Anda bisa membeli produk prabayar (seperti pulsa, e-wallet) maupun pascabayar (seperti tagihan listrik, transfer bank).

URL: POST https://snpdigital.sanpay.id/api/h2h/transaksi_produk

Request Body:

{
  "kode_produk": "DN05",
  "tujuan": "081234567890",
  "nominal": 10000,
  "ref_id": "CUSTOM-REF-123"
}

Response Sukses (HTTP 200):

{
  "success": true,
  "data": {
    "ref_id": "SP-1234567890-5678",
    "kode_produk": "DN05",
    "tujuan": "081234567890",
    "status": "sukses",
    "sn": "SN123456789",
    "pesan": "Transaksi berhasil",
    "harga": 5300
  }
}

3. Kategori Produk

Di sistem kami, produk dibagi menjadi tiga kategori utama berdasarkan cara pembeliannya: Prabayar (Nominal Tetap), Pascabayar (Nominal Bebas), dan Pascabayar (Tagihan). Setiap kategori memiliki format request yang berbeda.

A. Produk Prabayar (Nominal Tetap)

Produk prabayar adalah produk yang sudah memiliki nominal tetap dan tidak dapat diubah. Contoh produk: Pulsa, Token Listrik, Paket Data, dll.

Parameter yang diperlukan:

• kode_produk - Kode produk yang ingin dibeli
• tujuan - Nomor tujuan (nomor HP, ID pelanggan, dll)

Contoh Request:

{
  "kode_produk": "PLNT5",
  "tujuan": "081234567890"
}

Contoh produk prabayar: Pulsa (Telkomsel, Indosat, XL, dll), Token Listrik (PLN), Paket Data, Voucher Game, dll.

B. Produk Pascabayar (Nominal Bebas)

Produk pascabayar dengan nominal bebas memungkinkan Anda menentukan nominal sendiri sesuai kebutuhan. Contoh produk: Transfer Bank, Top-up E-Wallet, dll.

Parameter yang diperlukan:

• kode_produk - Kode produk yang ingin dibeli
• tujuan - Nomor tujuan (nomor rekening, nomor pelanggan, dll)
• nominal - Nominal transaksi (wajib diisi)

Contoh Request:

{
  "kode_produk": "DANAP",
  "tujuan": "081234567890",
  "nominal": 10000
}

Contoh produk pascabayar (nominal bebas): Transfer Bank (BCA, Mandiri, BRI, dll), Top-up E-Wallet (DANA, OVO, GoPay, dll), Transfer E-Wallet, dll.

C. Produk Pascabayar (Tagihan)

Produk pascabayar tagihan adalah produk yang memerlukan pengecekan tagihan terlebih dahulu sebelum pembayaran. Untuk produk ini, Anda dapat melakukan cek tagihan terlebih dahulu (gratis, tidak memotong saldo) atau langsung melakukan pembayaran. Contoh produk: PDAM, BPJS Kesehatan, BPJS Ketenagakerjaan, PLN Pascabayar, Telkom, PGN, dll.

Parameter yang diperlukan:

• kode_produk - Kode produk yang ingin dibeli
• tujuan - Nomor tujuan (nomor pelanggan, ID pelanggan, dll)
• tipe - Tipe transaksi: "CEK" untuk cek tagihan (gratis) atau "BYR" untuk pembayaran (default: "BYR")

1. Cek Tagihan (CEK) - Gratis

Gunakan tipe "CEK" untuk mengecek informasi tagihan tanpa melakukan pembayaran. Tidak ada potongan saldo.

Contoh Request:

{
  "kode_produk": "PLNPASC01",
  "tujuan": "441420633686",
  "tipe": "CEK"
}

Contoh Response:

{
  "success": true,
  "data": {
    "ref_id": "SP-1234567890-5678",
    "kode_produk": "PLNPASC01",
    "tujuan": "441420633686",
    "status": "inquiry",
    "inquiry": {
      "nama": "MANNA HUTAGALUNG",
      "tag": 53939,
      "admin": 3000,
      "total": 56939,
      "periode": "202412",
      "reff": "",
      "detail": {
        "tarifDaya": "R1/450VA",
        "lembar": 1,
        "meter": "20438-20555",
        "denda": 0
      }
    },
    "tagihan": 53939,
    "denda": 0,
    "total_tagihan": 53939,
    "harga_jual": 700,
    "total_bayar": 54639
  }
}

Keterangan: total_bayar = total_tagihan (tagihan + denda) + harga_jual (biaya admin sistem)

2. Pembayaran (BYR)

Gunakan tipe "BYR" atau tidak mengisi parameter tipe untuk melakukan pembayaran. Sistem akan otomatis melakukan inquiry, kemudian melakukan pembayaran jika saldo mencukupi.

Contoh Request:

{
  "kode_produk": "PLNPASC01",
  "tujuan": "441420633686",
  "tipe": "BYR"
}

Contoh Response (Berhasil):

{
  "success": true,
  "data": {
    "ref_id": "SP-1234567890-5678",
    "kode_produk": "PLNPASC01",
    "tujuan": "441420633686",
    "status": "sukses",
    "sn": "nama:MANNA HUTAGALUNG/periode:202412/tag:53939/admin:3000/total:56939/reff:3SOL21VS144580568BF2FD1701D5A65F",
    "pesan": "nama:MANNA HUTAGALUNG/periode:202412/tag:53939/admin:3000/total:56939/reff:3SOL21VS144580568BF2FD1701D5A65F",
    "harga": 700,
    "inquiry": {
      "nama": "MANNA HUTAGALUNG",
      "tag": 53939,
      "admin": 3000,
      "total": 56939,
      "periode": "202412",
      "reff": "3SOL21VS144580568BF2FD1701D5A65F",
      "detail": {
        "tarifDaya": "R1/450VA",
        "lembar": 1,
        "meter": "20438-20555",
        "denda": 0
      }
    },
    "tagihan": 53939,
    "denda": 0,
    "total_tagihan": 53939,
    "total_bayar": 54639
  }
}

Contoh produk pascabayar (tagihan): PDAM, BPJS Kesehatan, BPJS Ketenagakerjaan, PLN Pascabayar, Telkom, PGN, Pertagas, Finance, dll.

4. Callback - Notifikasi Real-time

Callback adalah fitur yang memungkinkan sistem kami mengirim notifikasi real-time ke server Anda setiap kali status transaksi berubah.

Format Data Callback (JSON):

POST [URL_CALLBACK_ANDA]
Content-Type: application/json

{
  "ref_id": "SP-1234567890-5678",
  "kode_produk": "DN05",
  "tujuan": "081234567890",
  "status": "sukses",
  "sn": "SN123456789",
  "pesan": "Transaksi berhasil",
  "harga": 5300,
  "timestamp": "2024-01-15 10:30:00"
}

5. Contoh Implementasi Lengkap

Lihat contoh implementasi lengkap di halaman Dokumentasi API setelah login.

6. API List Kategori & Produk

List Kategori: GET https://snpdigital.sanpay.id/api/h2h/list_kategori

List Produk: GET https://snpdigital.sanpay.id/api/h2h/list_produk?kategori={id_kategori}

7. Catatan Penting

• Saldo: Pastikan saldo Anda mencukupi sebelum melakukan transaksi
• Ref ID: Harus unik. Jika tidak diisi, sistem akan generate otomatis
• Status Transaksi: Status dapat berubah dari "pending" ke "sukses" atau "gagal" melalui callback