Callback penerimaan

The merchant server is called only after a pay-in completes successfully; the callback status is always completed.

Only final payment results are sent. Any HTTP 2xx response stops delivery immediately. After the first failure, the platform retries in 1 minute; after another failure, it makes a final retry in 5 minutes, for up to 3 attempts total. Callback business times use Beijing time in YYYY/MM/DD HH:mm:ss format.

POSTnotifyUrl dari permintaan pembuatan pesanan pembayaran body

Header

Kolom	Tipe	Wajib	Deskripsi
content-type	application/json	Ya	Selalu aplikasi/json.
x-callback-timestamp	string	Ya	Panggilan balik timestamp dalam milidetik.
x-callback-nonce	string	Ya	Panggilan balik nonce.
x-callback-signature	string	Ya	HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)。
x-callback-signature-algorithm	string	Ya	Selalu HMAC-SHA256.
x-callback-signature-version	string	Ya	Selalu v1.

Parameter

Kolom	Tipe	Wajib	Deskripsi
merchantUid	string	Ya	Merchant UID.
orderNo	string	Ya	Nomor pesanan platform.
merchantOrderNo	string \| null	Ya	Nomor pesanan pedagang.
bindKey	string \| null	Ya	Kunci pengikatan untuk isi ulang anggota. Biasanya kosong untuk pesanan pembayaran bersama.
expectedAmount	string	Ya	Jumlah pesanan.
paidAmount	string	Ya	Jumlah pembayaran sebenarnya.
chainCode	string	Ya	Kode rantai.
tokenSymbol	string	Ya	Simbol token.
txHash	string	Ya	Hash transaksi on-chain.
fromAddress	string \| null	Ya	Alamat pengirim.
status	string	Ya	Final successful pay-in status; always completed.

Contoh permintaan

{
  "merchantUid": "880001",
  "orderNo": "PI1776193200123ABCD1234",
  "merchantOrderNo": "M202604150001",
  "bindKey": "USER_90001",
  "expectedAmount": "100.000000",
  "paidAmount": "100.000000",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "txHash": "f7f17891f52c35d0c93170f0d12bb347ac16ab34853b4bc8dcf7fd0a8c9aa321",
  "fromAddress": "TS7b7iD8G2PaPqK1TqSmLJ9nrrYH4oKX1S",
  "status": "completed"
}

Kolom respons

Kolom	Tipe	Wajib	Deskripsi
HTTP Status	200-299	Ya	Setiap respons 2xx dianggap sukses.
Response Body	string \| json	TIDAK	Respons body dapat disesuaikan.

Contoh respons

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

Contoh kode

Node.js Contoh Verifikasi Panggilan Balik

import express from 'express';
import { verifyCallbackSignature } from 'uugate-openapi-sdk';

const app = express();
app.use(express.json({
  verify: (req, _res, buffer) => {
    req.rawBody = buffer.toString('utf8');
  },
}));

app.post('/merchant/callback', (req, res) => {
  const valid = verifyCallbackSignature({
    apiKey: process.env.UUGATE_API_KEY,
    timestamp: req.header('x-callback-timestamp'),
    nonce: req.header('x-callback-nonce'),
    signature: req.header('x-callback-signature'),
    rawBody: req.rawBody || '',
  });

  if (!valid) {
    return res.status(401).json({ ok: false });
  }

  return res.status(200).json({ ok: true });
});

Catatan

Verifikasi panggilan balik menggunakan apiKey, bukan header permintaan tanda tangan x OpenAPI.
Setelah verifikasi, cocokkan merchant, pesanan, aset, jaringan, dan jumlah. Simpan pembayaran serta hasil secara transaksional dan idempoten berdasarkan nomor platform sebelum merespons 2xx; notifikasi berulang tidak boleh menggandakan kredit atau pengiriman.
Untuk isi ulang anggota, gunakan bindKey secara langsung sebagai pengenal anggota sehingga Anda tidak memerlukan tabel pemetaan orderNo-ke-anggota tambahan.