Autentikasi & Signature

Setiap request ke API harus menyertakan 3 parameter ini di dalam body request:

Parameter	Keterangan
`api_id`	API ID anda yang sudah di setting di pengaturan
`timestamp`	Waktu saat request dikirim, dalam format UNIX timestamp
`signature`	Signature untuk validasi request, dihasilkan dari kombinasi parameter dan secret key

Toleransi timestamp ±30 detik

timestamp divalidasi ketat — hanya diterima jika selisihnya maksimal 30 detik dari waktu server IsiKuota. Pastikan jam server Anda tersinkronisasi via NTP, kalau tidak semua request akan gagal dengan SESSION_EXPIRED meski signature benar.

Signature sekali pakai & rate limit

Setiap signature hanya bisa dipakai satu kali — mengirim ulang signature yang sama (retry naif) akan ditolak dengan DUPLICATE_TRANSACTION. Selalu generate timestamp + signature baru untuk setiap request, termasuk saat retry.

Cara Mendapatkan API Key

Login ke Dashboard IsiKuota
Buka Pengaturan → API
Salin api_id, api_key, dan secret_key

danger

Jangan pernah membagikan api_key dan secret_key kepada siapapun. Simpan dengan aman di environment variables atau konfigurasi server Anda.

Cara Membuat Signature

Signature berfungsi seperti tanda tangan digital

Membuktikan bahwa request benar-benar dikirim oleh Anda (autentikasi)
Isi body request tidak dimodifikasi dalam perjalanan (integritas)

Server akan menolak request yang signature-nya tidak cocok.

Formula Signature:

hash_hmac('sha256', api_id|api_key|timestamp|body_hash
, SecretKey)

Penjelasan Per Langkah

Langkah 1 — Komponen Signature:

Parameter	Keterangan
`api_id`	API ID Anda
`api_key`	API Key Anda
`timestamp`	Waktu saat request dikirim UNIX timestamp (detik)
`body_hash`	SHA-256 dari raw body request. Jika request tidak memiliki body, gunakan hash dari string kosong: hash('sha256', '')

Langkah 2 — Gabungkan keempat komponen dengan karakter | (pipe):

api_id|api_key|timestamp|body_hash

Langkah 3 — Buat HMAC-SHA256 dari string di atas menggunakan SecretKey Anda:

$bodyHash     = hash('sha256', $canonicalBody);
$stringToSign = implode('|', [$api_id, $api_key, $timestamp, $bodyHash]);
$signature    = hash_hmac('sha256', $stringToSign, 'your_secret_key');

Langkah 4 — Urutkan parameter bisnis dari A ke Z

Sebelum di-hash, semua parameter bisnis harus diurutkan berdasarkan nama kunci secara alfabetis menggunakan ksort. Ini memastikan urutan kunci selalu konsisten antara sisi Anda dan server IsiKuota.

ksort($businessParams);
// Sebelum: customer_no, code, cmd
// Sesudah: cmd, code, customer_no ✓

warning

Jika urutan berbeda, body_hash yang dihasilkan akan berbeda dan signature akan ditolak server.

Langkah 5 — Encode menjadi JSON string lalu hitung body_hash

Jadikan parameter bisnis yang sudah diurutkan sebagai JSON tanpa spasi tambahan, lalu hash dengan SHA-256.

$canonicalBody = json_encode($businessParams, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
// Hasil: {"cmd":"prepaid","code":"TSEL5","customer_no":"08123456789"}

$body_hash = hash('sha256', $canonicalBody);

Jika tidak ada parameter bisnis (seperti saat cek saldo), gunakan string kosong: hash('sha256', '').

Contoh Kode Lengkap

<?php
header('Content-Type: application/json');

$api_id     = 'your_api_id';
$api_key    = 'your_api_key';
$secret_key = 'your_secret_key';
$timestamp  = time();

// Parameter bisnis (tanpa api_id, timestamp, signature)
$businessParams = [
    'cmd'         => 'prepaid',
    'code'        => 'TSEL5',
    'customer_no' => '08123456789',
    'ref_id'      => "TRX12345asdxxx", // Opsional, untuk id unik di sistem Anda
    'testing'     => true,             // Opsional, untuk mode testing (tidak memproses transaksi nyata)
];

// Urutkan A ke Z
ksort($businessParams);

// Jadikan JSON (kosong jika tidak ada parameter bisnis)
$canonicalBody = empty($businessParams)
    ? ''
    : json_encode($businessParams, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);

// Hitung signature
$bodyHash     = hash('sha256', $canonicalBody);
$stringToSign = implode('|', [$api_id, $api_key, $timestamp, $bodyHash]);
$signature    = hash_hmac('sha256', $stringToSign, $secret_key);

// Kirim request
$payload = array_merge($businessParams, [
    'api_id'    => $api_id,
    'timestamp' => $timestamp,
    'signature' => $signature,
]);

$ch = curl_init('https://api.isikuota.com/v1/transaction');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($payload),
]);
$response = json_decode(curl_exec($ch), true);
// print_r($response);
echo json_encode($response, JSON_PRETTY_PRINT);

const crypto = require('crypto');

const api_id     = 'your_api_id';
const api_key    = 'your_api_key';
const secret_key = 'your_secret_key';
const timestamp  = Math.floor(Date.now() / 1000);

// Parameter bisnis
const businessParams = {
  cmd: 'prepaid',
  code: 'TSEL5',
  customer_no: '08123456789',
  ref_id: 'TRX12345asdxxx',   // Opsional, untuk id unik di sistem Anda
  testing: true,              // Opsional, untuk mode testing (tidak memproses transaksi nyata)
};

// Urutkan A ke Z
const sorted = Object.fromEntries(
  Object.keys(businessParams).sort().map(k => [k, businessParams[k]])
);

// Jadikan JSON (kosong jika tidak ada parameter bisnis)
const canonicalBody = Object.keys(sorted).length === 0
  ? ''
  : JSON.stringify(sorted);

// Hitung signature
const bodyHash     = crypto.createHash('sha256').update(canonicalBody).digest('hex');
const stringToSign = `${api_id}|${api_key}|${timestamp}|${bodyHash}`;
const signature    = crypto.createHmac('sha256', secret_key).update(stringToSign).digest('hex');

// Kirim request
const response = await fetch('https://api.isikuota.com/v1/transaction', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ ...sorted, api_id, timestamp, signature }),
});
const data = await response.json();

import hmac, hashlib, time, json, requests

api_id     = 'your_api_id'
api_key    = 'your_api_key'
secret_key = 'your_secret_key'
timestamp  = int(time.time())

# Parameter bisnis
business_params = {
    'cmd':         'prepaid',
    'code':        'TSEL5',
    'customer_no': '08123456789',
    'ref_id':      'TRX12345asdxxx',   # Opsional, untuk id unik di sistem Anda
    'testing':     True,               # Opsional, untuk mode testing (tidak memproses transaksi nyata)
}

# Urutkan A ke Z
sorted_params = dict(sorted(business_params.items()))

# Jadikan JSON (kosong jika tidak ada parameter bisnis)
canonical_body = '' if not sorted_params else json.dumps(
    sorted_params, ensure_ascii=False, separators=(',', ':')
)

# Hitung signature
body_hash      = hashlib.sha256(canonical_body.encode()).hexdigest()
string_to_sign = f'{api_id}|{api_key}|{timestamp}|{body_hash}'
signature      = hmac.new(secret_key.encode(), string_to_sign.encode(), hashlib.sha256).hexdigest()

# Kirim request
payload = {**sorted_params, 'api_id': api_id, 'timestamp': timestamp, 'signature': signature}
response = requests.post('https://api.isikuota.com/v1/transaction', json=payload)
data = response.json()

API_ID="your_api_id"
API_KEY="your_api_key"
SECRET="your_secret_key"
TIMESTAMP=$(date +%s)

# Parameter bisnis — key wajib urut A ke Z
CANONICAL_BODY='{"cmd":"prepaid","code":"TSEL5","customer_no":"08123456789","ref_id":"TRX12345asdxxx","testing":true}'

# Hitung signature
BODY_HASH=$(echo -n "$CANONICAL_BODY" | sha256sum | awk '{print $1}')
STRING_TO_SIGN="${API_ID}|${API_KEY}|${TIMESTAMP}|${BODY_HASH}"
SIGNATURE=$(echo -n "$STRING_TO_SIGN" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')

# Kirim request
curl -X POST https://api.isikuota.com/v1/transaction \
  -H "Content-Type: application/json" \
  -d "{
    \"api_id\":      \"$API_ID\",
    \"timestamp\":   $TIMESTAMP,
    \"signature\":   \"$SIGNATURE\",
    \"cmd\":         \"prepaid\",
    \"code\":        \"TSEL5\",
    \"customer_no\": \"08123456789\",
    \"ref_id\":      \"TRX12345asdxxx\",  # Opsional, untuk id unik di sistem Anda
    \"testing\":     true                 # Opsional, untuk mode testing (tidak memproses transaksi nyata)
  }"

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.Map;
import java.util.TreeMap;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.net.http.*;
import java.net.URI;

public class IsiKuotaSignature {

    static String sha256(String input) throws Exception {
        MessageDigest digest = MessageDigest.getInstance("SHA-256");
        byte[] hash = digest.digest(input.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    static String hmacSha256(String data, String key) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
        byte[] hash = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {
        String apiId     = "your_api_id";
        String apiKey    = "your_api_key";
        String secretKey = "your_secret_key";
        long   timestamp = Instant.now().getEpochSecond();

        // Parameter bisnis — gunakan TreeMap agar otomatis urut A ke Z
        TreeMap<String, String> businessParams = new TreeMap<>();
        businessParams.put("cmd",         "prepaid");
        businessParams.put("code",        "TSEL5");
        businessParams.put("customer_no", "08123456789");
        businessParams.put("ref_id",      "TRX12345asdxxx"); // Opsional, untuk id unik di sistem Anda
        businessParams.put("testing",     "true");           // Opsional, untuk mode testing (tidak memproses transaksi nyata)

        // Jadikan JSON
        ObjectMapper mapper = new ObjectMapper();
        String canonicalBody = businessParams.isEmpty() ? "" : mapper.writeValueAsString(businessParams);

        // Hitung signature
        String bodyHash     = sha256(canonicalBody);
        String stringToSign = apiId + "|" + apiKey + "|" + timestamp + "|" + bodyHash;
        String signature    = hmacSha256(stringToSign, secretKey);

        // Gabungkan payload
        Map<String, Object> payload = new java.util.LinkedHashMap<>(businessParams);
        payload.put("api_id",    apiId);
        payload.put("timestamp", timestamp);
        payload.put("signature", signature);

        // Kirim request
        String body = mapper.writeValueAsString(payload);
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api.isikuota.com/v1/transaction"))
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class IsiKuotaSignature
{
    static string Sha256(string input)
    {
        using var sha = SHA256.Create();
        var bytes = sha.ComputeHash(Encoding.UTF8.GetBytes(input));
        return BitConverter.ToString(bytes).Replace("-", "").ToLower();
    }

    static string HmacSha256(string data, string key)
    {
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
        var bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
        return BitConverter.ToString(bytes).Replace("-", "").ToLower();
    }

    static async Task Main()
    {
        var apiId     = "your_api_id";
        var apiKey    = "your_api_key";
        var secretKey = "your_secret_key";
        var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

        // Parameter bisnis — gunakan SortedDictionary agar otomatis urut A ke Z
        var businessParams = new SortedDictionary<string, string>
        {
            { "cmd",         "prepaid" },
            { "code",        "TSEL5"  },
            { "customer_no", "08123456789" },
            { "ref_id",      "TRX12345asdxxx" }, // Opsional, untuk id unik di sistem Anda
            { "testing",     "true" }            // Opsional, untuk mode testing (tidak memproses transaksi nyata)
        };

        // Jadikan JSON (kosong jika tidak ada parameter bisnis)
        var canonicalBody = businessParams.Count == 0
            ? ""
            : JsonSerializer.Serialize(businessParams);

        // Hitung signature
        var bodyHash     = Sha256(canonicalBody);
        var stringToSign = $"{apiId}|{apiKey}|{timestamp}|{bodyHash}";
        var signature    = HmacSha256(stringToSign, secretKey);

        // Gabungkan payload
        var payload = new Dictionary<string, object>(businessParams.Select(x =>
            new KeyValuePair<string, object>(x.Key, x.Value)))
        {
            { "api_id",    apiId     },
            { "timestamp", timestamp },
            { "signature", signature },
        };

        // Kirim request
        using var client = new HttpClient();
        var json    = JsonSerializer.Serialize(payload);
        var content = new StringContent(json, Encoding.UTF8, "application/json");
        var response = await client.PostAsync("https://api.isikuota.com/v1/transaction", content);
        Console.WriteLine(await response.Content.ReadAsStringAsync());
    }
}

Cek Saldo (Tanpa Parameter Bisnis)

Untuk endpoint yang tidak punya parameter tambahan, canonicalBody cukup diisi string kosong:

$bodyHash     = hash('sha256', '');  // string kosong
$stringToSign = implode('|', [$api_id, $api_key, $timestamp, $bodyHash]);
$signature    = hash_hmac('sha256', $stringToSign, $secret_key);

Signature Salah? Cek Ini

Error	Penyebab Umum
`INVALID_SIGNATURE`	Parameter bisnis tidak diurutkan A–Z, atau `secret_key` salah
`UNAUTHORIZED`	`api_id` tidak ditemukan
`INVALID_API_KEY`	`api_key` salah
`SESSION_EXPIRED`	`timestamp` berbeda lebih dari 30 detik dari waktu server — pastikan jam server Anda tersinkronisasi (NTP)
`IP_NOT_ALLOWED`	IP server Anda tidak ada di whitelist IP akun
`DUPLICATE_TRANSACTION`	`signature` yang sama dikirim ulang — signature hanya bisa dipakai satu kali (proteksi replay attack), buat signature baru untuk setiap request
`TOO_MANY_REQUESTS`	Melebihi batas 1000 request/menit per `api_id`

Checklist debugging

Parameter bisnis sudah diurutkan A ke Z (ksort)
api_key yang dipakai di stringToSign, bukan api_id
timestamp dalam detik, bukan milidetik
JSON tidak ada spasi tambahan (JSON_UNESCAPED_SLASHES)

Cara Mendapatkan API Key​

Cara Membuat Signature​

Formula Signature:​

Penjelasan Per Langkah​

Contoh Kode Lengkap​

Cek Saldo (Tanpa Parameter Bisnis)​

Signature Salah? Cek Ini​