Dokumentasi

Dari nol sampai pembayaran pertama Anda.

Panduan ini membawa Anda melalui integrasi lengkap: autentikasi, membuat pembayaran, mengarahkan pelanggan ke checkout dan mengonfirmasi hasilnya lewat webhook. Kebanyakan developer menyelesaikannya dalam satu sore.

◷ Sandbox akan dibuka lebih dulu untuk developer di daftar tunggu. Kunci live menyusul setelah TujuPay berlisensi.

1. Sebelum memulai

Anda butuh tiga hal. Semua yang ada di panduan ini berjalan di sandbox, jadi tidak ada uang sungguhan yang berpindah.

Akun TujuPay. Daftar dan Anda langsung mendapat kunci uji, tanpa perlu persetujuan.
Server yang bisa mengirim request HTTPS. Bahasa apa pun bisa; contoh di sini memakai curl dan Node.js.
URL HTTPS publik untuk webhook. Untuk pengembangan lokal, tunnel seperti ngrok sudah cukup.

2. Autentikasi request Anda

Setiap request memakai secret key Anda dengan autentikasi HTTP Basic: kunci sebagai username dan password dikosongkan. Kunci uji diawali sk_test_ dan kunci live diawali sk_live_. Simpan secret key hanya di server Anda; jangan pernah menaruhnya di aplikasi mobile atau kode browser.

sk_test_… hanya berfungsi di sandbox dan tidak pernah memindahkan uang sungguhan.
sk_live_… akan diterbitkan setelah bisnis Anda terverifikasi dan TujuPay berlisensi.
Rotasi kunci kapan saja dari dasbor. Kunci lama berhenti berfungsi setelah 24 jam.

curl

curl https://api.tujupay.com/v1/payments \
  -u sk_test_51HxQ2...:

3. Buat pembayaran pertama Anda

Buat pembayaran di server Anda saat pelanggan siap membayar. Kirim nominal dalam sen (RM 189.00 berarti 18900), metode yang Anda terima dan referensi pesanan Anda sendiri. Tambahkan Idempotency-Key agar request yang diulang tidak pernah membuat pembayaran kedua.

amount adalah integer dalam sen. Kami tidak pernah memakai desimal untuk uang.
methods bisa berisi fpx dan duitnow_qr. Kosongkan untuk menawarkan semua metode yang sudah Anda aktifkan.
reference milik Anda: pakai ID pesanan agar pembayaran mudah dicocokkan di sistem Anda.

Node.js

const res = await fetch("https://api.tujupay.com/v1/payments", {
  method: "POST",
  headers: {
    Authorization: "Basic " + btoa(process.env.TUJUPAY_SECRET + ":"),
    "Content-Type": "application/json",
    "Idempotency-Key": "order-2214",
  },
  body: JSON.stringify({
    amount: 18900,            // RM 189.00 in sen
    currency: "myr",
    methods: ["fpx", "duitnow_qr"],
    reference: "ORDER-2214",
    return_url: "https://yourshop.my/orders/2214",
  }),
});

const payment = await res.json();
// payment.checkout_url → send the customer here

4. Arahkan pelanggan ke checkout

Response berisi checkout_url. Arahkan pelanggan ke sana. Mereka memilih bank atau memindai QR, menyetujui pembayaran di aplikasi perbankan, lalu kembali ke return_url yang Anda tentukan.

Checkout berjalan di ponsel apa pun dan menampilkan logo serta detail pesanan Anda.
Saat pelanggan kembali, tampilkan pesan 'sedang diproses' sampai webhook Anda mengonfirmasi hasilnya.
Jangan tandai pesanan sebagai lunas hanya karena pelanggan sudah kembali. Tunggu webhook.

Node.js

// Express example
app.post("/checkout", async (req, res) => {
  const payment = await createPayment(req.body.orderId);
  res.redirect(303, payment.checkout_url);
});

5. Konfirmasi hasilnya lewat webhook

Saat pembayaran berhasil atau gagal, kami mengirim event payment.succeeded atau payment.failed ke URL webhook Anda. Verifikasi tanda tangannya, lalu proses pesanan. Halaman Webhook menjelaskan tanda tangan, percobaan ulang dan setiap event secara rinci.

Balas dengan status 2xx apa pun dalam 10 detik, lalu kerjakan proses yang lambat di latar belakang.
Proses setiap event sekali saja: simpan ID event dan abaikan duplikatnya.

6. Go live

Setelah integrasi Anda berjalan di sandbox, berikut langkah untuk menerima pembayaran sungguhan. Kunci live akan tersedia setelah TujuPay berlisensi dan bisnis Anda terverifikasi.

Selesaikan verifikasi bisnis di dasbor: dokumen SSM, direktur dan rekening bank untuk pencairan.
Ganti sk_test_ dengan sk_live_ dan perbarui URL webhook Anda ke produksi.
Lakukan satu pembayaran sungguhan bernominal kecil lalu refund, untuk memeriksa seluruh alur dari awal sampai akhir.
Aktifkan notifikasi pencairan agar Anda tahu saat uang masuk ke bank.

SebelumnyaIkhtisar Berikutnya Referensi API