Mulai Cepat

Jika Anda hanya ingin menyelesaikan integrasi pertama, halaman ini sudah cukup: buat header yang ditandatangani, buat perintah pembayaran, lalu verifikasi callback dan kembalikan respons 2xx.

Contohnya menggunakan pembuatan pesanan pembayaran secara default. Perintah pembayaran menggunakan tanda tangan, header permintaan, dan header panggilan balik yang sama; hanya titik akhir dan muatan bisnis yang berubah.

API produksihttps://api.uugate.com

Aset yang didukungTRC20-USDT · BEP20-USDT · BEP20-USDC · SPL-USDC

Persiapan callbackAPI Key + notifyUrl

✓Merchant UID adalah identitas pedagang unik yang ditetapkan oleh platform. Ini digunakan dalam payload x-merchant-uid dan callback.

✓Siapkan API Key yang dimulai dengan mch_ dari pengaturan merchant API.

✓Siapkan notifyUrl milik pedagang yang dapat dijangkau publik; itu diperlukan saat membuat pesanan.

Step 1

Hasilkan Header yang Ditandatangani

Permintaan OpenAPI menggunakan lima header: x-api-key, x-merchant-uid, x-timestamp, x-nonce, dan x-signature.

Gunakan mch_ API Key yang sama dengan kunci x-api dan rahasia penandatanganan.
Jalur tanda tangan harus berupa jalur API saja, misalnya /openapi/payin/orders, tanpa domain.
Payload tanda tangan adalah Merchant UID, timestamp, nonce, metode, jalur, kanonik query, dan kanonik body.

Node.js

import { createHmac, randomBytes } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const uid = "880001", key = "mch_xxxxxxxxxxxxxxxxxxxx";
const timestamp = "1776193200000", nonce = "2f5c7b147c3748f0a8b3d9bb38aa91a4";
const method = 'POST', path = '/openapi/payin/orders';
const canonicalQuery = '', canonicalBody = "{\"amount\":\"100.00\",\"chainCode\":\"TRON\",\"merchantOrderNo\":\"M202604150001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/payin-notify\",\"tokenSymbol\":\"USDT\"}";
const payload = [uid, timestamp, nonce, method, path, canonicalQuery, canonicalBody].join('\n');
const signature = createHmac('sha256', key).update(payload, 'utf8').digest('hex');
console.log(signature);

Step 2

Buat pesanan penerimaan

Setelah menyiapkan header yang ditandatangani, panggil perintah pembuatan pembayaran API. Jika berhasil, gunakan orderNo, cashierUrl, dan paymentUri.

Titik akhir: POST /openapi/payin/orders.
Gunakan cashierUrl yang dikembalikan ketika frontend pedagang perlu dialihkan ke pembayaran.
notifyUrl diperlukan dan diteruskan dengan permintaan pesanan. Tidak diperlukan konfigurasi callback backend terpisah.

Node.js

import { createHmac, randomBytes } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const uid = required("UUGATE_MERCHANT_UID"), key = required("UUGATE_API_KEY");
const timestamp = String(Date.now()), nonce = randomBytes(16).toString("hex");
const method = 'POST', path = '/openapi/payin/orders';
const canonicalQuery = '', canonicalBody = "{\"amount\":\"100.00\",\"chainCode\":\"TRON\",\"merchantOrderNo\":\"M202604150001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/payin-notify\",\"tokenSymbol\":\"USDT\"}";
const payload = [uid, timestamp, nonce, method, path, canonicalQuery, canonicalBody].join('\n');
const signature = createHmac('sha256', key).update(payload, 'utf8').digest('hex');
const base = (process.env.UUGATE_BASE_URL || 'https://api.uugate.com').replace(/\/+$/, '');
const response = await fetch(base + path, {
  method, redirect: 'error', signal: AbortSignal.timeout(30000),
  headers: { 'Content-Type': 'application/json', 'x-api-key': key, 'x-merchant-uid': uid,
    'x-timestamp': timestamp, 'x-nonce': nonce, 'x-signature': signature },
  ...(canonicalBody ? { body: canonicalBody } : {}),
});
const raw = await response.text();
if (!response.ok) throw new Error('HTTP ' + response.status + ': ' + (raw || 'empty response body'));
JSON.parse(raw);
console.log(raw);

Step 3

Menerima dan Memproses Panggilan Balik

Saat platform memanggil notifyUrl Anda, verifikasi dengan apiKey terlebih dahulu, perbarui pesanan bisnis setelah verifikasi, lalu kembalikan respons 200 atau 2xx lainnya.

Verifikasi panggilan balik menggunakan apiKey, bukan tanda tangan x OpenAPI.
Untuk pembayaran, perlakukan status=completed sebagai status keberhasilan akhir.
Kode ini hanya memverifikasi callback. Kirim isi asli ke input standar dan petakan header ke UUGATE_CALLBACK_TIMESTAMP, UUGATE_CALLBACK_NONCE, UUGATE_CALLBACK_SIGNATURE. UUGATE_API_KEY harus sama dengan key saat membuat pesanan. Selanjutnya periksa pesanan dan simpan secara idempoten dalam transaksi sebelum mengembalikan HTTP 2xx.

Node.js

import { createHmac, timingSafeEqual } from 'node:crypto';

function required(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(name + ' is required');
  return value;
}
const key = required('UUGATE_API_KEY');
const timestamp = required('UUGATE_CALLBACK_TIMESTAMP'), nonce = required('UUGATE_CALLBACK_NONCE');
const signature = required('UUGATE_CALLBACK_SIGNATURE');
const chunks = [];
for await (const chunk of process.stdin) chunks.push(chunk);
const rawBody = Buffer.concat(chunks);
const expected = createHmac('sha256', key).update(timestamp + '.' + nonce + '.', 'utf8').update(rawBody).digest();
const actual = Buffer.from(signature, 'hex');
if (!/^[a-fA-F0-9]{64}$/.test(signature) || actual.length !== expected.length || !timingSafeEqual(expected, actual))
  throw new Error('Invalid callback signature');
console.log('VERIFIED');

Timestamp, nonce, dan kredensial tetap di bawah adalah nilai uji tanda tangan offline. Untuk permintaan nyata, gunakan timestamp milidetik saat ini dan nonce acak baru. Jalur API tidak memiliki awalan versi; v1 hanya merujuk ke tanda tangan callback.

Menjalankan: simpan Java sebagai UUGateExample.java (UUGateCallback.java untuk callback), lalu gunakan java nama file; PHP: php example.php; Go: go run example.go; Node.js: node example.mjs. Verifikasi callback membaca isi asli dari input standar.

Pembayaran masuk dan pembayaran menggunakan algoritme penandatanganan dan header panggilan balik yang sama, sehingga Anda tidak memerlukan dua alur autentikasi.

Setelah halaman ini masuk akal, lanjutkan ke bawah untuk mengetahui parameter detail, struktur respons, dan unduhan SDK.