Bina integrasi dengan API Bayarcash

Dengan Bayarcash API, laman web atau app anda boleh mencipta bayaran, menyemak transaksi dan mengurus mandate FPX Direct Debit. Guna API v3 untuk semua integrasi baru. Rujukan penuh ada di api-reference.bayarcash.com.

Pilih versi API

Bayarcash ada dua versi API:

Versi	Status	Bila perlu digunakan
v3	Terkini	Untuk setiap integrasi baru. Ciri baru (DuitNow QR pada page anda sendiri, idempotency, pengesahan identiti pembayar, carian transaksi) hanya ada dalam v3.
v2	Deprecated	Hanya jika sistem anda sudah menggunakannya. v2 tidak menerima ciri baru. Rancang untuk berpindah ke v3.

Sandbox & production

Bina dan uji integrasi anda dalam sandbox dahulu. Dalam sandbox, tiada transaksi sebenar yang berlaku. Kedua-dua environment ini berasingan: setiap satu ada merchant dashboard, akaun dan keys sendiri.

Environment	Base URL API	Merchant dashboard
Sandbox	https://api.console.bayarcash-sandbox.com/v3	console.bayarcash-sandbox.com
Production	https://api.console.bayar.cash/v3	console.bayar.cash

Apabila anda go live, tukar base URL dan guna keys production anda. Keys dari satu environment tidak akan berfungsi dalam environment yang lain.

Apa yang anda perlukan

Setiap integrasi v3 menggunakan item ini dari merchant dashboard anda:

Item	Fungsinya
Personal Access Token (PAT)	Membuktikan identiti anda pada setiap request API.
Portal key	Menentukan portal mana yang menerima bayaran.
API Secret Key	Menandatangani request dan mengesahkan callback dengan checksum. Key ini tidak pernah dihantar dengan sendirinya.

Simpan token dan secret key di server anda sahaja. Jangan letak keys itu dalam aplikasi mudah alih, JavaScript dalam browser atau repository awam.

Tambah token pada setiap request

Hantar Personal Access Token anda sebagai bearer token dalam header Authorization bagi setiap request:

Authorization: Bearer <your Personal Access Token>
Accept: application/json

Contohnya, untuk menyemak sama ada token anda berfungsi, senaraikan portal anda dalam sandbox:

curl https://api.console.bayarcash-sandbox.com/v3/portals \
  -H "Authorization: Bearer $BAYARCASH_PAT" \
  -H "Accept: application/json"

Aliran bayaran melalui API

Biasanya, bayaran melalui API berjalan begini:

1. Server anda mencipta payment intent dengan portal key, nombor pesanan, amaun, nama dan e-mel pelanggan, serta callback_url dan return_url anda.
2. Bayarcash membalas dengan url. Redirect pelanggan anda ke URL itu untuk membayar.
3. Apabila bayaran mencapai status akhir, Bayarcash menghantar callback ke callback_url anda, terus dari server ke server. Sahkan checksum-nya dan kemas kini pesanan itu.
4. Bayarcash menghantar pelanggan kembali ke return_url anda supaya pelanggan dapat melihat keputusannya.

Hanya callback yang boleh anda percayai untuk status bayaran. Lihat Sahkan callback dan checksum.

Tips

• Guna SDK jika ada SDK untuk bahasa pengaturcaraan anda. SDK menguruskan base URL, bearer token, checksum dan pengesahan callback untuk anda. Lihat Pilih SDK Bayarcash.
• Hantar header Idempotency-Key apabila anda mencipta payment intent. Jika request timeout, anda boleh menghantar request itu semula dengan key yang sama. Bayarcash tidak akan mencipta bayaran kedua. Key ini tamat tempoh selepas 24 jam.
• Simpan setiap ID transaksi dan semak ID itu sebelum anda bertindak atas callback. Callback yang sama boleh sampai lebih daripada sekali. Semakan ini memastikan anda tidak memproses pesanan yang sama dua kali.

Isu-isu biasa

Kenapa token saya berfungsi dalam production tetapi tidak sah dalam sandbox?

Sandbox dan production mengeluarkan token yang berasingan. Personal Access Token production tidak berfungsi dengan API sandbox, dan token sandbox tidak berfungsi dalam production. Dapatkan setiap token dari merchant dashboard environment itu.

Boleh saya terus guna API v2?

Tidak. API v2 sudah deprecated dan tidak akan menerima ciri baru. Guna v3 untuk setiap integrasi baru. Kebanyakan SDK masih bermula pada v2 secara default, jadi tukar SDK itu kepada v3 (lihat Pilih SDK Bayarcash).

Di mana saya boleh dapatkan senarai penuh endpoint dan field?

Dalam rujukan API di api-reference.bayarcash.com. Panduan dalam Bayarcash Help ini menerangkan konsepnya. Rujukan API pula menyenaraikan setiap endpoint, field dan response.

Artikel berkaitan

• Pilih SDK Bayarcash
• Sahkan callback dan checksum
• Terima bayaran dengan PHP SDK
• Cari API keys & portal key anda