Referensi API

Base URL: https://triapay.net. Permintaan server-to-server diotentikasi dengan Authorization: Bearer <api_key>. Sesi browser menggunakan cookie yang diset oleh /auth/login plus token CSRF dari /auth/csrf.

Otentikasi

Dua tingkat key per akun:

Prefiks	Penggunaan
pk_live_*	Produksi. Tidak dapat dilihat ulang setelah dibuat. Putar untuk mengganti.
pk_test_*	Sandbox. Dapat dilihat dari dashboard. Hanya untuk endpoint sandbox.

Putar kunci dan webhook secret dari halaman Integration. Rotasi memerlukan email OTP.

Buat order

POST /api/v1/orders
Authorization: Bearer pk_live_...
Content-Type: application/json

{
  "invoiceId": 12345,
  "userId": 678,
  "baseAmount": "10.00",
  "currency": "USD",
  "chain": "bep20",
  "asset": "USDT",
  "idempotencyKey": "01HT8X1V...-uuid",
  "returnUrl": "https://shop.example.com/orders/12345"
}

Field	Tipe	Catatan
invoiceId	int	ID invoice DHRU Anda.
userId	int	ID user DHRU untuk atribusi kredit.
baseAmount	string	String desimal. Akhiran amount kecil ditambahkan untuk crypto chain.
currency	string	Mata uang sumber.
chain	enum	trc20 | bep20 | binance_pay. BEP20 dan TRC20 juga menerima transfer internal Binance (off-chain) ke alamat deposit yang sama.
asset	enum	USDT | USDC. TRC20 hanya USDT.
idempotencyKey	string	UUID. Permintaan berulang dengan payload sama mengembalikan order yang sama.
returnUrl	string	Target redirect setelah order berakhir.

Respons

{
  "orderId": 4711,
  "checkoutToken": "ck_a8f3...",
  "checkoutUrl": "https://triapay.net/checkout/ck_a8f3...",
  "expectedAmount": "10.0001",
  "matchCode": 1,
  "expiresAt": "2026-05-08T05:30:00Z",
  "status": "pending"
}

Redirect pelanggan ke checkoutUrl. Gunakan expectedAmount sebagai jumlah persis yang harus dikirim pelanggan.

Status order

GET /api/v1/orders/{idempotencyKey}/status
Authorization: Bearer pk_live_...

{
  "orderId": 4711,
  "status": "credited",
  "txHash": "0xabc...",
  "matchedAmount": "10.0001",
  "creditedAt": "2026-05-08T05:18:42Z"
}

Status order membentuk state machine black-box:

• pending — menunggu pembayaran.
• matched — dana diterima, kredit sedang berlangsung.
• credited — sukses terminal. Webhook telah diakui.
• expired — terminal. Pelanggan tidak membayar tepat waktu.
• failed — terminal. Pengiriman webhook menghabiskan retry.
• overpaid — terminal. Pelanggan mengirim lebih dari yang diharapkan. Order tetap dikredit, ditandai untuk review manual.

Kedatangan terlambat (settlement chain setelah expiresAt) tidak dikredit otomatis. Pulihkan dari Admin → Orphan transactions.

Helper sandbox

Tersedia hanya dengan pk_test_*. Paksa status terminal tanpa menunggu settlement chain:

POST /api/v1/sandbox/orders/{idempotencyKey}/force-match
POST /api/v1/sandbox/orders/{idempotencyKey}/force-credit
POST /api/v1/sandbox/orders/{idempotencyKey}/force-expire
POST /api/v1/sandbox/webhook/replay

Body kosong. Mengembalikan order yang diperbarui. Webhook sandbox menyertakan X-Payment-Mode: sandbox; plugin DHRU bawaan memutusnya tanpa mengkredit invoice mana pun.

Checkout untuk pelanggan

Otentikasi token-only. Digunakan oleh halaman checkout terhost:

GET  /api/v1/checkout/{token}/status
GET  /api/v1/checkout/{token}/methods
POST /api/v1/checkout/{token}/select-method

Body select-method: {"chain": "bep20", "asset": "USDT"}. Mengembalikan order dengan alamat deposit, expected amount, QR data URI, dan match code.

Error

Envelope JSON, status HTTP mencerminkan kelas:

{ "error": "invalid_credentials", "code": "unauthorized" }

HTTP	code	Kapan
400	validation_error	Bentuk payload buruk, field wajib hilang.
401	unauthorized	Bearer atau sesi hilang atau tidak valid.
403	forbidden	IP tidak ada di allowlist, hanya sandbox di key live.
404	not_found	Token kedaluwarsa, idempotency key tidak dikenal.
409	conflict	Idempotency-key dipakai ulang dengan payload berbeda.
429	rate_limited	Hormati header Retry-After (detik).
500	internal	Error server. Coba lagi dengan backoff.

Rate limit diberlakukan per akun. Hormati Retry-After pada setiap 429.

Idempotensi

Setiap permintaan yang mengubah state memerlukan idempotencyKey. Mengulang key yang sama dengan payload yang sama mengembalikan order asli. Mengulang key yang sama dengan payload berbeda mengembalikan:

{ "error": "idempotency_payload_mismatch", "code": "conflict" }

Buat key sebagai UUIDv4 per invoice dan simpan di sisi Anda agar retry setelah kegagalan jaringan tidak menyebabkan charge ganda.

---

Butuh lebih?

Apa pun di luar halaman ini tersedia di bawah perjanjian mitra. Hubungi kami via WhatsApp di halaman beranda.