Dokumentasi API

REST API untuk membuat transaksi QRIS, memeriksa status, dan menerima notifikasi pembayaran.

Pendahuluan

API Tatsupay berbasis REST. Semua permintaan dan respons memakai JSON, dan setiap permintaan diautentikasi dengan kunci API melalui header Authorization. Tidak ada SDK yang wajib dipasang.

Base URL

Semua endpoint berada di bawah base URL berikut. Seluruh permintaan harus melalui HTTPS.

https://api.tatsupay.com

Autentikasi

Sertakan kunci API sebagai bearer token di header Authorization. Kunci mode uji berawalan sk_test_ dan kunci produksi berawalan sk_live_.

Authorization: Bearer sk_test_your_key_here

Mode uji dan produksi

Setiap akun memiliki dua set kunci yang terpisah. Transaksi mode uji tidak melibatkan dana sungguhan dan dapat dilunasi lewat endpoint simulasi, sehingga seluruh alur integrasi bisa diuji lebih dulu.

Membuat transaksi

Membuat transaksi baru dan mengembalikan data QRIS yang siap ditampilkan kepada pelanggan.

Parameter

• amount — bilangan bulat, nominal dalam rupiah penuh. Wajib.
• payment_method — kode metode pembayaran, misalnya qris. Wajib.
• reference — identitas pesanan di sistem Anda. Opsional, tetapi sangat disarankan untuk rekonsiliasi.

curl -X POST "https://api.tatsupay.com/v1/transactions" \
  -H "Authorization: Bearer sk_test_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "payment_method": "qris",
    "reference": "ORDER-1042"
  }'

{
  "id": "trx_01HQ8Z3XK2M9V4N7P1R5T8W2Y6",
  "status": "pending",
  "amount": 150000,
  "payment_method": "qris",
  "reference": "ORDER-1042",
  "qr_string": "00020101021226...",
  "url_image_qris": "https://api.tatsupay.com/v1/transactions/trx_01HQ8Z3XK2M9V4N7P1R5T8W2Y6/qris.png",
  "expires_at": "2026-10-03T01:15:00Z",
  "created_at": "2026-10-03T00:45:00Z"
}

const res = await fetch('https://api.tatsupay.com/v1/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TATSUPAY_SECRET_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 150000,
    payment_method: 'qris',
    reference: 'ORDER-1042',
  }),
});

const trx = await res.json();

Memeriksa status

Mengambil keadaan terkini satu transaksi. Berguna sebagai pemeriksaan cadangan bila webhook tidak sampai.

curl "https://api.tatsupay.com/v1/transactions/trx_01HQ8Z3XK2M9V4N7P1R5T8W2Y6" \
  -H "Authorization: Bearer sk_test_your_key"

Webhook

Saat transaksi lunas, Tatsupay mengirim permintaan POST ke endpoint yang Anda daftarkan di dashboard. Endpoint Anda harus menjawab dengan status 2xx; bila tidak, pengiriman akan dicoba ulang dengan jeda yang semakin panjang.

{
  "event": "transaction.paid",
  "data": {
    "id": "trx_01HQ8Z3XK2M9V4N7P1R5T8W2Y6",
    "status": "paid",
    "amount": 150000,
    "reference": "ORDER-1042",
    "paid_at": "2026-10-03T00:47:12Z"
  }
}

Status transaksi

• pending — transaksi dibuat, menunggu pembayaran.
• paid — pembayaran diterima dan transaksi lunas.
• expired — batas waktu pembayaran terlewati.
• failed — transaksi gagal dan tidak dapat dibayar.

Penanganan error

Kegagalan dijawab dengan kode status HTTP yang sesuai beserta badan JSON yang memuat kode error. Tangani berdasarkan kode, bukan berdasarkan teks pesan: teks dapat berubah seiring perbaikan, sedangkan kode tidak.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "field": "amount"
  }
}

Batas permintaan

Permintaan dibatasi per kunci API. Bila batas terlampaui, respons yang diterima adalah 429 beserta header Retry-After yang menyatakan berapa detik lagi permintaan dapat diulang.

Untuk mesin dan agen AI

Spesifikasi OpenAPI dan ringkasan dalam teks polos tersedia pada alamat berikut, sehingga alat otomatis tidak perlu mengurai HTML halaman ini.

• /openapi.json
• /llms.txt
• /llms-full.txt