Checkout dan Payment

Checkout Storefront API memakai konsep checkout yang sama dengan storefront bawaan Scalev. Storefront browser dapat mengambil opsi pengiriman, menghitung summary checkout, membuat guest order, membaca public order, dan membuat atau memakai ulang instruksi payment tanpa backend merchant. Storefront API dirancang agar storefront Anda dapat merender payment page sendiri. Gunakan response public order dan payment untuk menampilkan instruksi pembayaran langsung di UI Anda. payment_url tetap dikembalikan sebagai fallback hosted untuk storefront yang belum mengimplementasikan renderer per metode atau untuk flow provider yang memang harus membuka hosted payment page. Gunakan hanya metode payment yang dikembalikan oleh GET /v3/stores/{store_id}/public/payment-methods. Checkout storefront tidak mengembalikan no_payment, dan endpoint checkout akan menolaknya jika dikirim langsung.

Alur guest checkout

Baca atau buat guest cart dan simpan X-Scalev-Guest-Token.
Minta lokasi pengiriman dan postal code jika cart berisi produk fisik.
Panggil POST /public/checkout/shipping-options.
Biarkan buyer memilih opsi pengiriman.
Panggil POST /public/checkout/summary.
Panggil POST /public/guest-checkout dengan detail buyer dan field checkout terpilih.
Baca order dengan GET /public/orders/{secret_slug}.
Panggil POST /public/orders/{secret_slug}/payment dan render data payment yang dikembalikan di payment page Anda sendiri.

Shipping options

POST /v3/stores/{store_id}/public/checkout/shipping-options

Headers:

X-Scalev-Storefront-Api-Key: sfpk_...
X-Scalev-Guest-Token: <guest-token>

Jika X-Scalev-Guest-Token menemukan guest cart yang tidak kosong, Scalev memakai cart tersebut. Jika tidak, kirim direct variant items:

{
  "items": [
    {
      "variant_id": 494535,
      "quantity": 1
    }
  ],
  "destination": {
    "location_id": 9089,
    "postal_code": "10510"
  },
  "payment_method": "bank_transfer"
}

Direct items[] mendukung variant. Checkout bundle didukung melalui guest cart. Response:

{
  "data": [
    {
      "courier_service_id": 123,
      "courier_code": "jne",
      "service_code": "REG",
      "name": "Regular",
      "cost": 12000,
      "etd": "2-3",
      "is_cod": false,
      "warehouse_unique_id": "warehouse_...",
      "courier_aggregator_code": null
    }
  ],
  "is_paginated": false
}

Cart digital-only mengembalikan:

{
  "data": [],
  "is_paginated": false
}

Checkout summary

POST /v3/stores/{store_id}/public/checkout/summary

Kirim opsi pengiriman terpilih. Scalev menghitung ulang shipping cost di server dan mengabaikan shipping_cost dari client.

{
  "destination": {
    "location_id": 9089,
    "postal_code": "10510"
  },
  "courier_service_id": 123,
  "warehouse_unique_id": "warehouse_...",
  "courier_aggregator_code": null,
  "payment_method": "bank_transfer"
}

Field response sama dengan summary checkout yang sudah ada:

{
  "product_price": "125000.00",
  "shipping_cost": "12000",
  "other_income": "0",
  "other_income_name": "Biaya Lainnya",
  "gross_revenue": "137000.00"
}

Cart digital-only mengembalikan shipping_cost: "0".

Cek kode diskon

POST /v3/stores/{store_id}/public/discount-codes/check

Gunakan body JSON untuk memvalidasi kode diskon sebelum checkout:

{
  "code": "SAVE10",
  "items": [
    {
      "variant_id": 494535,
      "quantity": 1
    }
  ],
  "destination": {
    "location_id": 9089,
    "postal_code": "10510"
  },
  "courier_service_id": 123,
  "warehouse_unique_id": "warehouse_abc",
  "courier_aggregator_code": null,
  "payment_method": "bank_transfer"
}

Jika X-Scalev-Guest-Token mengarah ke cart yang tidak kosong, API memakai cart itu sebagai sumber item. Jika tidak, kirim items[]. Kode yang tidak ditemukan atau tidak eligible tetap mengembalikan response validasi normal dengan is_eligible: false dan discount_code: null.

Guest checkout

Buat order dengan:

POST /v3/stores/{store_id}/public/guest-checkout

Gunakan field checkout terpilih yang sama:

{
  "items": [
    {
      "variant_id": 494535,
      "quantity": 1
    }
  ],
  "customer_name": "Customer Name",
  "customer_email": "customer@example.com",
  "customer_phone": "08123456789",
  "shipping_address": "Jl. Example 1",
  "shipping_location_id": 9089,
  "shipping_subdistrict": "Cempaka Putih",
  "shipping_postal_code": "10510",
  "courier_service_id": 123,
  "warehouse_unique_id": "warehouse_...",
  "courier_aggregator_code": null,
  "payment_method": "bank_transfer"
}

Endpoint checkout memakai courier service, warehouse, destinasi, metode pembayaran, dan item cart terpilih untuk menghitung ulang shipping cost di server. Jangan menjadikan shipping_cost dari client sebagai sumber kebenaran. Jika berhasil, response berisi data order yang dibuat, termasuk secret_slug, public_order_url, payment_url, status, total, item, detail pengiriman, dan field payment. Gunakan secret_slug untuk membaca atau mengubah order. Gunakan payment_url hanya sebagai hosted fallback jika storefront Anda tidak merender instruksi payment sendiri.

Instruksi payment

Setelah checkout, panggil:

POST /v3/stores/{store_id}/public/orders/{secret_slug}/payment

Endpoint ini idempotent. Jika instruksi payment sudah ada, response mengembalikan order lagi dengan data payment buyer-facing dan URL yang sudah tersedia. Gunakan urutan preferensi berikut di browser storefront:

Render instruksi per metode dari payment_method, sub_payment_method, epayment_provider, dan pg_payment_info.
Untuk metode hosted oleh provider, buka URL provider dari pg_payment_info saat provider memang membutuhkan redirect.
Gunakan payment_url hanya sebagai fallback ke payment page hosted Scalev jika storefront Anda belum mendukung metode atau response provider tersebut.
Poll public order saat metode payment memerlukan data gateway yang mungkin belum langsung tersedia.

Rendering per metode

Success page bawaan Scalev adalah reference implementation untuk rendering per metode. Storefront API storefront dapat menggantikan page tersebut dengan menerapkan mapping pg_payment_info yang sama di UI sendiri. Success page bawaan terlebih dulu membuat data tampilan sederhana dari pg_payment_info Xendit/default yang dipakai saat ini. Data tampilan ini bukan response API baru. Bagian ini hanya referensi jika storefront Anda ingin punya satu renderer payment, bukan branching langsung ke field payload provider:

{
  "qrString": "000201010212...",
  "qrImageUrl": "https://api.qrserver.com/v1/create-qr-code/?...",
  "vaNumber": "88081234567890",
  "vaAccountHolder": "Customer Name",
  "invoiceUrl": "https://provider.example/pay/...",
  "renderUrlAs": "button"
}

Field sumber aslinya berasal dari order dan response payment. Untuk payload Xendit/default saat ini, petakan dengan aturan berikut:

Display value	Field sumber
`qrString`	`pg_payment_info.qr_string` atau `pg_payment_info.payment_method.qr_code.channel_properties.qr_string`
`vaNumber`	`pg_payment_info.payment_method.virtual_account.channel_properties.virtual_account_number` atau `pg_payment_info.payment_method.over_the_counter.channel_properties.payment_code`
`vaAccountHolder`	`pg_payment_info.payment_method.virtual_account.channel_properties.customer_name` atau `pg_payment_info.payment_method.over_the_counter.channel_properties.customer_name`
`invoiceUrl`	`pg_payment_info.invoice_url` atau `pg_payment_info.redirect_url`
`qrImageUrl`	Buat QR image dari `qrString` di frontend saat Anda membutuhkan gambar QR yang bisa diunduh.

Untuk gopay, dana, linkaja, shopeepay, dan ovo, pilih action URL dari pg_payment_info.actions: mobile memprioritaskan url_type WEB atau DEEPLINK; desktop memprioritaskan MOBILE atau DEEPLINK. Set renderUrlAs menjadi button untuk invoice, card, dan semua tampilan mobile. Untuk tampilan desktop lainnya, render URL sebagai QR code. bank_transfer: Tampilkan total order, rekening manual bank transfer, expiry countdown jika aktif, dan link konfirmasi pembayaran ke /o/{secret_slug}?showPaymentConfirmation=true. Hosted page mengambil rekening dari payment_accounts store dengan method bank_transfer dan metode yang masih aktif. pg_payment_info bisa berupa {}. cod: Tampilkan body sukses COD dan jangan tampilkan countdown payment. Payment creation dapat mengembalikan pg_payment_info kosong. Virtual account (va): Render bank/channel virtual account dari sub_payment_method, vaNumber, dan vaAccountHolder jika tersedia. Tampilkan tombol copy dan link tutorial pembayaran. Bank code yang dikenal mencakup BRI, MANDIRI, PERMATA, BNI, BCA, MAYBANK, CIMB, BNC, DANAMON, BSI, AG, BJB, SAHABAT_SAMPOERNA, ARTAJASA, BMI, dan BTN. QRIS (qris): Render QR code dari qrString. Sediakan juga aksi download QR dari qrImageUrl dan instruksi mobile untuk menyimpan atau screenshot QR image sebelum membayar di aplikasi QRIS. Jika QR gagal dibuat atau qrString tidak ada, tampilkan retry action yang memanggil public payment endpoint lagi. E-wallet kecuali OVO (gopay, dana, linkaja, shopeepay): Gunakan invoiceUrl dari provider actions. Di mobile, buka sebagai button/deep link. Di desktop, render invoiceUrl sebagai QR code saat renderUrlAs bernilai qr_code; selain itu buka sebagai button. Jika URL tidak bisa dipetakan, arahkan buyer kembali ke public order page. OVO (ovo): Tampilkan instruksi untuk mengecek aplikasi OVO yang terhubung dengan nomor telepon buyer. Komponen success bawaan tidak merender OVO melalui komponen QR e-wallet yang sama. Card (card) dan invoice/hosted payment (invoice): Buka invoiceUrl hasil mapping sebagai button/redirect. Hosted success page otomatis redirect ketika invoiceUrl tersedia dan renderUrlAs bernilai button. Alfamart dan Indomaret: Render vaNumber sebagai No Pembayaran, tampilkan vaAccountHolder jika tersedia, dan sediakan aksi copy.

Polling dan cek status

Untuk metode e-payment (gopay, card, invoice, va, qris, ovo, dana, shopeepay, linkaja, alfamart, dan indomaret), success page bawaan menunggu pg_payment_info muncul dengan refetch public order sampai 15 kali dengan jeda 1,5 detik. Untuk order pending unpaid dengan card, invoice, shopeepay, dana, qris, linkaja, gopay, bank_transfer, indomaret, dan alfamart, success page bawaan kemudian me-refresh public order setiap 5 detik sambil menunggu konfirmasi payment. Untuk va, bank_transfer, qris, alfamart, dan indomaret, success page bawaan juga menampilkan aksi manual “cek status pembayaran”.

Authenticated customer checkout

Endpoint customer checkout berada di:

/v3/stores/{store_id}/customers/me/checkout/*

Endpoint ini memakai Authorization: Bearer <customer_access_token>, bukan Storefront API key. Address, metode payment, shipping option, dan summary memakai field persiapan checkout yang sama dengan guest checkout. Confirm mengembalikan response public order yang sama dengan guest checkout dan public order read, sehingga semua response checkout completion memakai field order yang sama. Summary customer checkout memakai courier service, warehouse, destinasi, metode payment, dan item customer cart terpilih untuk menghitung ulang shipping cost di server. shipping_cost dari client hanya nilai compatibility dan bukan jumlah authoritative.

Storefront API

Webhooks

Contoh penggunaan

Landing Pages

Alur guest checkout

Shipping options

Checkout summary

Cek kode diskon

Guest checkout

Instruksi payment

Rendering per metode

Polling dan cek status

Authenticated customer checkout

Storefront API

Webhooks

Contoh penggunaan

Landing Pages

Documentation Index

​Alur guest checkout

​Shipping options

​Checkout summary

​Cek kode diskon

​Guest checkout

​Instruksi payment

​Rendering per metode

​Polling dan cek status

​Authenticated customer checkout

Alur guest checkout

Shipping options

Checkout summary

Cek kode diskon

Guest checkout

Instruksi payment

Rendering per metode

Polling dan cek status

Authenticated customer checkout