Autentikasi

Cara membuktikan bahwa request benar-benar dari Anda, memakai Secret ID dan Secret Key.

Agar server tahu bahwa request benar-benar dari Anda, setiap request wajib membawa dua isian di dalam body JSON. Tidak ada header khusus yang perlu diatur.

Parameter	Tipe	Wajib	Keterangan
`secret_id`	string	Ya	Secret ID Anda. Diawali `ZV`. Dilihat di menu Kredensial API.
`signature`	string	Ya	Tanda tangan: hasil hash MD5 dari gabungan Secret ID, Secret Key, dan (untuk endpoint transaksi) ref_id. Rumusnya di bawah.

Rumus signature

Gabungkan nilai-nilai berikut dengan tanda titik dua : (tanpa spasi), lalu hash dengan MD5. Hasilnya 32 karakter huruf kecil dan angka.

Endpoint	Teks yang di-hash
`/v1/balance, /v1/products`	`secret_id:secret_key`
`/v1/transaction/create`	`secret_id:secret_key:ref_id`
`/v1/transaction/status`	`secret_id:secret_key:ref_id`

Contoh perhitungan

Misalnya data Anda seperti ini:

Data	Nilai
`secret_id`	ZV1234567890ABCD
`secret_key`	abc123secretkey
`ref_id`	INV-1001

Contoh

Cek saldo (tanpa ref_id)
teks yang di-hash : ZV1234567890ABCD:abc123secretkey
signature         : 522600cab7d32af04411bc8f67d08243

Buat transaksi (dengan ref_id)
teks yang di-hash : ZV1234567890ABCD:abc123secretkey:INV-1001
signature         : 4ff61779e78815b545033522b1f4fe4b

Cara mengecekBila hasil MD5 di program Anda sama dengan contoh di atas untuk data yang sama, rumus Anda sudah benar. Pastikan tidak ada spasi atau baris baru di akhir teks, dan hasilnya huruf kecil.

Fungsi siap pakai

Salin salah satu fungsi di bawah ke project Anda. Halaman endpoint lain memakai fungsi bernama zeval ini, jadi Anda tidak perlu menghitung signature berulang kali.

PHP

<?php
$secretId  = 'SECRET_ID_ANDA';
$secretKey = 'SECRET_KEY_ANDA';
$base      = 'https://api.zevaldigital.com';

// $signPart: isi dengan ref_id untuk endpoint transaksi, kosongkan untuk endpoint lain.
function zeval(string $path, array $data = [], string $signPart = ''): array
{
    global $secretId, $secretKey, $base;

    $data['secret_id'] = $secretId;
    $data['signature'] = md5($secretId . ':' . $secretKey . ($signPart !== '' ? ':' . $signPart : ''));

    $ch = curl_init($base . $path);
    curl_setopt_array($ch, [
        CURLOPT_POST           => true,
        CURLOPT_POSTFIELDS     => json_encode($data),
        CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_TIMEOUT        => 30,
    ]);
    $response = curl_exec($ch);

    return json_decode((string) $response, true) ?? ['status' => 'error', 'message' => 'Tidak ada respons'];
}

Node.js

const crypto = require('crypto');

const secretId = 'SECRET_ID_ANDA';
const secretKey = 'SECRET_KEY_ANDA';
const base = 'https://api.zevaldigital.com';

// signPart: isi dengan ref_id untuk endpoint transaksi, kosongkan untuk endpoint lain.
async function zeval(path, data = {}, signPart = '') {
  const signature = crypto
    .createHash('md5')
    .update(secretId + ':' + secretKey + (signPart ? ':' + signPart : ''))
    .digest('hex');

  const response = await fetch(base + path, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ ...data, secret_id: secretId, signature }),
  });
  return response.json();
}

Python

import hashlib
import requests

SECRET_ID = "SECRET_ID_ANDA"
SECRET_KEY = "SECRET_KEY_ANDA"
BASE = "https://api.zevaldigital.com"

# sign_part: isi dengan ref_id untuk endpoint transaksi, kosongkan untuk endpoint lain.
def zeval(path, data=None, sign_part=""):
    raw = SECRET_ID + ":" + SECRET_KEY + (":" + sign_part if sign_part else "")
    payload = {**(data or {}), "secret_id": SECRET_ID, "signature": hashlib.md5(raw.encode()).hexdigest()}
    return requests.post(BASE + path, json=payload, timeout=30).json()

Rahasiakan Secret KeySecret Key sama pentingnya dengan password. Jangan dibagikan, jangan dimasukkan ke aplikasi yang dipakai pengguna akhir, dan jangan ditulis di chat atau repository publik. Bila bocor, buat ulang kuncinya di menu Kredensial API (kunci lama langsung tidak berlaku).

← SebelumnyaPengenalan Berikutnya →Kode Respons