Dokumentasi API.

Satu API untuk membuat tautan pembayaran, mengecek pembayaran, dan menerima webhook. Semua contoh bisa dicoba di sandbox dengan secret key ub_test_.

Mulai cepat

Daftar, buka Developer → Secret Key di dashboard, lalu buat key. Key lengkapnya hanya ditampilkan sekali; simpan di environment server, jangan di aplikasi atau website. Lalu buat tautan pertama:

TerminalShell
curl -X POST https://api.udahbayar.id/v1/payment-links \
  -H "Authorization: Bearer $UDAHBAYAR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Workshop Latte Art", "amount": 175000 }'

Respons berisi url: halaman pembayaran yang kamu bagikan ke pembeli. Di sandbox, pembeli bisa menekan tombol simulasi untuk melunasinya tanpa uang sungguhan.

Autentikasi

Kirim secret key sebagai bearer token di setiap permintaan. Key menentukan mode: ub_test_ hanya melihat data sandbox, ub_live_ hanya data live. Key yang dicabut di dashboard langsung berhenti bekerja.

HeaderHTTP
Authorization: Bearer ub_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Batas permintaan 120 per menit per akun; di atasnya API membalas 429.

Idempotensi

Koneksi bisa putus setelah permintaan sampai di server kami. Supaya aman diulang, kirim header Idempotency-Key di setiap POST, misalnya nomor pesananmu. Permintaan ulang dengan key yang sama dibalas respons pertama apa adanya, dengan header Idempotent-Replayed: true, tanpa membuat tautan atau pembayaran kedua.

HeaderHTTP
Idempotency-Key: order-1001
  • Key berlaku 24 jam, per secret key mode (sandbox dan live terpisah), maksimal 255 karakter.
  • Key yang sama untuk isi permintaan berbeda ditolak 422 idempotency_key_reused.
  • Selama permintaan pertama masih diproses, ulangan dibalas 409 idempotency_in_progress.
  • Error server (5xx) tidak disimpan, jadi permintaan boleh diulang dengan key yang sama.

Metode pembayaran

GET/v1/methods?amount=175000

Metode yang aktif untuk akunmu beserta code-nya, dipakai di POST /v1/payments. Biaya berupa persen dan/atau nominal tetap. Dengan amount, respons juga berisi feeAmount dan net untuk nominal itu. Metode yang kamu matikan di dashboard tidak ikut.

ResponsJSON
{
  "data": [
    {
      "code": "qris",
      "type": "qris",
      "name": "QRIS",
      "fee": { "percent": 0.7, "flat": 0 },
      "expiresInSecs": 900,
      "feeAmount": 1225,
      "net": 173775
    },
    {
      "code": "va_bca",
      "type": "va",
      "name": "BCA Virtual Account",
      "fee": { "percent": 0, "flat": 4000 },
      "expiresInSecs": 86400,
      "feeAmount": 4000,
      "net": 171000
    }
  ]
}

Kode yang tersedia: qris; va_bca, va_bni, va_bri, va_mandiri, va_permata, va_cimb; gopay, ovo, dana, shopeepay, linkaja; card; alfamart, indomaret; kredivo, akulaku.

Tautan pembayaran

POST/v1/payment-links

Buat tautan pembayaran. Tautan masuk ke kantong yang kamu pilih lewat kode kantongnya; tanpa kode, uangnya masuk ke kantong utama.

KolomTipeKeterangan
titlewajibstringJudul yang tampil di halaman pembayaran, maksimal 255 karakter.
amountwajibintegerNominal dalam rupiah, minimal 10000.
pocketstringKode kantong, 12 karakter, dari Pengaturan → Kantong. Tidak peka huruf besar/kecil. Kosong atau tidak dikirim: kantong utama.
multiplebooleantrue untuk tautan multi-pakai. Bawaan false (sekali bayar).
maxUsageintegerKuota pembayaran untuk tautan multi-pakai, 1–10.000. Wajib bila multiple bernilai true.
expiresAtstringWaktu ISO 8601 setelah tautan tidak bisa dibayar lagi, harus di masa depan.
payerFieldsobjectData pembeli yang diminta di halaman pembayaran: name, email, phone (boolean).
returnUrlstringURL http(s) tokomu. Setelah lunas, pembeli dibawa kembali ke sini (otomatis setelah 5 detik).
BodyJSON
{
  "title": "Workshop Latte Art",
  "amount": 175000,
  "pocket": "PK7Q2M9XW4AB",
  "multiple": true,
  "maxUsage": 25,
  "payerFields": { "name": true, "email": true, "phone": false }
}
Respons 201JSON
{
  "id": "128",
  "code": "f11ae206-2126-4ab2-a285-f65f57530197",
  "url": "https://pay.udahbayar.id/f11ae206-2126-4ab2-a285-f65f57530197",
  "title": "Workshop Latte Art",
  "amount": 175000,
  "status": "open",
  "multiple": true,
  "maxUsage": 25,
  "paidCount": 0,
  "pocket": { "code": "PK7Q2M9XW4AB", "name": "Workshop" },
  "mode": "test",
  "payerFields": { "name": true, "email": true, "phone": false },
  "returnUrl": null,
  "expiresAt": null,
  "createdAt": "2026-11-20T03:12:45.000Z"
}

Kode kantong yang tidak ditemukan dibalas 400 dengan error di kolom pocket; tautan tidak dibuat.

GET/v1/payment-links?status=open&page=1

Daftar tautan di mode key, terbaru dulu, dengan meta.total.

GET/v1/payment-links/{code}

Satu tautan, termasuk paidCount dan status.

POST/v1/payment-links/{code}/cancel

Tutup tautan yang masih terbuka. Mengirim webhook payment_link.cancelled.

Pembayaran

Pakai tautan pembayaran kalau pembeli yang memilih metodenya. Kalau aplikasimu sudah tahu metodenya (misalnya pembeli memilih BCA di halaman checkout tokomu), buat pembayaran langsung: nomor VA, kode QRIS, atau kode bayar gerai langsung ada di respons.

POST/v1/payments

Buat pembayaran dengan metode pilihanmu. Kirim Idempotency-Key supaya aman diulang.

KolomTipeKeterangan
amountwajibintegerNominal rupiah, 10.000–1.000.000.000.
methodwajibstringKode metode dari GET /v1/methods, misalnya va_bca atau qris.
referencestringNomor pesanan di sistemmu, maksimal 64 karakter. Ikut di webhook dan bisa dicari lewat GET /v1/payments?reference=.
descriptionstringKeterangan yang tampil di halaman pembayaran dan Jurnal. Bawaan Pembayaran.
pocketstringKode kantong; kosong berarti kantong utama.
customerobjectname, email, phone pembeli. Nomor HP dipakai untuk e-wallet seperti OVO.
expiresInintegerBatas bayar dalam detik, 300–604.800. Bawaan mengikuti metode.
returnUrlstringURL tokomu untuk kembali setelah lunas.
metadataobjectData bebas milikmu (maksimal 4 KB), dikembalikan apa adanya di respons dan webhook.
TerminalShell
curl -X POST https://api.udahbayar.id/v1/payments \
  -H "Authorization: Bearer $UDAHBAYAR_SECRET_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 175000,
    "method": "va_bca",
    "reference": "ORDER-1001",
    "description": "Order #1001",
    "customer": { "name": "Rina", "email": "[email protected]" },
    "returnUrl": "https://tokomu.com/terima-kasih",
    "metadata": { "cart": "c-77" }
  }'
Respons 201JSON
{
  "reference": "UBP-SSSATMKUKZ3E5697",
  "status": "open",
  "amount": 175000,
  "fee": 4000,
  "net": 171000,
  "method": { "id": "2", "type": "va", "name": "BCA Virtual Account" },
  "instructions": { "kind": "va", "bank": "BCA", "vaNumber": "3935821503594675" },
  "hostedUrl": "https://pay.udahbayar.id/ef6ad7fc-…/pay/UBP-SSSATMKUKZ3E5697",
  "returnUrl": "https://tokomu.com/terima-kasih",
  "merchantReference": "ORDER-1001",
  "description": "Order #1001",
  "metadata": { "cart": "c-77" },
  "payer": { "name": "Rina", "email": "[email protected]", "phone": null },
  "link": null,
  "mode": "test",
  "expiresAt": "2026-11-21T07:10:56.000Z",
  "paidAt": null,
  "createdAt": "2026-11-20T07:10:56.000Z"
}

Tampilkan instructions di aplikasimu, atau arahkan pembeli ke hostedUrl: halaman kami yang menampilkan instruksi dan memperbarui status sendiri. Isi instructions mengikuti jenis metode: vaNumber untuk Virtual Account, qrString untuk QRIS, paymentCode untuk gerai ritel.

GET/v1/payments?status=paid&reference=ORDER-1001&page=1

Daftar pembayaran di mode key, terbaru dulu. Filter opsional: status (open, paid, expired, cancelled) dan reference (nomor pesananmu). perPage maksimal 100.

GET/v1/payments/{reference}

Satu pembayaran dengan bentuk yang sama seperti di atas: status, nominal, biaya, dana bersih, metode, dan data pembeli. Pembayaran dari tautan juga muncul di sini, dengan link berisi tautannya.

Batas bayar bawaan mengikuti metode: QRIS dan e-wallet 15 menit, kartu dan paylater 30 menit, Virtual Account dan gerai ritel 24 jam. Setelah itu status menjadi expired dan tidak dikenai biaya. Pembayaran live baru bisa dibuat setelah akunmu terverifikasi; sebelum itu API membalas 409 live_unavailable.

Halaman pembayaran

Setiap tautan punya halaman pembayaran di pay.udahbayar.id/{code}. Pembeli memilih metode, mendapat instruksi (nomor VA, kode QRIS, atau kode bayar gerai), dan halamannya memperbarui status sendiri sampai lunas. Kamu tidak perlu membuat halaman pembayaran sendiri.

Pembayaran langsung punya halamannya sendiri di hostedUrl. Kalau tautan atau pembayaran punya returnUrl, halaman lunas menampilkan tombol kembali ke tokomu dan mengarahkan pembeli ke sana setelah 5 detik (pembeli bisa memilih tetap di halaman).

Tautan dari akun yang belum terverifikasi hanya bisa dibayar di sandbox. Pembayaran live terbuka setelah akunmu diverifikasi.

Webhook

Atur URL dan event di Developer → Webhook. Kami mengirim POST JSON untuk payment.paid, payment.expired, payment_link.paid, dan payment_link.cancelled. Tombol Kirim event uji di dashboard mengirim webhook.test untuk mengecek endpoint-mu.

BodyJSON
{
  "id": "evt_ae2cedd2fb092c66d44a0f41",
  "type": "payment.paid",
  "createdAt": "2026-11-20T07:11:02.000Z",
  "data": {
    "reference": "UBP-SSSATMKUKZ3E5697",
    "status": "paid",
    "amount": 175000,
    "fee": 4000,
    "net": 171000,
    "method": { "type": "va", "name": "BCA Virtual Account" },
    "merchantReference": "ORDER-1001",
    "metadata": { "cart": "c-77" },
    "mode": "test",
    "paidAt": "2026-11-20T07:11:02.000Z"
  }
}
  • Header: X-Udahbayar-Event (jenis event), X-Udahbayar-Delivery (sama dengan id), dan X-Udahbayar-Signature.
  • Balas dengan status 2xx secepatnya. Selain itu kami mengirim ulang otomatis setelah 1 menit, 5 menit, 15 menit, 1 jam, 3 jam, 6 jam, 12 jam, dan 24 jam. Setiap percobaan tercatat dan bisa dikirim ulang manual dari dashboard.
  • id sama di setiap percobaan: simpan yang sudah diproses dan abaikan duplikat. Urutan kedatangan tidak dijamin, jadi berpeganglah pada data.status.

Tanda tangannya berbentuk t=<waktu>,v1=<hex>, dengan v1 = HMAC-SHA256 dari <t>.<body mentah> memakai signing secret kamu. Selalu periksa sebelum memproses:

Node.jsJavaScript
import crypto from "node:crypto";

export function isFromUdahBayar(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""));
}
PHPPHP
function is_from_udah_bayar(string $rawBody, string $header, string $secret): bool {
    parse_str(str_replace(',', '&', $header), $parts);
    $expected = hash_hmac('sha256', $parts['t'] . '.' . $rawBody, $secret);
    return hash_equals($expected, $parts['v1'] ?? '');
}

Error

Semua error memakai bentuk yang sama. Kirim Accept-Language: id untuk pesan berbahasa Indonesia.

Respons 400JSON
{
  "error": {
    "code": "validation",
    "message": "Periksa kolom yang ditandai.",
    "fields": { "amount": ["Jumlah minimal Rp 10.000."] }
  }
}
KodeHTTPArtinya
invalid_api_key401Secret key tidak ada, salah, atau sudah dicabut.
validation400Ada kolom yang tidak valid; detailnya di fields.
not_found404Tautan atau pembayaran tidak ditemukan di mode key ini.
link_unavailable409Tautan sudah lunas, kedaluwarsa, atau dibatalkan.
live_unavailable409Pembayaran live belum bisa dibuat; akun belum terverifikasi.
method_unavailable409Metode pembayaran tidak tersedia untuk akun ini.
idempotency_key_reused422Idempotency-Key sudah dipakai untuk permintaan lain.
idempotency_in_progress409Permintaan dengan key yang sama masih diproses.
rate_limited429Terlalu banyak permintaan; coba lagi sebentar.