Build on the Bayarcash API

The Bayarcash API lets your own website or app create payments, check transactions and manage FPX Direct Debit mandates. Use API v3 for everything new. The full reference is at api-reference.bayarcash.com.

Which API version to use

Bayarcash has two API versions:

Version	Status	When to use it
v3	Current	Every new integration. New features (DuitNow QR on your own page, idempotency, payer identity verification, transaction search) are v3 only.
v2	Deprecated	Only if you already run on it. It gets no new features. Plan a move to v3.

Sandbox and production

Build and test in the sandbox first. No real money moves there. The two environments are separate: each has its own merchant dashboard, its own account and its own keys.

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

When you go live, change the base URL and swap in your production keys. Keys from one environment never work in the other.

What you need

Every v3 integration uses these from your merchant dashboard:

Item	What it does
Personal Access Token (PAT)	Proves who you are on every API request.
Portal key	Says which of your portals receives the payment.
API Secret Key	Signs requests and verifies callbacks with a checksum. Never sent on its own.

Keep the token and the secret key on your server only. Never put them in a mobile app, browser JavaScript or a public repository.

Authenticate every request

Send your Personal Access Token as a bearer token in the Authorization header of every request:

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

For example, to check that your token works, list your portals in the sandbox:

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

How a payment works

A typical payment through the API goes like this:

1. Your server creates a payment intent with the portal key, order number, amount, payer name and email, and your callback_url and return_url.
2. Bayarcash answers with a url. Redirect your customer there to pay.
3. When the payment reaches a final state, Bayarcash sends a callback to your callback_url, server to server. Verify its checksum and update the order.
4. Bayarcash sends the customer back to your return_url to show them the result.

The callback is the one to trust. See Verify callbacks and checksums.

Tips

• Use an SDK if there is one for your language. It handles the base URL, the bearer token, checksums and callback verification for you. See Choose a Bayarcash SDK.
• Send an Idempotency-Key header when you create a payment intent. If a request times out, you can send it again with the same key without creating a second payment. Keys expire after 24 hours.
• Store each transaction ID and check it before you act on a callback. Callbacks can arrive more than once, and this stops you fulfilling the same order twice.

Common issues

My token works in production but the sandbox says it is not valid. Why?

Sandbox and production issue separate tokens. A production Personal Access Token does not work against the sandbox API, and a sandbox token does not work in production. Get each token from its own merchant dashboard.

Should I still use API v2?

No. API v2 is deprecated and gets no new features. Use v3 for every new integration. Most SDKs still default to v2, so switch them to v3 (see Choose a Bayarcash SDK).

Where is the full list of endpoints and fields?

In the API reference at api-reference.bayarcash.com. This help centre explains the ideas; the reference has every endpoint, field and response.

Related articles

• Choose a Bayarcash SDK
• Verify callbacks and checksums
• Accept payments with the PHP SDK
• Find your API keys and portal key