Contoh Permintaan dan Verifikasi Tanda Tangan

Metode permintaan: API terutama memakai `GET` / `POST`; permintaan JSON memakai `application/json`.

Autentikasi: permintaan OpenAPI diverifikasi dengan header dan tanda tangan HMAC-SHA256.

Header

Kolom	Tipe	Wajib	Deskripsi
x-api-key	string	Ya	Pedagang API Key. Gunakan nilai yang diawali dengan mch_ dari halaman pengaturan API pedagang.
x-merchant-uid	string	Ya	Merchant UID.
x-timestamp	string	Ya	13 digit milidetik timestamp. Penyimpangan jam yang diperbolehkan secara default adalah 5 menit.
x-nonce	string	Ya	String acak unik untuk setiap permintaan, hingga 128 karakter. Penggunaan kembali ditolak.
x-signature	string	Ya	Tanda tangan hex dihasilkan dengan HMAC-SHA256. Payload berisi Merchant UID, timestamp, nonce, metode, jalur, query kanonik, dan body kanonik.

Aturan tanda tangan

Permintaan menggunakan application/json. Untuk GET APIs tanpa body, bagian body di tanda tangan adalah string kosong.
Jalur tanda tangan harus berupa jalur API mentah, misalnya /openapi/payin/orders, tanpa domain.
Parameter kueri diurutkan berdasarkan kunci; Kunci JSON body diurutkan sebelum serialisasi.
Kegagalan tanda tangan yang umum mencakup timestamp yang kedaluwarsa, nilai nonce yang berulang, urutan bidang yang tidak konsisten, atau spasi tambahan.

Contoh payload tanda tangan

880001
1776193200000
2f5c7b147c3748f0a8b3d9bb38aa91a4
POST
/openapi/payin/orders

{"amount":"100.00","chainCode":"TRON","merchantOrderNo":"M202604150001","notifyUrl":"https://merchant.example.com/api/uugate/payin-notify","tokenSymbol":"USDT"}

Contoh permintaan lengkap

POST /openapi/payin/orders HTTP/1.1
Host: api.uugate.com
Content-Type: application/json
x-api-key: mch_xxxxxxxxxxxxxxxxxxxx
x-merchant-uid: 880001
x-timestamp: 1776193200000
x-nonce: 2f5c7b147c3748f0a8b3d9bb38aa91a4
x-signature: 6d7e96fdbf3ec37c1ec515540f46c6c19b08754973c43293e54644c2da910838

{
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "merchantOrderNo": "M202604150001",
  "amount": "100.00",
  "notifyUrl": "https://merchant.example.com/api/uugate/payin-notify"
}

Contoh kode tanda tangan

Node.js Contoh Tanda Tangan

import crypto from 'node:crypto';

const merchantUid = '880001';
const apiKey = 'mch_xxxxxxxxxxxxxxxxxxxx';
const timestamp = '1776193200000';
const nonce = '2f5c7b147c3748f0a8b3d9bb38aa91a4';
const method = 'POST';
const path = '/openapi/payin/orders';
const canonicalQuery = '';
const canonicalBody = JSON.stringify({
  amount: '100.00',
  chainCode: 'TRON',
  merchantOrderNo: 'M202604150001',
  notifyUrl: 'https://merchant.example.com/api/uugate/payin-notify',
  tokenSymbol: 'USDT',
});

const payload = [
  merchantUid,
  timestamp,
  nonce,
  method,
  path,
  canonicalQuery,
  canonicalBody,
].join('\n');

const signature = crypto.createHmac('sha256', apiKey).update(payload).digest('hex');
console.log(signature);

Kolom error

Kolom	Tipe	Wajib	Deskripsi
code	number	Ya	Kode kesalahan bisnis.
message	string	Ya	Pesan kesalahan.
data	object \| null	Ya	Data kesalahan tambahan.
requestId	string \| null	Ya	ID jejak permintaan server.

Contoh error

{
  "code": 20011,
  "message": "Invalid API signature",
  "data": null,
  "requestId": "9e0cf688-11fd-4cd2-83aa-61df77123456"
}