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:
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.
Authorization: Bearer ub_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxBatas 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.
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.
{
"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.
| Kolom | Tipe | Keterangan |
|---|---|---|
titlewajib | string | Judul yang tampil di halaman pembayaran, maksimal 255 karakter. |
amountwajib | integer | Nominal dalam rupiah, minimal 10000. |
pocket | string | Kode kantong, 12 karakter, dari Pengaturan → Kantong. Tidak peka huruf besar/kecil. Kosong atau tidak dikirim: kantong utama. |
multiple | boolean | true untuk tautan multi-pakai. Bawaan false (sekali bayar). |
maxUsage | integer | Kuota pembayaran untuk tautan multi-pakai, 1–10.000. Wajib bila multiple bernilai true. |
expiresAt | string | Waktu ISO 8601 setelah tautan tidak bisa dibayar lagi, harus di masa depan. |
payerFields | object | Data pembeli yang diminta di halaman pembayaran: name, email, phone (boolean). |
returnUrl | string | URL http(s) tokomu. Setelah lunas, pembeli dibawa kembali ke sini (otomatis setelah 5 detik). |
{
"title": "Workshop Latte Art",
"amount": 175000,
"pocket": "PK7Q2M9XW4AB",
"multiple": true,
"maxUsage": 25,
"payerFields": { "name": true, "email": true, "phone": false }
}{
"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.
| Kolom | Tipe | Keterangan |
|---|---|---|
amountwajib | integer | Nominal rupiah, 10.000–1.000.000.000. |
methodwajib | string | Kode metode dari GET /v1/methods, misalnya va_bca atau qris. |
reference | string | Nomor pesanan di sistemmu, maksimal 64 karakter. Ikut di webhook dan bisa dicari lewat GET /v1/payments?reference=. |
description | string | Keterangan yang tampil di halaman pembayaran dan Jurnal. Bawaan Pembayaran. |
pocket | string | Kode kantong; kosong berarti kantong utama. |
customer | object | name, email, phone pembeli. Nomor HP dipakai untuk e-wallet seperti OVO. |
expiresIn | integer | Batas bayar dalam detik, 300–604.800. Bawaan mengikuti metode. |
returnUrl | string | URL tokomu untuk kembali setelah lunas. |
metadata | object | Data bebas milikmu (maksimal 4 KB), dikembalikan apa adanya di respons dan webhook. |
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" }
}'{
"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.
{
"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 denganid), danX-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.
idsama di setiap percobaan: simpan yang sudah diproses dan abaikan duplikat. Urutan kedatangan tidak dijamin, jadi berpeganglah padadata.status.
Tanda tangannya berbentuk t=<waktu>,v1=<hex>, dengan v1 = HMAC-SHA256 dari <t>.<body mentah> memakai signing secret kamu. Selalu periksa sebelum memproses:
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 ?? ""));
}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.
{
"error": {
"code": "validation",
"message": "Periksa kolom yang ditandai.",
"fields": { "amount": ["Jumlah minimal Rp 10.000."] }
}
}| Kode | HTTP | Artinya |
|---|---|---|
invalid_api_key | 401 | Secret key tidak ada, salah, atau sudah dicabut. |
validation | 400 | Ada kolom yang tidak valid; detailnya di fields. |
not_found | 404 | Tautan atau pembayaran tidak ditemukan di mode key ini. |
link_unavailable | 409 | Tautan sudah lunas, kedaluwarsa, atau dibatalkan. |
live_unavailable | 409 | Pembayaran live belum bisa dibuat; akun belum terverifikasi. |
method_unavailable | 409 | Metode pembayaran tidak tersedia untuk akun ini. |
idempotency_key_reused | 422 | Idempotency-Key sudah dipakai untuk permintaan lain. |
idempotency_in_progress | 409 | Permintaan dengan key yang sama masih diproses. |
rate_limited | 429 | Terlalu banyak permintaan; coba lagi sebentar. |