# Bina integrasi dengan API Bayarcash

> Mula dengan Bayarcash API v3, base URL untuk sandbox dan production, dan cara menghantar Personal Access Token anda dengan setiap request.
>
> Source: https://docs.bayarcash.com/ms/developers/

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](https://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](https://console.bayarcash-sandbox.com) |
| Production | `https://api.console.bayar.cash/v3` | [console.bayar.cash](https://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:

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

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

```bash
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](/ms/callbacks-and-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](/ms/sdks/).
- **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 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 (/ms/sdks/)).

### Di mana saya boleh dapatkan senarai penuh endpoint dan field?

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