Lewati ke konten utama

Pendahuluan

Buat sesi pembayaran dan lacak transaksi melalui gateway yang dikonfigurasi dalam proyek Anda.

Informasi lebih lanjut tentang pembayaran di panel admin OneEntry: https://doc.oneentry.cloud/docs/category/payments

🎯 Apa yang dilakukan modul ini?​

Modul Payments memungkinkan Anda untuk membuat sesi pembayaran dan melacak transaksi untuk toko Anda. Anda mengonfigurasi akun pembayaran di panel admin (Payments > Accounts) — Stripe atau kustom — dan modul ini membuat sesi pembayaran untuk sebuah pesanan, mengembalikan tautan checkout gateway, dan memungkinkan Anda membaca riwayat dan status sesi.

SDK mengambil akun pembayaran dan membuat sesi pembayaran; akun dan status dikonfigurasi di panel admin.

🚀 Memulai dengan Cepat​

Inisialisasi modul dari defineOneEntry:


const { Payments } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

Buat sesi pembayaran untuk sebuah pesanan dan arahkan pelanggan ke gateway (autentikasi diperlukan):

// Create a Stripe Checkout session for order #179.
const session = await Payments.createSession(179, "session");

console.log(session.id, session.status, session.paymentUrl);

// Send the customer to the gateway checkout page.
window.location.href = session.paymentUrl;

✨ Konsep Kunci​

Apa itu Sesi Pembayaran?​

Sebuah Sesi Pembayaran (ISessionEntity) adalah catatan yang berisi:

  • type — 'session' atau 'intent'
  • status — string status pembayaran bebas (misalnya, "waiting", "completed")
  • paymentAccountId — akun yang dikonfigurasi digunakan
  • orderId — pesanan terkait
  • paymentUrl — tautan checkout gateway (atau null)
  • createdDate / updatedDate — cap waktu

Jenis Sesi​

TipeDeskripsi
sessionMembuat halaman Stripe Checkout dengan tautan pembayaran redirect
intentMembuat niat pembayaran untuk pemrosesan pembayaran langsung/kustom

Jenis Akun​

TipeKapan DigunakanKonfigurasi Diperlukan
StripeMenghubungkan sistem pembayaran StripeAkun Stripe, URL
CustomSistem pembayaran alternatif atau pembayaran tunaiKonfigurasi kustom

Status Pembayaran​

status dari sebuah sesi adalah string bebas yang ditetapkan dari hasil gateway, bukan enum tetap. Nilai umum:

StatusArti
waitingSesi dibuat, menunggu pembayaran
completedPembayaran dikonfirmasi oleh gateway

Anda tidak dapat membuat atau mengubah status pembayaran di panel admin. Namun, Anda dapat memetakan status pembayaran ke status penyimpanan pesanan sehingga status pesanan diperbarui secara otomatis ketika status pembayaran berubah.

Siklus Hidup Pembayaran​

1. Configure a payment account in the admin panel (Stripe or custom)
   ↓
2. Customer places an order (Orders module)
   ↓
3. Create a payment session  →  Payments.createSession(orderId, type)
   ↓
4. Redirect the customer to session.paymentUrl
   ↓
5. Customer completes payment at the gateway
   ↓
6. Session status reflects the gateway result (e.g. "waiting" → "completed")
   ↓
7. Mapped order status is updated automatically

📋 Apa yang Perlu Anda Ketahui​

Akun pembayaran dibuat di panel admin​

Anda tidak dapat membuat akun pembayaran melalui SDK — buat dan edit mereka di panel admin OneEntry (Payments > Accounts), dengan memberikan Nama, Tipe (Stripe atau Kustom), dan Token. Untuk akun Stripe, Anda juga mengonfigurasi Success URL, Cancel URL, dan Session lifetime. SDK digunakan untuk mengambil akun dan membuat sesi.

Sinkronisasi Status​

Status pembayaran dipetakan ke status penyimpanan pesanan di panel admin (Payments > Statuses → pilih penyimpanan pesanan → peta status → simpan). Ini memungkinkan pembaruan status pesanan otomatis ketika status pembayaran berubah.

Jangan pernah menyimpan data kartu mentah​

Jangan pernah menyimpan nomor kartu kredit, CVV, atau tanggal kedaluwarsa lengkap. Pembayaran ditangani oleh gateway (Stripe), yang menjaga Anda agar tidak terlibat dalam penyimpanan data kartu; OneEntry tidak pernah menyimpan detail kartu mentah.

Pengembalian dana ada di modul Orders​

Modul Payments tidak memiliki metode pengembalian dana. Pengembalian dana ditangani oleh modul Orders melalui createRefundRequest(), cancelRefundRequest(), dan getRefunds().

📊 Tabel Referensi Cepat​

MetodeDeskripsiKasus Penggunaan
getAccounts() 🔐Mendapatkan semua akun pembayaranDaftar akun pembayaran yang dikonfigurasi
getAccountById() 🔐Mendapatkan akun pembayaran berdasarkan IDMengambil detail akun tertentu
createSession() 🔐Membuat sesi pembayaranMenghasilkan tautan pembayaran untuk pesanan
getSessions() 🔐Mendapatkan semua sesi pembayaran (terpaginated)Melihat riwayat sesi pembayaran
getSessionById() 🔐Mendapatkan sesi pembayaran berdasarkan IDMemeriksa status sesi tertentu
getSessionByOrderId() 🔐Mendapatkan sesi pembayaran berdasarkan ID pesananMenemukan pembayaran untuk pesanan tertentu

🔐 = Memerlukan otorisasi

❓ Pertanyaan Umum (FAQ)​

Bagaimana cara mengatur pembayaran Stripe?​

Buat akun pembayaran di panel admin dengan tipe "Stripe", lalu konfigurasikan Success URL, Cancel URL, dan Session lifetime. Gunakan createSession() dengan tipe "session" untuk menghasilkan tautan yang mengarahkan pelanggan ke Stripe Checkout.

Apa perbedaan antara jenis pembayaran sesi dan niat?​

Sebuah sesi membuat halaman Stripe Checkout dengan URL redirect, ideal untuk halaman pembayaran yang dihosting. Sebuah niat membuat niat pembayaran untuk integrasi formulir pembayaran kustom langsung di aplikasi Anda.

Dapatkah saya mendukung beberapa akun pembayaran?​

Ya. Buat beberapa akun pembayaran (Stripe atau kustom) di panel admin. Setiap pesanan dapat menggunakan akun yang berbeda melalui paymentAccountIdentifier-nya.

Bagaimana cara menghubungkan status pembayaran ke status pesanan?​

Di panel admin, pergi ke Payments > Statuses, pilih penyimpanan pesanan Anda, dan peta status pembayaran ke status pesanan. Ini memungkinkan sinkronisasi otomatis.

Bagaimana cara mengeluarkan pengembalian dana?​

Pengembalian dana bukan bagian dari modul Payments. Gunakan modul Orders: createRefundRequest() untuk meminta pengembalian dana, cancelRefundRequest() untuk membatalkan permintaan, dan getRefunds() untuk mendaftar mereka.

🎓 Praktik Terbaik​

  • Autentikasi terlebih dahulu — setiap metode Payments memerlukan pengguna yang terotorisasi (lihat AuthProvider).
  • Arahkan ke paymentUrl setelah membuat sesi, dan tangani URL kembali dari gateway di aplikasi Anda.
  • Baca status dari sesi, bukan dari klien — periksa status sesi (atau getSessionByOrderId()) untuk mengonfirmasi pembayaran.
  • Peta status pembayaran ke status pesanan sehingga keadaan pesanan tetap sinkron secara otomatis.
  • Uji dengan kunci uji Stripe sebelum masuk ke produksi.

🔗 Dokumentasi Terkait​