Buat Dompet Eksklusif

Membuat alamat penerima eksklusif untuk bindKey. Setoran mendatang ke alamat ini secara permanen menjadi milik bindKey tersebut.

Jika notifyUrl disediakan, pesanan isi ulang yang dibuat secara otomatis di masa mendatang untuk alamat eksklusif ini akan melakukan panggilan balik ke URL tersebut terlebih dahulu. Ini berguna ketika setiap situs atau aplikasi menerima notifikasi isi ulang anggotanya sendiri.

POST/openapi/payin/exclusive-bindings

Header

KolomTipeWajibDeskripsi
x-api-keystringYaPedagang API Key. Gunakan nilai yang diawali dengan mch_ dari halaman pengaturan API pedagang.
x-merchant-uidstringYaMerchant UID.
x-timestampstringYa13 digit milidetik timestamp. Penyimpangan jam yang diperbolehkan secara default adalah 5 menit.
x-noncestringYaString acak unik untuk setiap permintaan, hingga 128 karakter. Penggunaan kembali ditolak.
x-signaturestringYaTanda tangan hex dihasilkan dengan HMAC-SHA256. Payload berisi Merchant UID, timestamp, nonce, metode, jalur, query kanonik, dan body kanonik.

Parameter

KolomTipeWajibDeskripsi
chainCodestringYaKode rantai. Nilai yang didukung: TRON / BSC / SOL.
tokenSymbolstringYaSimbol token.
bindKeystringYaKunci pengikatan unik di sisi pedagang. Maksimal 128 karakter.
labelstringTIDAKKomentar yang mengikat. Maksimal 100 karakter.
notifyUrlstringTIDAKPanggilan balik independen URL untuk alamat eksklusif ini. Pesanan yang dibuat secara otomatis dari setoran masa depan akan dipanggil kembali ke sini terlebih dahulu. Maksimal 500 karakter; tujuan jaringan privat, loopback, dan tidak aman dilarang.

Contoh permintaan

{
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "bindKey": "USER_90001",
  "label": "VIP User 90001",
  "notifyUrl": "https://merchant.example.com/api/uugate/member-topup-notify"
}

Kolom respons

KolomTipeWajibDeskripsi
bindingIdnumberYaMengikat ID rekaman.
chainCodestringYaKode rantai.
tokenSymbolstringYaSimbol token.
bindKeystringYaKunci pengikat.
addressIdnumberYaID Alamat.
addressstringYaAlamat penerima eksklusif.
addressTypestringYaSelalu eksklusif.
notifyUrlstring | nullYaURL callback eksklusif yang digunakan oleh binding ini.
statusstringYaMengikat status.

Contoh respons

{
  "bindingId": 70031,
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "bindKey": "USER_90001",
  "addressId": 31088,
  "address": "TQ3sCY8k9h7G9UsApY3JPt5VDpNKr2kJ1E",
  "addressType": "exclusive",
  "notifyUrl": "https://merchant.example.com/api/uugate/member-topup-notify",
  "status": "active"
}

Contoh kode

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.

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/exclusive-bindings';
const canonicalQuery = '', canonicalBody = "{\"bindKey\":\"USER_90001\",\"chainCode\":\"TRON\",\"label\":\"VIP User 90001\",\"notifyUrl\":\"https://merchant.example.com/api/uugate/member-topup-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);

Catatan

  • Jika bindKey yang sama dibuat lagi, platform secara idempoten mengembalikan pengikatan dan alamat yang ada, yang berfungsi dengan baik untuk alur dapatkan atau buat.
  • Untuk isi ulang anggota, lewati notifyUrl pada waktu yang mengikat sehingga setoran dalam jumlah berapa pun ke alamat eksklusif akan dipanggil kembali langsung ke situs atau aplikasi terkait.
  • Keempat bahasa memakai jalur, parameter, dan kontrak respons yang sama. Kredensial dibaca dari UUGATE_MERCHANT_UID dan UUGATE_API_KEY; UUGATE_BASE_URL secara default adalah https://api.uugate.com.
  • canonicalBody adalah JSON ringkas dengan nama kolom terurut. Setelah mengubah parameter, urutkan key objek secara rekursif, pertahankan urutan array, dan gunakan UTF-8 tanpa escape tambahan untuk slash atau Unicode. Nominal berupa string; boolean true / false.
  • Respons sukses langsung berisi objek bisnis tanpa pembungkus code / data. Periksa status HTTP sebelum isi. Error bisnis berisi code, message, data, requestId; penolakan keamanan dapat hanya mengirim HTTP 401 / 403 dengan isi kosong.
  • Setelah timeout atau HTTP 5xx, periksa pesanan sebelum mengulang pembuatan atau pengiriman. Buat timestamp, nonce, dan tanda tangan baru untuk setiap permintaan.