Quickstart

Di akhir panduan ini, Anda memiliki satu pembayaran TEST, URL checkout, dan hasil simulasi yang bisa diperiksa melalui API. Langkah ini belum memperbarui pesanan Anda secara otomatis; kita menambahkan bagian itu pada panduan webhook.

Sebelum mulai

• Buat atau pilih workspace dan project di aplikasi Valcentra.
• Pada project tersebut, buka API Keys dan buat key untuk environment TEST. Jika Anda tidak memiliki akses, minta anggota workspace dengan izin yang sesuai.
• Simpan key di environment variable atau secret manager backend. Jangan memasukkannya ke kode frontend, Git, atau log.
• Siapkan cURL, backend TypeScript dengan fetch, atau PHP dengan ekstensi cURL.

Contoh memakai VALCENTRA_API_URL untuk origin API, tanpa /v1 di akhir, dan TEST_API_KEY untuk key Anda. Isi keduanya di environment backend dari konfigurasi layanan yang Anda gunakan. Origin API berbeda dari alamat dashboard dan checkout. Anda dapat melihat alamat server di API Reference ↗.

1. Buat pembayaran dari backend

Kirim POST /v1/payments untuk pesanan order-book-1001 senilai Rp125.000. Gunakan Idempotency-Key yang sama jika Anda harus mengulang operasi yang sama setelah koneksi terputus.

Pilih contoh cURL, TypeScript, atau PHP. Ketiganya mengirim body yang sama. Contoh ini dijalankan di server atau terminal lokal, bukan di browser pelanggan.

curl --include --request POST "$VALCENTRA_API_URL/v1/payments" \
  --header "Authorization: Bearer $TEST_API_KEY" \
  --header "Idempotency-Key: order-book-1001-create" \
  --header "Content-Type: application/json" \
  --data '{"amount":125000,"currency":"IDR","merchant_reference":"order-book-1001","channel":"qris"}'

Backend Anda harus mengambil jumlah dari data pesanan tepercaya, bukan menerima harga dari browser begitu saja.

2. Baca respons dan simpan identitas pembayaran

Request yang berhasil mengembalikan HTTP 201 dan objek pembayaran langsung, tanpa pembungkus data. Bentuknya seperti berikut:

{
	"id": "pay_example_1001",
	"amount": "125000",
	"currency": "IDR",
	"merchant_reference": "order-book-1001",
	"status": "awaiting_method",
	"livemode": false,
	"channel": "qris",
	"created_at": "2026-10-01T09:00:00.000Z",
	"updated_at": "2026-10-01T09:00:00.000Z",
	"expires_at": "2026-10-01T09:30:00.000Z",
	"paid_at": null,
	"checkout_url": "https://pay.example.test/c/checkout_example_1001"
}

• Simpan id sebagai ID pembayaran Valcentra, terpisah dari ID pesanan Anda.
• Simpan checkout_url dari respons; jangan membangun URL sendiri.
• awaiting_method berarti pembayaran dibuat, belum lunas, meskipun request menyertakan channel.
• livemode: false menandakan pembayaran TEST.
• amount pada respons berupa string untuk menjaga presisi. Waktu memakai UTC; expires_at bergantung pada konfigurasi project, bukan selalu 30 menit seperti contoh.

3. Periksa halaman checkout

Buka checkout_url yang Anda terima dan cocokkan pesanan serta jumlahnya. Dalam aplikasi Anda, backend dapat memberikan URL ini ke frontend untuk membuka halaman checkout. API key tetap di backend.

Untuk mengikuti simulasi API pada langkah berikutnya, cukup periksa halaman, jangan memulai metode pembayaran dari checkout terlebih dahulu. Simulator membuat attempt uji sendiri. Jika pembayaran sudah diproses melalui checkout, gunakan pembayaran baru untuk simulasi API.

Pada integrasi pelanggan yang sesungguhnya, lanjutkan melalui panduan checkout.

4. Simulasikan pembayaran berhasil

Isi PAYMENT_ID di environment terminal dengan id dari respons Anda, lalu jalankan:

curl --include --request POST \
  "$VALCENTRA_API_URL/v1/test/payments/$PAYMENT_ID/simulate" \
  --header "Authorization: Bearer $TEST_API_KEY" \
  --header "Idempotency-Key: order-book-1001-simulate-paid" \
  --header "Content-Type: application/json" \
  --data '{"scenario":"paid"}'

Hasil sukses memakai HTTP 200 dengan objek pembayaran. Untuk skenario paid, periksa status: "paid", livemode: false, dan paid_at yang terisi.

5. Ambil status terbaru

Gunakan ID dan API key project yang sama:

curl --include "$VALCENTRA_API_URL/v1/payments/$PAYMENT_ID" \
  --header "Authorization: Bearer $TEST_API_KEY"

Respons HTTP 200 berisi status terbaru. Endpoint ini tidak mengembalikan checkout_url; itulah alasan Anda menyimpannya dari respons create payment.

Quickstart berhasil jika: pembayaran dapat diambil kembali, merchant_reference sesuai pesanan, livemode bernilai false, dan status berubah menjadi paid setelah simulasi. Ini membuktikan alur API TEST, bukan penerimaan webhook atau transaksi produksi.

Jika belum berhasil

Langkah berikutnya: tambahkan webhook agar backend mengetahui perubahan status tanpa bergantung pada pelanggan membuka halaman Anda.