Payment Create

Endpoint ini digunakan untuk membuat invoice pembayaran baru. Setelah Anda mendapatkan account_id yang aktif dari endpoint Payment Account, Anda dapat melanjutkan ke langkah ini untuk menerbitkan invoice kepada customer.

Konsep Penting:

• Nominal Unik: Sistem akan secara otomatis menambahkan angka acak antara 1 hingga 999 pada nominal transaksi. Customer WAJIB mentransfer sebesar nilai payment_total (gabungan payment_amount + kode unik), bukan payment_amount saja. Hal ini sangat penting agar transfer dari customer dapat dideteksi dan diverifikasi secara otomatis oleh sistem.
• Idempotency Key: Parameter payment_code berfungsi sebagai idempotency key. Jika Anda mengirimkan request dengan kode invoice yang sama berulang kali, sistem akan menolaknya dengan status error 409 Conflict guna mencegah terjadinya duplikasi pembuatan invoice.

Contoh Tagihan: Total yang harus dibayar: Rp 50.123 (Rincian: Tagihan utama Rp 50.000 + Kode unik Rp 123)

---

Request

Endpoint

Method	URL
POST	https://api.bayar.digital/gateway/payments

Parameter

Tidak ada parameter yang dibutuhkan pada URL.

Header

Header	Wajib	Deskripsi
X-Api-Key	Ya	API Key merchant Anda
Content-Type	Ya	Harus diisi dengan application/json

Body

Field	Tipe	Wajib	Deskripsi
account_id	uuid	Ya	ID akun tujuan yang didapat dari GET /gateway/accounts
payment_code	string	Ya	Kode referensi unik dari sistem Anda (Idempotency key)
payment_amount	int64	Ya	Nominal pokok invoice sebelum ditambahkan kode unik
payment_expired_at	string	Ya	Batas waktu pembayaran (Format ISO 8601, harus di waktu mendatang)
customer_name	string	Ya	Nama lengkap customer
customer_email	string	Tidak	Alamat email customer (maksimal 255 karakter). Wajib diisi minimal salah satu antara email atau telepon
customer_phone	string	Tidak	Nomor telepon customer (maksimal 50 karakter). Wajib diisi minimal salah satu antara email atau telepon
payment_webhook_url	string	Tidak	URL endpoint webhook spesifik untuk invoice ini
payment_return_url	string	Tidak	URL redirect setelah customer menyelesaikan pembayaran
customer_orders	array	Tidak	Daftar detail item pesanan

Detail customer_orders (Order Item):

Jika array customer_orders diisi, pastikan total akumulasi dari seluruh field subtotal sama persis dengan payment_amount.

Field	Tipe	Wajib	Deskripsi
sku	string	Ya	SKU (Stock Keeping Unit) produk
name	string	Ya	Nama produk
price	int64	Ya	Harga satuan produk
quantity	int	Ya	Jumlah item yang dibeli
subtotal	int64	Ya	Akan di-override oleh sistem menggunakan rumus price × quantity
product_url	string	Tidak	Tautan menuju halaman detail produk
image_url	string	Tidak	Tautan gambar produk

Contoh

curl -X POST https://api.bayar.digital/gateway/payments \
  -H "X-Api-Key: pk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "payment_code": "INV-2026-0001",
    "payment_amount": 50000,
    "payment_expired_at": "2026-10-11T12:00:00Z",
    "customer_name": "Budi Santoso",
    "customer_email": "budi@example.com",
    "customer_phone": "081234567890",
    "customer_orders": [
      {
        "sku": "SKU001",
        "name": "Produk A",
        "price": 50000,
        "quantity": 1,
        "subtotal": 50000
      }
    ]
  }'

Response

Sukses

Field	Tipe	Deskripsi
payment_id	uuid	ID unik invoice yang dihasilkan sistem
payment_code	string	Kode invoice referensi dari sistem Anda
payment_amount	int64	Nominal tagihan asli (tanpa tambahan kode unik)
payment_unique	int64	Nominal kode unik yang di-generate (1-999)
payment_total	int64	Total tagihan akhir yang harus dibayar (amount + unique)
payment_status	string	Status pembayaran awal, umumnya PENDING
payment_expired_at	datetime	Batas akhir waktu pembayaran invoice
payment_updated_at	datetime	Waktu pembaruan data terakhir
payment_webhook_url	string / null	URL webhook khusus untuk invoice ini
payment_checkout_url	string	Tautan publik menuju halaman checkout pembayaran
payment_return_url	string / null	URL redirect setelah pembayaran sukses
customer_name	string	Nama customer
customer_email	string / null	Alamat email customer
customer_phone	string / null	Nomor telepon customer
customer_orders	array	Daftar detail pesanan (order items)
account_id	uuid	ID akun pembayaran tujuan
account_number	string	Nomor rekening bank tujuan
account_name	string	Nama pemilik rekening bank
channel_id	uuid	ID channel perbankan di sistem
channel_name	string	Nama institusi bank terkait
channel_type	string	Tipe pembayaran (TRANSFER atau QRIS)
channel_instructions	array	Panduan atau instruksi pembayaran untuk customer
is_manual_match	bool	Indikator apakah pembayaran dicocokkan secara manual
manual_matched_mutation_id	uuid / null	ID mutasi apabila pencocokan dilakukan secara manual

Detail customer_orders (Order Item):

Field	Tipe	Deskripsi
sku	string	SKU (Stock Keeping Unit) produk
name	string	Nama produk
price	int64	Harga satuan produk
quantity	int	Jumlah item yang dibeli
subtotal	int64	Total harga (price × quantity)
product_url	string / null	Tautan menuju halaman detail produk
image_url	string / null	Tautan gambar produk

201 Created

{
  "success": true,
  "message": "created",
  "data": {
    "payment_id": "660e8400-e29b-41d4-a716-446655440010",
    "payment_code": "INV-2026-0001",
    "payment_amount": 50000,
    "payment_unique": 123,
    "payment_total": 50123,
    "payment_status": "PENDING",
    "payment_expired_at": "2026-10-11T12:00:00Z",
    "payment_updated_at": "2026-06-11T10:00:00Z",
    "payment_webhook_url": "https://yourserver.com/webhooks/bayar",
    "payment_checkout_url": "https://bayar.digital/checkout/660e8400-e29b-41d4-a716-446655440010",
    "payment_return_url": "https://yourserver.com/orders/INV-2026-0001",
    "customer_name": "Budi Santoso",
    "customer_email": "budi@example.com",
    "customer_phone": "081234567890",
    "customer_orders": [
      {
        "sku": "SKU001",
        "name": "Produk A",
        "price": 50000,
        "quantity": 1,
        "subtotal": 50000,
        "product_url": "https://yourserver.com/products/produk-a",
        "image_url": "https://yourserver.com/images/produk-a.jpg"
      }
    ],
    "account_id": "550e8400-e29b-41d4-a716-446655440000",
    "account_number": "1234567890",
    "account_name": "PT Merchant Contoh",
    "channel_id": "660e8400-e29b-41d4-a716-446655440001",
    "channel_name": "Bank Central Asia",
    "channel_type": "TRANSFER",
    "channel_instructions": [],
    "is_manual_match": false,
    "manual_matched_mutation_id": null
  }
}

Gagal

Code	Status	Keterangan
invalid request body	400	Struktur atau format JSON tidak valid
validation_error	400	Satu atau lebih field tidak valid (Detail lengkap dapat dilihat pada atribut errors)
invalid_expired_at	400	Format waktu pada payment_expired_at salah
account_not_owned	403	account_id yang digunakan tidak terdaftar atau bukan milik Anda
no_active_quota	403	Kuota hari akun Anda sudah habis
tenant_api_key_required	403	API Key tidak disertakan atau tidak valid
unique_amount_conflict	409	Sistem gagal men-generate nominal unik secara aman, silakan coba kirim request kembali
payment_code_conflict	409	payment_code sudah pernah digunakan sebelumnya (Idempotency conflict)
internal_error	500	Terjadi kesalahan internal pada server, silakan coba beberapa saat lagi

Validation Error (400)

{
  "success": false,
  "code": "validation_error",
  "message": "validation error",
  "errors": {
    "customer_name": "customer name is required"
  }
}

Conflict (409) - Payment Code

{
  "success": false,
  "code": "payment_code_conflict",
  "message": "payment code conflict"
}

Conflict (409) - Unique Amount

{
  "success": false,
  "code": "unique_amount_conflict",
  "message": "unique amount conflict"
}