# Bayarcash API > Bayarcash is a Malaysian payment gateway. This is the reference for API v3: FPX, Direct Debit, DuitNow QR, cards, e-wallets and buy now, pay later. - Interactive reference: https://api-reference.bayarcash.com/ - OpenAPI document: https://api-reference.bayarcash.com/openapi/v3.yaml (also https://api-reference.bayarcash.com/openapi/v3.json) - Production base URL: https://api.console.bayar.cash - Authentication: a Personal Access Token as a bearer token (`Authorization: Bearer `). - Help centre for merchants: https://docs.bayarcash.com/ (its own index: https://docs.bayarcash.com/llms.txt) ## Introduction Bayarcash is a payment gateway in Malaysia. This reference is for **API v3**, the current version. Use v3 for all new integrations. API v2 is old, and it gets no new features. ## Environments | Environment | API base URL | Console | |---|---|---| | **Production** | `https://api.console.bayar.cash/v3` | [console.bayar.cash](https://console.bayar.cash) | | **Sandbox** | `https://api.console.bayarcash-sandbox.com/v3` | [console.bayarcash-sandbox.com](https://console.bayarcash-sandbox.com) | ## Authentication Send a Personal Access Token as a bearer token in each request. To create a token, go to your account settings in the merchant dashboard. ``` Authorization: Bearer ``` The sandbox and production have different tokens. A production token does not work in the sandbox. ## Guides ## Getting Started Each v3 request needs 3 items: a **Personal Access Token**, a **portal key** and a **payment channel**. ## 1. Personal Access Token Create a token in your account settings in the merchant dashboard. Send it as a bearer token in each request. The sandbox and production have different tokens. ## 2. Portal key A portal is a shop or a place where you collect payments. Create a portal in the merchant dashboard or with [Merchant Portal](#tag/merchant-portal). Then use its `portal_key`. ## 3. Payment channel Each channel has a number. You can use only the channels that are switched on for your account. FPX is on by default. Before you show banks to a payer, use [Banks List](#tag/banks-list) to get the banks for the channel. ## Next steps 1. Create a [Payment Intent](#tag/payment-intent). 2. Send the payer to the `url` in the response. 3. When the payment is complete, Bayarcash sends the [Transaction Callback](#tag/transaction/webhook/POST/transactioncallback) to your server. Sign your requests with a [checksum](#tag/checksum). The checksum is optional. It shows that the request came from you and that nobody changed it. ## Payment Channels Send the ID of the channel as `payment_channel`. You can use only the channels that are switched on for your portal. FPX Personal Banking (B2C) is on by default. To switch on a channel, ask the Bayarcash team. | ID | Channel | Use it for | |---|---|---| | | **Online banking** | | | 1 | FPX Personal Banking (B2C) | Online banking from Malaysian banks. On by default. | | 23 | FPX Business Banking (B2B) | Company (business) online banking. | | 4 | FPX Line of Credit (CCA) | Paying with a bank credit facility. See [FPX Line of Credit](https://docs.bayarcash.com/fpx-line-of-credit/). | | 5 | DuitNow Online Banking/Wallets (DOBW) | Real-time payment from a bank app or e-wallet. | | | **Recurring** | | | 3 | Direct Debit | Recurring collection after an e-mandate. Use the [Direct Debit](#tag/direct-debit) endpoints. | | | **Cards** | | | 12 | Cards (Visa, Mastercard, MyDebit) | Card payments. Card recurring also uses this channel. See [Card Recurring Overview](#tag/card-recurring-overview). | | | **DuitNow QR** | | | 6 | DuitNow QR | Customers scan a QR code with their banking app or e-wallet. | | | **Cross-border QR** | | | 9 | QRIS Indonesia (online banking) | Customers from Indonesia who pay with a bank app. See [Cross-border channels](https://docs.bayarcash.com/cross-border-channels/). | | 10 | QRIS Indonesia (e-wallet) | Customers from Indonesia who pay with an e-wallet. | | 11 | NETS | Customers from Singapore. | | 13 | Alipay | Customers from China who pay with Alipay. | | 14 | WeChat Pay | Customers from China who pay with WeChat Pay. | | 15 | PromptPay | Customers from Thailand. | | | **E-wallets** | | | 16 | Touch 'n Go eWallet | Touch 'n Go eWallet. | | 17 | Boost Wallet | Boost e-wallet. | | 18 | GrabPay | Grab e-wallet. | | 21 | ShopeePay | ShopeePay e-wallet. | | | **Buy now, pay later** | | | 7 | SPayLater | Buy now pay later with SPayLater. | | 8 | Boost PayFlex | Buy now pay later with Boost PayFlex. | | 19 | PayLater by Grab | Buy now pay later with Grab. | Direct Debit (3) uses the [Direct Debit](#tag/direct-debit) endpoints, not a payment intent. The payer uses FPX online banking only to enrol, change or end a mandate. The deductions are a separate process. For each channel in more detail, see [Payment channels](https://docs.bayarcash.com/payment-channels/) in the help centre. ## Checksum ## Make a request checksum For secure requests, make a checksum with your API Secret Key and add it to the request. Bayarcash uses the checksum to make sure that nobody changed the request and that it came from you. Your API Secret Key is in the merchant dashboard. > [!NOTE] > The checksum is optional. We recommend it, because it makes your integration more secure. ## Request Checksum **1. Payment Intent Request** ``` "1", "order_number" => "ORD-0060", "amount" => "60.00", "payer_name" => "MOHD ALI", "payer_email" => "m.ali@gmail.com" ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $checksum = hash_hmac('sha256', $payloadString, $secretKey); // Generate HMAC SHA256 checksum ``` **2. Direct Debit Enrolment** ``` "ORD-0027", "amount" => "10", "payer_name" => "MOHD ALI", "payer_email" => "m.ali@gmail.com", "payer_telephone_number" => "0199009001", "payer_id_type" => "1", "payer_id" => "880101010123", "frequency_mode" => "MT", "application_reason" => "Enrollment of ORD-0027", ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $checksum = hash_hmac('sha256', $payloadString, $secretKey); // Generate HMAC SHA256 checksum ``` **3. Direct Debit Maintenance** ``` "ORD-0027", "amount" => "10", "payer_email" => "m.ali@gmail.com", "payer_telephone_number" => "0199009001", "frequency_mode" => "MT", "application_reason" => "Enrollment of ORD-0027", ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $checksum = hash_hmac('sha256', $payloadString, $secretKey); // Generate HMAC SHA256 checksum ``` ## Check the callback data **1. Pre-Transaction Callback** ``` $callbackData['record_type'], "exchange_reference_number" => $callbackData['exchange_reference_number'], "order_number" => $callbackData['order_number'], ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $validResponse= hash_hmac('sha256', $payloadString, $secretKey) === $callbackChecksum; // Validate checksum ``` **2. Transaction Callback** ``` $callbackData['record_type'], "transaction_id" => $callbackData['transaction_id'], "exchange_reference_number" => $callbackData['exchange_reference_number'], "exchange_transaction_id" => $callbackData['exchange_transaction_id'], "order_number" => $callbackData['order_number'], "currency" => $callbackData['currency'], "amount" => $callbackData['amount'], "payer_name" => $callbackData['payer_name'], "payer_email" => $callbackData['payer_email'], "payer_bank_name" => $callbackData['payer_bank_name'], "status" => $callbackData['status'], "status_description" => $callbackData['status_description'], "datetime" => $callbackData['datetime'], ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $validResponse= hash_hmac('sha256', $payloadString, $secretKey) === $callbackChecksum; // Validate checksum ``` **3. Direct Debit Authorization Callback** ``` $callbackData['record_type'], "exchange_reference_number" => $callbackData['exchange_reference_number'], "order_number" => $callbackData['order_number'], ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $validResponse= hash_hmac('sha256', $payloadString, $secretKey) === $callbackChecksum; // Validate checksum ``` **4. Direct Debit Bank Approval Callback** ``` $callbackData['record_type'], "approval_date" => $callbackData['approval_date'], "approval_status" => $callbackData['approval_status'], "mandate_id" => $callbackData['mandate_id'], "mandate_reference_number" => $callbackData['mandate_reference_number'], "order_number" => $callbackData['order_number'], "payer_bank_code_hashed" => $callbackData['payer_bank_code_hashed'], "payer_bank_code" => $callbackData['payer_bank_code'], "payer_bank_account_no" => $callbackData['payer_bank_account_no'], "application_type" => $callbackData['application_type'], ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $validResponse= hash_hmac('sha256', $payloadString, $secretKey) === $callbackChecksum; // Validate checksum ``` **5. Direct Debit Transaction Callback** ``` $callbackData['record_type'], "batch_number" => $callbackData['batch_number'], "mandate_id" => $callbackData['mandate_id'], "mandate_reference_number" => $callbackData['mandate_reference_number'], "transaction_id" => $callbackData['transaction_id'], "datetime" => $callbackData['datetime'], "reference_number" => $callbackData['reference_number'], "amount" => $callbackData['amount'], "status" => $callbackData['status'], "status_description" => $callbackData['status_description'], "cycle" => $callbackData['cycle'], ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Concatenate values with '|' $validResponse= hash_hmac('sha256', $payloadString, $secretKey) === $callbackChecksum; // Validate checksum ``` ## Notes - Keep the API Secret Key in a safe place. Do not put it in code that runs in the browser. - Always check the checksum in the callback data. This shows that the data came from Bayarcash and that nobody changed it. - `ksort` sorts the payload data by key. The checksum is correct only when the order is the same. - `implode` joins the sorted values with `|`. The result is the string for the checksum. - `hash_hmac` makes the checksum with SHA256 and your API Secret Key. - **Trim each value** before you make the checksum, so that the string has no extra spaces. ## Idempotency ## Idempotent requests With an idempotency key, you can safely send a request again. Bayarcash does not do the same operation 2 times. Use it when a request stops before you get a response. To send an idempotent request, add an `Idempotency-Key` header with a unique key. We recommend a UUID v4. The key applies to your merchant account and portal, so different portals can use the same key. Bayarcash keeps the body of the first successful (2xx) response for each key. If you send the same key with the same parameters again, you get the same body and the same status code (for example `201` for a create). The status code does not show that the response is a copy. To find a copy, compare the `id`. Bayarcash does not keep a response that is not successful, so you can send the request again with the same key. Keys expire after **24 hours**. The [Card Recurring](#tag/card-recurring-overview) endpoints do not use an `Idempotency-Key`. They ignore the header. Each create has your own `reference`, plan `code` or customer email instead. Bayarcash refuses a second create with the same value (`422`). > [!IMPORTANT] > If you send the same key with different parameters, the API returns an error. This prevents mistakes. **Example request with an idempotency key:** ```bash curl https://api.console.bayar.cash/v3/payment-intents \ -H "Authorization: Bearer " \ -H "Idempotency-Key: 8f14e45f-ceea-367f-a27f-c790e02b3045" \ -H "Content-Type: application/json" \ -d '{"portal_key":"xxx","payment_channel":[1],"order_number":"ORD001","amount":100.00,"payer_name":"MOHD ALI","payer_email":"m.ali@gmail.com"}' ``` **Error responses:** | When | Status | Error message | |----------|--------|-------------| | The same key with different parameters | 422 | Idempotency key already used with different request parameters | | A request with the same key is not complete yet | 409 | A request with this idempotency key is currently being processed | | The key is longer than 255 characters | 422 | Idempotency key must not exceed 255 characters | This error body is not the `{"error": {"code", "message"}}` body of the Card Recurring endpoints: ```json { "error": { "idempotency_key": "A request with this idempotency key is currently being processed." } } ``` ## Methods that a path does not accept If you send a method that a path does not accept, the API returns `405 Method Not Allowed`. An example is `PATCH /v3/plans` or `GET /v3/payments`. The API does this check before the authentication. Thus a request with no token also gets `405`, not `401`. ```json { "code": 405, "message": "Method PATCH not allowed." } ``` ## Payer Identity Verification ## Payer Identity Verification FPX can verify the identity of the payer. It checks that the buyer and the payer are the same person or company, and it checks the source of the money. It uses the bank account number of the payer, the NRIC, passport number or business registration number of the payer, or both. ### Requirements - `payment_channel` **must be 1 channel only**: FPX (`1`) or FPX B2B (`23`). A payment intent with more than 1 channel cannot use identity verification. - `payment_channel` is **required** when `verify_identity` is `true`. - Set `verify_identity` to `true`. - `fpx_eaccount_number` (string, maximum 40 characters): **required**. The bank account number of the payer. - `fpx_ebuyer_id` (string, maximum 40 characters): **required**. The NRIC, passport number or business registration number of the payer. ### Example request ```json { "payment_channel": 1, "portal_key": "your-portal-key", "order_number": "ORD001", "amount": 100.00, "payer_name": "MOHD ALI", "payer_email": "m.ali@gmail.com", "verify_identity": true, "fpx_eaccount_number": "1234567890", "fpx_ebuyer_id": "900101145678" } ``` ### Verification result After the payment, the transaction callback includes these fields. The response of `GET /v3/transactions/{id}` does not include them. - `payer_identity_verified` (boolean | null): `true` if the identity is correct, `false` if it is not correct, `null` if the transaction has no verification. - `fpx_extra_info` (object | null): the details of the verification. Only a transaction with verification has it. It contains: - `fpx_extra_info.account_type` (string): `"CASA"` (current or savings account), `"LCA"` (loan or credit account), or `"Undetermined"`. - `fpx_extra_info.account_number_verified` (boolean | null): `true` if the account number is correct, `false` if it is not correct, `null` if FPX cannot tell. - `fpx_extra_info.buyer_id_verified` (boolean | null): `true` if the buyer ID is correct, `false` if it is not correct, `null` if FPX cannot tell. ### Example callback ```json { "record_type": "transaction", "transaction_id": "trx_abc123", "exchange_reference_number": "1-726-210-822-807492", "order_number": "ORD001", "currency": "MYR", "amount": 100.00, "payer_name": "MOHD ALI", "payer_email": "m.ali@gmail.com", "status": 3, "status_description": "Approved", "payer_identity_verified": true, "fpx_extra_info": { "account_type": "CASA", "account_number_verified": true, "buyer_id_verified": true }, "checksum": "..." } ``` ## Card Recurring Overview With card recurring, Bayarcash charges the card of a customer more than 1 time. There are 3 types: - **Subscription:** a fixed price at a fixed interval, from a plan. The charges continue until you or the customer stops them. - **Installment:** a total amount in a fixed number of charges (2 to 60). An installment has no plan. - **On-demand charge:** you charge a saved card at the time that you select. ## Before you start - Bayarcash must switch on card recurring for your account. Until then, each card recurring endpoint returns `403` `recurring_not_enabled`. To switch it on, ask the Bayarcash team. - The card processor examines each merchant before the switch-on. Prepare the items in the checklist for your checkout, below. - The portal must have the Cards channel (`12`). A recurring charge is a card payment. - Only the merchant can create a customer, a plan, a subscription or an installment. An agent, admin or staff user gets `401`. An enterprise or agent user can read the records of a child merchant, but cannot change them. ## Enrol a customer in a subscription 1. Create a [plan](#tag/plans/create-plan) with your own `code`, the price and the interval. 2. [Create a subscription](#tag/subscriptions/create-subscription) for the plan. Send your own `reference`, a `start_date`, a `callback_url` and a `return_url`. 3. Send the customer to the `redirect_url` in the response. This is the card page of the provider. It is available for 20 minutes. 4. The customer completes the card page. The provider takes the first charge at that time. 5. Bayarcash sends the [Recurring Charge Callback](#tag/charges/webhook/POST/recurringchargecallback) to your `callback_url`. A successful first charge means that the subscription is `active`. 6. The customer goes to your `return_url`. Verify the checksum. Then get the subscription, and use its status. An installment uses the same steps with [Create an installment](#tag/installments/create-installment). It has no plan. Each enrolment uses the card page, also for a customer with a saved card. A saved card is only for on-demand charges. ## Charge a saved card 1. [Save a card](#tag/customers/save-card) for the customer. The customer completes the card page of the provider. 2. [Charge the saved card](#tag/charges/charge-saved-card) when you must collect money. The response is the result of the charge. There is no customer page and no `return_url`. ## Your reference A create of a subscription, an installment or an on-demand charge has your own `reference`. There is no `Idempotency-Key`. - Use letters, digits, `_` and `-`, a maximum of 36 characters. - A reference is unique for each merchant and each type, for all time. You cannot use it again, also after the record failed or ended. - The comparison ignores the case. `INV-1` and `inv-1` are the same reference. - If you send a reference again, the API returns `422` `reference_already_used`. It does not return the first record. Each charge gives the reference back as `order_number`. An on-demand charge gives its own reference. A scheduled charge gives the reference of its subscription or installment. ## When you do not get a clear response Do not send the same create again. Read the record. | Response | What occurred | What to do | |---|---|---| | `202` on a subscription or an installment | The payment exchange did not answer. Bayarcash recorded the create as `pending`. | Get the record with its `id`. It usually changes in 6 minutes, a maximum of approximately 10 minutes. | | No response, or a `5xx` | You do not know. | Get the list with `?reference=`. If the list is empty, send the request again. If the list has the record, read it. | | `422` `upstream_rejected`, `409`, `429` or `502` `upstream_auth` | The exchange refused the create. Nothing was created. | Correct the request. Send it with a new reference. After a `429`, wait for the time in `Retry-After`. | | `202` on an on-demand charge | **The card can have a charge.** | Wait for the callback. Or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. | After a `202` on an on-demand charge, an empty search result is not proof that there is no charge. Bayarcash first checks the charge 15 minutes after it records it, then each 5 minutes. This usually takes approximately 20 minutes, and it can take longer. Charge again with a new reference only after a failed charge callback. Or charge again when the search is still empty a long time after that. ## Status of a subscription or an installment | Status | Meaning | |---|---| | `pending` | The customer did not complete the card page yet. Or the create got a `202`. | | `active` | The charges occur on the schedule. | | `paused` | The charges stopped for a time. `paused_reason` gives the cause. | | `canceled` | You or the provider stopped it, before or after the first charge. | | `expired` | Nobody completed the card page. The provider canceled it approximately 30 minutes after the create. There was no charge. | | `terminated` | You or the provider ended it. | | `failed` | The card page declined the card, or the exchange refused the create. Create a new one with a new reference. | | `completed` | Installments only. Bayarcash collected all the charges. | The API uses the American spelling `canceled`. It refuses `cancelled`. `paused_reason` has 3 values: - `payment_failed`: the provider paused it after a scheduled charge failed. Correct the card problem before you continue the charges. - `merchant`: you paused it. - `provider`: the provider paused it, and Bayarcash did not see the failed charge yet. The value changes to `payment_failed` when Bayarcash sees it. ## Change the status Send `PATCH` with the new `status`. Bayarcash first reads the current status from the provider. These changes are permitted: | From | To | |---|---| | `pending` | `canceled` | | `active` | `paused`, `terminated` or `canceled` | | `paused` | `active`, `terminated` or `canceled` | You cannot change a subscription or an installment that ended. All other changes get `422` `invalid_transition`. You cannot change the card of an agreement. Terminate the agreement, and enrol the customer again. ## Notifications The [Recurring Charge Callback](#tag/charges/webhook/POST/recurringchargecallback) is the only card recurring webhook. There is no webhook for a change of the subscription or installment status. Obey these rules: - **The first charge callback tells you that the enrolment is complete.** A successful first charge means that the agreement is `active`. - **The order is not fixed.** The first charge callback can come before or after the customer goes to your `return_url`. Use `subscription_id` or `installment_id` to connect them. - **A declined first charge comes as a failed charge callback.** The agreement then has the status `failed`. To try again, create a new agreement. - **A change with no charge does not send a callback.** Get the record to see it. Examples: `expired`, a pause or a cancellation that you made, and a pause that the provider made. The failed scheduled charge before the pause of the provider sends a failed charge callback. ## Recurring Return URL After the card page of an enrolment, the customer goes to the `return_url` of the agreement. The query string has the status of the agreement and a checksum. An on-demand charge has no return. The query string has these fields. Each field is always there. A field with no value is an empty string. - `recurring_type`: `subscription` or `installment`. - `status`: the status of the agreement, as a word, for example `active`. This is not the number in `status` of the charge callback. - `customer_id`, `subscription_id`, `installment_id`. - `transaction_id`, `exchange_reference_number`, `exchange_transaction_id`, `currency`, `amount`, `transaction_status`, `transaction_status_description`: the first charge. These fields are empty until Bayarcash records the charge. Then `currency` is the currency of the agreement. - `datetime`: ISO 8601, with an offset. - `checksum`. **Verify the checksum. Then get the agreement. Then do the next step.** The return only tells you that the customer came back. The status of the agreement and the charge callback are the record. If the customer closes the card page, the customer does not come to the `return_url`. The checksum signs the 12 fields before `datetime`: ```php $_GET['recurring_type'] ?? '', "status" => $_GET['status'] ?? '', "customer_id" => $_GET['customer_id'] ?? '', "subscription_id" => $_GET['subscription_id'] ?? '', "installment_id" => $_GET['installment_id'] ?? '', "transaction_id" => $_GET['transaction_id'] ?? '', "exchange_reference_number" => $_GET['exchange_reference_number'] ?? '', "exchange_transaction_id" => $_GET['exchange_transaction_id'] ?? '', "currency" => $_GET['currency'] ?? '', "amount" => $_GET['amount'] ?? '', "transaction_status" => $_GET['transaction_status'] ?? '', "transaction_status_description" => $_GET['transaction_status_description'] ?? '', ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Join the values with '|' $validResponse = hash_equals(hash_hmac('sha256', $payloadString, $secretKey), $checksum); ``` ## Checklist for your checkout Bayarcash does not show its own page for an enrolment. Your checkout shows the consent. Then the customer goes directly to the card page of the provider (`redirect_url`). The card processor asks for these items before the switch-on: - Your recurring terms and conditions, and your policies. - Your checkout page with the recurring consent. For example, a required checkbox next to the amount and the interval: *"I authorise {merchant} to charge my card {amount} {every month} starting {date} until I cancel"*. - A sample authorization form, or a description of how the customer gives consent. - A clear cancellation process for the customer. For example: *"Cancel at any time from your account page, or send an email to {support e-mail}. We stop the charges from the next cycle."* To cancel, send `PATCH` with the `status` `canceled`. ## Dates and times - Transaction records (`GET /v3/transactions`, the charge lists and `GET /v3/payments/{paymentId}`) and the `datetime` of the callback use Kuala Lumpur time as `Y-m-d H:i:s`, **with no offset**. - Customers, plans, subscriptions, installments and `next_payment_date` use ISO 8601 **with an offset**, for example `2027-01-01T10:00:00+08:00`. ## Errors The card recurring endpoints use this error body. `code` does not change, so use it in your code. `message` is for persons. `fields` is only in a validation error. ```json { "error": { "code": "validation_error", "message": "The email field is required.", "fields": { "email": ["The email field is required."] } } } ``` A `401` uses the body `{"code": 401, "message": "This action is unauthorized."}`. A validation error of [Save a card](#tag/customers/save-card) uses the body of `POST /v3/payment-intents`. Bayarcash keeps a log of each call to the payment exchange for your requests, with the request and the answer. The exchange keeps a log of each call to the provider. These logs are the audit record of card recurring. ## SDKs & Plugins Official libraries, and integrations that need no code. Each SDK supports API v2 and v3. ## SDKs | Language | Package | Install | |---|---|---| | PHP | [`bayarcash/php-sdk`](https://packagist.org/packages/bayarcash/php-sdk) | `composer require bayarcash/php-sdk` | | Node.js / TypeScript | [`bayarcash`](https://www.npmjs.com/package/bayarcash) | `npm install bayarcash` | | Python | [`bayarcash`](https://pypi.org/project/bayarcash/) | `pip install bayarcash` | | Go | [`go-sdk`](https://pkg.go.dev/github.com/bayarcash/go-sdk) | `go get github.com/bayarcash/go-sdk` | | Ruby | [`bayarcash`](https://rubygems.org/gems/bayarcash) | `gem install bayarcash` | | Rust | [`bayarcash`](https://crates.io/crates/bayarcash) | `cargo add bayarcash` | | Dart / Flutter | [`bayarcash`](https://pub.dev/packages/bayarcash) | `dart pub add bayarcash` | | C# / .NET | [`Bayarcash`](https://www.nuget.org/packages/Bayarcash) | `dotnet add package Bayarcash` | The PHP SDK uses v2 by default. To use this API, call `setApiVersion('v3')`. ## Demos - [bayarcash-demo.com](https://bayarcash-demo.com/): try the payment flow of Bayarcash. - [bayarcash/php-demo](https://github.com/bayarcash/php-demo): a demo page in plain PHP that uses the API. ## Framework integrations | Framework | Package | Install | |---|---|---| | Laravel | [`bayarcash/laravel`](https://packagist.org/packages/bayarcash/laravel) | `composer require bayarcash/laravel` | | Django | [`django-bayarcash`](https://pypi.org/project/django-bayarcash/) | `pip install django-bayarcash` | ## Plugins Plugins are available for WooCommerce, GiveWP, Gravity Forms, Fluent Forms, FluentCart, Easy Digital Downloads, Paymattic, OpenCart, PrestaShop, WHMCS and HostBill. To get them, go to [plugin.bayarcash.com](https://plugin.bayarcash.com). The WordPress plugins are also on [WordPress.org](https://profiles.wordpress.org/bayarcash/). ## Workflow automation Bayarcash nodes and BCL nodes for [n8n](https://github.com/bayarcash/n8n-nodes-bayarcash). ## Changelog Changes to the Bayarcash API v3, and corrections to this reference. The newest changes are first. ## 10 Nov 2026 ### New: card recurring Charge the card of a customer more than 1 time: subscriptions, installments and on-demand charges. Bayarcash must switch on card recurring for your account. See [Card Recurring Overview](#tag/card-recurring-overview). - **Customers:** `POST /v3/customers`, `GET /v3/customers`, `GET /v3/customers/{customerId}`, `POST /v3/customers/{customerId}/save-card`. - **Plans:** `POST /v3/plans`, `GET /v3/plans`, `GET /v3/plans/{planId}`, `PATCH /v3/plans/{planId}`. - **Subscriptions:** `POST /v3/subscriptions`, `GET /v3/subscriptions`, `GET /v3/subscriptions/{subscriptionId}`, `PATCH /v3/subscriptions/{subscriptionId}`. - **Installments:** `POST /v3/installments`, `GET /v3/installments`, `GET /v3/installments/{installmentId}`, `PATCH /v3/installments/{installmentId}`. - **Charges:** `POST /v3/payments`, `GET /v3/payments/{paymentId}`, and the charge lists of a customer, a subscription and an installment. - **Recurring Charge Callback**, and the signed **Recurring Return URL**. ### New: other changes - **Payment intent:** the new status `authorized`. A card saved with `validate_only` has this status. The new field `tokenize` is only on a payment intent from Save a card. - **List transactions:** the new filter `recurring_type` (`on_demand`, `subscription` or `installment`). - **Transaction object:** for card recurring, the fields `recurring_customer_id`, `subscription` and `installment`. - **Settlements:** Boost settles and pays its own settlements. Each settlement has the new field `settled_by` (`Bayarcash` or `Boost`). The ID starts with `pay_` for Bayarcash and `bpay_` for Boost. The list has the new filters `settled_by`, `per_page` and `page`. ### Now in this reference This reference did not show these items before. - **Transaction status:** the codes `6` Authorized, `7` Void and `8` Refund. Make sure that your code accepts them. - **Transaction object:** the fields `platform_fees`, `nett_amount` and `payment_intent_id`. For Direct Debit: `transaction_type`, `application_reason` and `mandate`. - **Payment intent:** when `generate_qr` is `true`, `url` is the page of the QR, not the checkout page. ### Corrections - **Idempotency:** Bayarcash keeps only a successful (2xx) first response. If the first request fails, you can send it again with the same key. See [Idempotency](#tag/idempotency). - **Methods:** a method that a path does not accept returns `405`, also with no token. - **Payer identity verification:** `payer_identity_verified` and `fpx_extra_info` are only in the transaction callback. `GET /v3/transactions/{id}` does not have them. - **Get a settlement:** `payout_id` is in the path, not in the query. ## 29 Oct 2026 - **Short links:** each endpoint has a short link, for example `#tag/duitnow-qr/create-duitnow-qr`. The old links go to the new links. ## 28 Oct 2026 - **Direct Debit:** `frequency_mode` accepts only `WK` (weekly), `MT` (monthly) and `YR` (yearly). Bayarcash does not offer daily Direct Debit. - **API version:** the reference shows version 3.0.0. ## 27 Oct 2026 - **Direct Debit:** Bayarcash does not refund the RM1.00 enrolment debit. A mandate change cannot move to a different bank. The mandate callbacks have `application_type`. - **Callbacks:** the retries and the status codes of each callback. - **Merchant Registration:** removed from this reference. Bayarcash selects the merchants that can use it. ## 21 Aug 2026 - The first release of this reference for API v3. ## Payments ## Payment Intent ### Initialize Payment `POST /v3/payment-intents` Create a payment intent to start a payment. - For FPX and FPX B2B, you can verify the identity of the payer. See [Payer Identity Verification](#tag/payer-identity-verification). - To send the request again safely, add the `Idempotency-Key` header. See [Idempotency](#tag/idempotency). - For a DuitNow QR channel, set `generate_qr` to `true`. The response then also has the QR, in the `duitnow_qr` object. You show this QR on your own page. Parameters: - `Idempotency-Key` (header, string, optional): Optional. A unique key to ensure idempotent request processing. If provided, the API will return the cached response for duplicate requests with the same key and parameters. Keys are scoped per merchant and portal, and expire after 24 hours. We recommend using a UUID v4. Request body (JSON): - `payment_channel` (integer, required, one of: 1, 23, 4, 5, 12, 6, 9, 10, 11, 13, 14, 15, 16, 17, 18, 21, 7, 8, 19): The ID of the payment channel. See [Payment Channels](#tag/payment-channels) for each channel. - `portal_key` (string, required) - `order_number` (string, required) - `amount` (number, required) - `payer_name` (string, required) - `payer_email` (string, required) - `payer_telephone_number` (string, optional) - `payer_bank_code` (string, optional) - `payer_bank_name` (string, optional) - `metadata` (string, optional) - `return_url` (string, optional) - `callback_url` (string, optional) - `autosubmit_form` (boolean, optional): Optional. Set to `true` to send the payment to the selected bank automatically. FPX only. You must also send `payer_bank_code`. - `link_expired_at` (string, optional): Optional. The date and time when the payment link expires. The default is 1 hour after you create the payment intent. - `platform_id` (string, optional) - `checksum` (string, optional) - `verify_identity` (boolean, optional): Optional. Set to `true` to verify the identity of the payer. Only for FPX (`1`) and FPX B2B (`23`). See [Payer Identity Verification](#tag/payer-identity-verification). - `fpx_eaccount_number` (string, optional): Required when `verify_identity` is `true`. The bank account number of the payer. - `fpx_ebuyer_id` (string, optional): Required when `verify_identity` is `true`. The NRIC, passport number or business registration number of the payer. - `generate_qr` (boolean, optional): Optional. Set to `true` to get the DuitNow QR in the same response. You then do not need a second request. The response then has a `duitnow_qr` object: - `qr_image`: a PNG data URI. Put it in an `img` tag. - `qr_string`: the QR data, if you make the QR image yourself. - `qr_expires_at`, `poll_url`, `next_poll_after_ms` and `transaction_id`. Rules: - `payment_channel` must be one DuitNow QR channel: 6 to 11, or 13 to 15. - `link_expired_at` must be at least 5 minutes after the request. The QR is valid for approximately 5 minutes. If Bayarcash cannot make the QR, the API returns 403 or 502, with the `payment_intent_id`. The payment intent stays as a cancelled record. Send the same request again. If you used an `Idempotency-Key`, you can send the same key again. Responses: - 201: Successful response - 403: `generate_qr` was `true`, but this payment intent cannot have a DuitNow QR. The `payment_channel` is not a DuitNow QR channel, or `link_expired_at` is less than 5 minutes after the request. - 502: `generate_qr` was `true`, but Bayarcash could not make the QR because of a failure at the QR provider. Send the same request again. Callbacks: Pre-Transaction, Transaction, Transaction Receipt. ### Get a Payment Intent `GET /v3/payment-intents/{payment_intent_id}` Get a payment intent to check the payment status. The response is the payment intent object. Parameters: - `payment_intent_id` (path, string, required): Payment Intent ID Responses: - 200: Successful response ### Cancel a Payment Intent `DELETE /v3/payment-intents/{payment_intent_id}` Cancel a payment intent. After you cancel it, nobody can pay it. You can cancel a payment intent only when nobody paid it and its status allows a cancellation. If a payment has the status pending, wait for its final status: successful, unsuccessful or expired. Then cancel the payment intent. Parameters: - `payment_intent_id` (path, string, required): Payment Intent ID Responses: - 201: Payment intent successfully cancelled. The cancelled payment intent object is returned. - 403: The payment intent cannot be cancelled (for example, it has already been paid or a payment attempt is still pending). ## DuitNow QR ### Generate a DuitNow QR for a Payment Intent `POST /v3/payment-intents/{payment_intent_id}/duitnow-qr` Make a DuitNow QR code for a payment intent, and show it on your own page. The payer then does not go to the Bayarcash payment page. The response has 2 fields for the QR: - `qr_image`: a PNG data URI. Put it in an `img` tag. - `qr_string`: the QR data, if you make the QR image yourself. The payment intent must use a DuitNow QR payment channel, and nobody must have paid it. > [!TIP] > You can do this in 1 step. Send `generate_qr: true` when you create the payment intent. The response then has the same `duitnow_qr` object. Use this endpoint to make a new QR after a QR expires. The callback to your `callback_url` is the main payment notification. Use the `poll_url` in this response only to update your page. Wait `next_poll_after_ms` between 2 polls. Stop when the QR expires (`qr_expires_at`) or when the status is final. When a QR is active (not expired and not paid), each call gives the same QR with HTTP 200. After the QR expires, a new call makes a new QR for the same payment intent. Parameters: - `payment_intent_id` (path, string, required): Payment Intent ID Responses: - 201: QR code generated (200 is returned instead when an active QR already exists and is being re-served). - 403: The payment intent is not a DuitNow QR payment, is no longer payable, or the merchant is not allowed to accept this payment. - 404: Payment intent not found. - 409: A QR generation attempt is already in progress for this payment intent (concurrent request). Retry. - 502: The QR code could not be generated due to an upstream failure. Retry the request. ### Poll DuitNow QR payment status `GET /v3/transactions/{transaction_id}/duitnow-qr/status` Get the status of a DuitNow QR transaction that you made with the Generate DuitNow QR endpoint. Use it only to update your page. The callback to your `callback_url` is the main payment notification. Bayarcash gets the status from its records. If nobody checked the status recently, Bayarcash checks with the provider before it answers. - Wait `next_poll_after_ms` between 2 polls. When it is `null`, stop. It is `null` when the status is final or when `qr_expired` is `true`. - The limit is 30 requests each minute for each transaction. There is also a limit for each merchant. A 429 response has a `Retry-After` header. - Status codes: 0 new, 1 pending, 2 unsuccessful, 3 successful, 4 cancelled, 5 abandoned. - After `qr_expires_at`, `qr_expired` is `true` and `next_poll_after_ms` is `null`. The transaction can stay pending for some time after this. Treat an expired QR as failed. If the payer still wants to pay, make a new QR. Parameters: - `transaction_id` (path, string, required): Transaction ID (returned as transaction_id when generating the QR) Responses: - 200: Current status of the QR transaction. - 404: Transaction not found, or the transaction has no DuitNow QR code. - 429: Rate limit exceeded. Honour the Retry-After header before polling again. ## Transaction ### Get a list of all transactions `GET /v3/transactions` Get a list of all transactions. The response is an array of transaction objects. Parameters: - `order_number` (query, string, optional): Filter transactions by their order number. - `recurring_type` (query, string, optional, one of: on_demand, subscription, installment): Show only one type of card recurring charge: `on_demand` (from `POST /v3/payments`), `subscription` or `installment`. To find an on-demand charge with its `reference`, use it with `order_number`: `?order_number={reference}&recurring_type=on_demand`. - `status` (query, integer, optional, one of: 0, 1, 2, 3, 4, 5, 6, 7, 8) - `payment_channel` (query, integer, optional, one of: 1, 23, 4, 5, 3, 12, 6, 9, 10, 11, 13, 14, 15, 16, 17, 18, 21, 7, 8, 19) - `exchange_reference_number` (query, string, optional) - `payer_email` (query, string, optional) Responses: - 200: Successful response ### Get a transaction `GET /v3/transactions/{transaction_id}` Get a transaction to check its status. The response is the transaction object. Parameters: - `transaction_id` (path, string, required): Transaction ID Responses: - 200: Successful response ## Banks List ### Get the FPX bank list `GET /v3/banks` Get the bank codes for **buyer_bank_code** and **buyer_bank_name** in an FPX payment request. The list has the banks for **FPX** and **Direct Debit** online banking. Responses: - 200: Successful response ### Get the DuitNow Online Banking/Wallets (DOBW) bank list `GET /v3/duitnow/dobw/banks` Get the list of banks and e-wallets for DuitNow Online Banking/Wallets (DOBW). Responses: - 200: Successful response ## Recurring ## Direct Debit ### Get a list of all Direct Debit mandates `GET /v3/mandates` Get a list of all Direct Debit mandates. The response is an array of Direct Debit objects. Parameters: - `order_number` (query, string, optional): Filter transactions by their order number. - `status` (query, integer, optional, one of: 0, 1, 2, 3, 4, 6, 7) - `payer_email` (query, string, optional) Responses: - 200: Successful response ### Direct Debit Enrollment `POST /v3/mandates` Start a Direct Debit enrolment. The payer approves the e-mandate through FPX online banking. When the payer approves the e-mandate, their bank takes RM1.00 from the account. Bayarcash does not refund it. The bank statement of the payer can show it as "e-Mandate Enrolment". FPX is only for the enrolment, the maintenance and the termination of a mandate. The deductions are a separate process. They do not use FPX. Request body (JSON): - `portal_key` (string, required) - `order_number` (string, required) - `amount` (string, required): Required Between 5.00 and 30000.00 - `payer_id_type` (integer, required, one of: 1, 2, 3, 4, 5): Required 1 - New IC Number 2 - Old IC Number 3 - Passport Number 4 - Business Registration 5 - Others - `payer_id` (string, required) - `payer_name` (string, required) - `payer_email` (string, required) - `payer_telephone_number` (string, required) - `payer_bank_code` (string, optional): Optional - `payer_bank_code_hashed` (string, optional): Optional - `frequency_mode` (string, required, one of: WK, MT, YR): Required. WK - weekly, MT - monthly, YR - yearly. Bayarcash does not offer daily Direct Debit. - `max_frequency` (integer, required): Required. Maximum number of charges within a collection cycle. Defaults to 9. - `application_reason` (string, required): Required - `effective_date` (string, required): Required. Defaults to the next day. - `expiry_date` (string, optional): Optional - `metadata` (string, optional) - `return_url` (string, optional) - `success_url` (string, optional) - `failed_url` (string, optional) - `maintenance_url` (string, optional) - `termination_url` (string, optional) - `link_expired_at` (string, optional): Optional. Payment link expiry datetime. Defaults to 1 hour from creation. - `platform_id` (string, optional) - `checksum` (string, optional) Responses: - 200: Successful response Callbacks: Bank Authorization (Success/Failed Redirect), Bank Approval, Transaction. ### Get a Direct Debit mandate `GET /v3/mandates/{mandate_id}` Get a Direct Debit mandate to check its status. The response is the Direct Debit object. Parameters: - `mandate_id` (path, string, required): Mandate ID Responses: - 200: Successful response ### Direct Debit Maintenance `PUT /v3/mandates/{mandate_id}` Change a Direct Debit mandate, for example the amount. The payer approves the change through FPX online banking. - To change the bank account, the payer selects a different account in their online banking. - A change cannot move the mandate to a different bank. The change always goes to the bank of the enrolment. To use a different bank, end the mandate and start a new enrolment. FPX is only for the enrolment, the maintenance and the termination of a mandate. The deductions are a separate process. They do not use FPX. Parameters: - `mandate_id` (path, string, required): Mandate ID Request body (JSON): - `amount` (string, required): Required Between 5.00 and 30000.00 - `payer_email` (string, required) - `payer_telephone_number` (string, required) - `frequency_mode` (string, required, one of: WK, MT, YR): Required. WK - weekly, MT - monthly, YR - yearly. Bayarcash does not offer daily Direct Debit. - `max_frequency` (integer, required): Required. Maximum number of charges within a collection cycle. Defaults to 9. - `application_reason` (string, required): Required - `metadata` (string, optional): Optional - `link_expired_at` (string, optional): Optional. Payment link expiry datetime. Defaults to 1 hour from creation. - `platform_id` (string, optional): Optional - `checksum` (string, optional): Optional Responses: - 200: Successful response Callbacks: Bank Authorization (Success/Failed Redirect), Authorization, Bank Approval. ### Direct Debit Termination `DELETE /v3/mandates/{mandate_id}` End a Direct Debit mandate. The payer approves the termination through FPX online banking. After the termination, Bayarcash makes no more deductions. FPX is only for the enrolment, the maintenance and the termination of a mandate. The deductions are a separate process. They do not use FPX. Parameters: - `mandate_id` (path, string, required): Mandate ID Request body (JSON): - `application_reason` (string, required): Required - `link_expired_at` (string, optional): Optional. Payment link expiry datetime. Defaults to 1 hour from creation. - `platform_id` (string, optional) - `checksum` (string, optional): Optional Responses: - 200: Successful response Callbacks: Bank Authorization (Success/Failed Redirect), Authorization, Bank Approval. ### Activate a Direct Debit mandate `PATCH /v3/mandates/{mandate_id}/activate` Activate an inactive mandate again. It is then part of the next deduction cycle. You can activate only a mandate with the status `Inactive`. Parameters: - `mandate_id` (path, string, required): Mandate ID Responses: - 200: Mandate successfully activated. The mandate object is returned. - 422: The mandate is not in a state that can be activated. - 500: Error processing request. ### Deactivate a Direct Debit mandate `PATCH /v3/mandates/{mandate_id}/deactivate` Remove an active mandate from the deductions. This does not end the mandate. Only the payer can end it. You can deactivate only a mandate with the status `Active`. Parameters: - `mandate_id` (path, string, required): Mandate ID Responses: - 200: Mandate successfully deactivated. The mandate object is returned. - 422: The mandate is not in a state that can be deactivated. - 500: Error processing request. ### Get a list of all Direct Debit transactions `GET /v3/mandates/transactions` Get a list of all Direct Debit transactions. The list has the mandate applications and the deductions. The response is an array of transaction objects. Parameters: - `order_number` (query, string, optional): Filter transactions by their order number. - `status` (query, integer, optional, one of: 0, 1, 2, 3, 4, 5, 6, 7, 8) - `exchange_reference_number` (query, string, optional) - `payer_email` (query, string, optional) Responses: - 200: Successful response ### Get a Direct Debit transaction `GET /v3/mandates/transactions/{transaction_id}` Get a Direct Debit transaction to check its status. The response is the transaction object. Parameters: - `transaction_id` (path, string, required): Transaction ID Responses: - 200: Successful response ## Card Recurring ## Customers A customer is the person that a subscription, an installment or an on-demand charge bills. A customer belongs to your account, not to a portal. Each customer has a unique email address. You can also create a customer in the same request as a subscription, an installment or an on-demand charge. Use the `customer` object for this. ### Get a list of customers `GET /v3/customers` Parameters: - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) - `search` (query, string, optional): Find customers by full name or email. Responses: - 200: A list of customers, in pages. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. ### Create a customer `POST /v3/customers` Create the customer for a subscription, an installment or an on-demand charge. Only the merchant can create a customer. An agent, admin or staff user gets `401`. Each customer has a unique email address. The comparison ignores the case. If you already have a customer with the email, the API returns `422` `customer_email_exists`, and it creates nothing. Use the ID of that customer. A new customer returns `201`. There is no `Idempotency-Key`. The email stops a second create. If a create gets no response or a `5xx` (for example a `504` from a proxy), send it again: - A `422` `customer_email_exists` tells you that Bayarcash recorded the first create. Find it with `GET /v3/customers?search={email}`. - If the search finds nothing, the provider has the email outside your records. Contact Bayarcash support. A new customer has no card. To save a card, the payer completes the card page of an enrolment, or you use [Save a card](#tag/customers/save-card). Request body (JSON): - `full_name` (string, required) - `email` (string, required) - `phone` (string, required): The provider requires it. Responses: - 201: Bayarcash created the customer. - 401: Only a merchant can create a customer, a plan, a subscription or an installment. An enterprise merchant creates its own. An agent, admin or staff user gets `401`. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 422: `customer_email_exists`: you have a customer with this email, or the payment exchange has one. Nothing was created. Or a different validation error. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ### Get a customer `GET /v3/customers/{customerId}` Get a customer. Bayarcash reads the card status from the provider, so `card_on_file` changes to `true` after the customer saves a card. If Bayarcash cannot connect to the provider, it gives the last record that it has. Parameters: - `customerId` (path, string, required) Responses: - 200: The customer - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Save a card `POST /v3/customers/{customerId}/save-card` Save the card of a customer for on-demand charges. This creates a Cards payment intent. Send the payer to the `url` in the response. This is the card page of the provider, not the Bayarcash checkout. The page: - Is available for 30 minutes after the create. - Works only 1 time. - Has no other link. The Bayarcash checkout does not open a save-card payment intent. After 30 minutes, or after the payer used the page, create a new one. ## Request Send the fields of `POST /v3/payment-intents`, but not the payer fields. Add `tokenize`. Bayarcash takes `payer_name`, `payer_email` and `payer_telephone_number` from the customer record, and ignores the values that you send. If the customer has no phone number, the API returns `422` on `payer_telephone_number`. - `tokenize` `capture`: charge the amount and save the card. The minimum amount is 2.00. - `tokenize` `validate_only`: authorize the amount and save the card. No money moves. The minimum amount is 1.00. The payment channel is always Cards (`12`). You can leave out `payment_channel`. Bayarcash refuses all other channels. Only a merchant with a card provider that can save cards can use this endpoint. Other merchants get `422` on `tokenize`. `GET /v3/payment-intents/{payment_intent_id}` gives the payment intent, with `tokenize`. A `validate_only` payment intent has the status `authorized` after the provider authorizes the card. ## No Idempotency-Key **Each call creates a new payment intent**, with its own link. The API ignores an `Idempotency-Key`. A link does not charge money, but a payer can pay each link. With `capture`, each paid link is a sale, so 2 paid links are 2 sales. After a timeout or a `5xx`, get the payment intent if you have its ID. Or create a new one. Send the payer **only the newest link**. Parameters: - `customerId` (path, string, required) Request body (JSON): - `tokenize` (string, required, one of: capture, validate_only): - `capture`: charge the amount and save the card. The minimum amount is 2.00. - `validate_only`: authorize the amount and save the card. No money moves. The minimum amount is 1.00. - `payment_channel` (integer, optional, one of: 12): Optional. Cards (`12`). Bayarcash saves a card only on this channel. - `portal_key` (string, required): One of your portals, with the Cards channel switched on. - `order_number` (string, required) - `amount` (number, required): The minimum is 2.00 for `capture` and 1.00 for `validate_only`. - `metadata` (string, optional) - `return_url` (string, optional) - `callback_url` (string, optional) - `terminal_mode` (boolean, optional): Optional. Set to `true` for terminal (POS) mode. - `link_expired_at` (string, optional): Not used. A save-card payment intent always expires 30 minutes after the create, the same as the card page. The API ignores this value. - `platform_id` (string, optional) - `checksum` (string, optional): Optional. To send it, make it the same as for `POST /v3/payment-intents`. Use `payment_channel` `12`, also when you do not send `payment_channel`. Use the `full_name` and `email` of the customer record, exactly, as `payer_name` and `payer_email`. A different name, email or channel gives `422` `Data checksum mismatch.` Responses: - 201: Bayarcash created the payment intent. The payer is the customer. - 401: Only the merchant that owns the record can change it. This applies to a plan update, a status change, a charge and a saved card. An enterprise or agent user can read the record of a child merchant, but gets `401` for a change. - 403: - `recurring_not_enabled`: card recurring is not switched on for this merchant. - `save_card_refused`: the provider refused the card page, and a retry will not help. For example, the account is suspended or not approved yet. `message` gives the cause. `payment_intent_id` is the payment intent, which is closed. Correct the cause before you send a new request. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 422: A field is not correct. This error body is the same as for `POST /v3/payment-intents`, not the card recurring error body. - 502: `save_card_failed`: Bayarcash could not start the card page. The provider did not start the payment, or did not answer in time. Nobody can pay this payment intent. It has the status `cancelled`, or `processing` if the provider started it. `payment_intent_id` is the reference for support. Send a new request, and send the payer only the newest link. ## Plans A plan gives the price and the interval of a subscription. A plan belongs to your account, not to a portal. Each plan has your own `code`. ### Get a list of plans `GET /v3/plans` Parameters: - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) - `search` (query, string, optional): Find plans by name. - `code` (query, string, optional): Your own plan `code`, an exact match. The case is ignored. Use it to find a create that got no response. Responses: - 200: A list of plans, in pages. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. ### Create a plan `POST /v3/plans` Create a plan. A plan gives the price and the interval of a subscription. Only the merchant can create a plan. An agent, admin or staff user gets `401`. Each plan has your own `code`. The code is unique among your plans for all time. A deleted plan keeps its code. The comparison ignores the case, so `PLAN-1` and `plan-1` are the same code. There is no `Idempotency-Key`. If you already have a plan with the code, the API returns `422` `plan_code_already_used` before all other checks, and it records nothing. Bayarcash records the plan only after the payment exchange answers. Thus, after a `502`, no plan has the code, and you can send the request again. If the create gets no response or a `5xx` (for example a `504` from a proxy), send it again. A `422` `plan_code_already_used` tells you that Bayarcash recorded the first create. Find it with `GET /v3/plans?code={code}`. Request body (JSON): - `code` (string, required): **Required.** Your own code for this plan. Use letters, digits, `_` and `-`, a maximum of 36 characters. It is unique among your plans for all time. The comparison ignores the case. Bayarcash does not send it to the provider. - `name` (string, required) - `description` (string, optional): Optional. If you do not send it, Bayarcash uses `name`. The provider must have a description. - `price` (number, required) - `currency` (string, optional) - `interval` (string, required, one of: day, week, month, year): The interval of the charges of a plan or an installment. Responses: - 201: Bayarcash created the plan. - 401: Only a merchant can create a customer, a plan, a subscription or an installment. An enterprise merchant creates its own. An agent, admin or staff user gets `401`. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 422: `plan_code_already_used`: you have a plan with this `code`. Nothing was recorded. Or a different validation error. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ### Get a plan `GET /v3/plans/{planId}` Parameters: - `planId` (path, string, required) Responses: - 200: The plan - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Update a plan `PATCH /v3/plans/{planId}` Send 1 field or more. You cannot change `name`. A change to a plan also changes the subscriptions of the plan. Parameters: - `planId` (path, string, required) Request body (JSON): - `description` (string, optional) - `price` (number, optional) - `currency` (string, optional) - `interval` (string, optional, one of: day, week, month, year): The interval of the charges of a plan or an installment. Responses: - 200: The updated plan - 401: Only the merchant that owns the record can change it. This applies to a plan update, a status change, a charge and a saved card. An enterprise or agent user can read the record of a child merchant, but gets `401` for a change. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 422: - `validation_error`: a field in the body is not correct. This includes a `portal_key` that is not yours, that has no card channel, or that is of a merchant with no card recurring. `fields.portal_key` tells you. - `recurring_not_configured`: card recurring is not set up for the card gateway of the merchant. This is not the same as `recurring_not_enabled` (`403`). - `upstream_rejected`: the payment exchange refused the request. `fields` gives the details. - `invalid_transition`: on a status change, the current status does not permit the new status. - `reference_already_used`: on a create of a subscription, an installment or a charge, you used the `reference` before. Bayarcash sends and records nothing. - `customer_email_exists`: the payment exchange has the email of the `customer` object outside your records. Or one of your customers in a card account that you do not use now has it. Bayarcash sends and records nothing. - `customer_already_subscribed`: on a create of a subscription, you have a subscription for the same customer and plan with the status `pending`, `active` or `paused`. Cancel it first. - `plan_code_already_used`: on a create of a plan, you have a plan with the `code`. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ## Subscriptions A subscription charges the card of a customer at the price and the interval of a plan. It continues until you, the customer or the provider stops it. See [Card Recurring Overview](#tag/card-recurring-overview). ### Get a list of subscriptions `GET /v3/subscriptions` Parameters: - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) - `customer_id` (query, string, optional) - `status` (query, string, optional, one of: pending, active, paused, canceled, expired, terminated, failed) - `reference` (query, string, optional): Your own `reference`, an exact match. The case is ignored. Use it to find a create that got no response. Responses: - 200: A list of subscriptions, in pages. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. ### Create a subscription `POST /v3/subscriptions` Create a subscription at the provider. The response has the status `pending` and a `redirect_url`, the card page of the provider. **Send the customer to `redirect_url`.** - The subscription becomes `active` when the customer completes the card page. The provider takes the first charge at that time. - The card page is available for 20 minutes after the create. - If nobody completes the card page, the provider cancels the subscription approximately 30 minutes after the create. It then has the status `expired`. Each enrolment uses the card page, also for a customer with a saved card. ## The customer Send `customer_id` **or** a `customer` object, not both. If you already have a customer with the email of the `customer` object, Bayarcash uses that customer. If that customer is in a card account that you do not use now, the API returns `422` `customer_email_exists`, and it records and sends nothing. ## Your reference Each create has your own `reference`. There is no `Idempotency-Key`. The reference stops a second agreement. - **A reference that you used before** gets `422` `reference_already_used` before all other checks. This occurs in all conditions: a different status, the same body or a different body, a different case, and a request that is not complete. Bayarcash sends and records nothing. **Do not send a create again. Read it.** - **A customer with a subscription to the plan** gets `422` `customer_already_subscribed`. This occurs when you have a subscription for the same customer and plan with the status `pending`, `active` or `paused`. Bayarcash sends and records nothing. First cancel the old subscription (`PATCH` with `status` `canceled`). A subscription that has the status `canceled`, `terminated`, `expired` or `failed` does not count. The provider can also have a subscription for the customer and plan that you do not have. Then the API also returns `customer_already_subscribed`, and Bayarcash keeps the new subscription as `failed`. ## When you do not get a clear response - **`202`**: the payment exchange did not answer. Bayarcash recorded the subscription as `pending`. The status usually changes in 6 minutes, a maximum of approximately 10 minutes. Get it with `GET /v3/subscriptions/{id}`. The `id` is in the `202`. - **No response, or a `5xx`** (for example a `504` from a proxy): get `GET /v3/subscriptions?reference={reference}`. If no subscription has the reference, send the request again. If one has it, read it. Do not send the create again. - **The exchange refused the create:** usually `422` `upstream_rejected`, with `fields` when the exchange gave them. Or `409` `upstream_conflict`, `404` `not_found`, `429` `rate_limited` or `502` `upstream_auth`. Nothing was created. Bayarcash keeps the subscription as `failed`, and you cannot use the reference again. Correct the request, or wait for `Retry-After`. Then send it with a new reference. ## The card page `redirect_url` is in each response while the subscription is `pending` and Bayarcash knows the card page. After a `202`, it is in `GET /v3/subscriptions/{id}` when the create is complete. Use `created_at` to calculate the time that remains. After 20 minutes the link does not work, also when the status is still `pending`. The `pending` subscription also stops a new create for the same customer and plan. Cancel it, or wait for `expired`. Then send a new create with a new `reference`. The charges come to `callback_url` as the [Recurring Charge Callback](#tag/charges/webhook/POST/recurringchargecallback). The first callback tells you that the enrolment is complete. The customer then goes to `return_url`. There is no webhook for a status change. Get the subscription to see its status. Request body (JSON): - `portal_key` (string, required): The portal of this sale. It is required on the 3 requests that move money, `POST /v3/subscriptions`, `POST /v3/installments` and `POST /v3/payments`. It must be one of your own portals, not the portal of a child merchant. It must have the Cards channel, because a recurring charge is a card payment. A customer and a plan belong to your account, not to a portal. Save a card uses `portal_key` the same as `POST /v3/payment-intents`. - `reference` (string, required): **Required.** Your own reference for this subscription, installment or on-demand charge. Use letters, digits, `_` and `-`, a maximum of 36 characters. It is unique for each merchant and each type, for all time. You cannot use it again, also after the record failed or ended. The comparison ignores the case. A reference that you used before gets `422` `reference_already_used` before all other checks. After a `202`, a timeout or a `5xx`, read the result. Do not send the create again. Each charge gives the reference back as `order_number`. - `customer_id` (string, optional): Required if you do not send `customer`. Do not send it with `customer`. - `customer` (object, optional): Create a customer, or use a customer, in the same request. Do not send it with `customer_id`. If you have a customer with the email, Bayarcash uses that customer. If that customer is in a card account that you do not use now, the API returns `422` `customer_email_exists`, and Bayarcash records and sends nothing. - `plan_id` (string, required): One of your plans. An unknown plan, or the plan of a different merchant, gets `422` `validation_error` on `plan_id` ("Invalid plan id."). Bayarcash creates nothing. - `start_date` (string, required): A full ISO 8601 timestamp, a minimum of 1 hour in the future. The first charge occurs when the customer completes the card page. The schedule then starts from this date. - `callback_url` (string, optional): Bayarcash sends the Recurring Charge Callback here for each charge of this subscription, at each status change. Bayarcash does not send it to the provider. Use a public http or https URL, a maximum of 500 characters. A private, loopback or internal host gets `422`. - `return_url` (string, optional): The customer goes here after the card page. The query string has the status of the agreement and a checksum. See Recurring Return URL in the Card Recurring Overview. Bayarcash does not send it to the provider. Use a public http or https URL, a maximum of 500 characters. A private, loopback or internal host gets `422`. Responses: - 201: Bayarcash created the subscription at the provider, with the status `pending`. Send the customer to `redirect_url`. - 202: The payment exchange did not answer. Bayarcash recorded the subscription as `pending`, with no `redirect_url` yet. The status usually changes in 6 minutes, a maximum of approximately 10 minutes. Get it with `GET /v3/subscriptions/{id}`. While it is `pending`, the response has `redirect_url`. The card page is available for 20 minutes after the create. After that, cancel the subscription or wait for `expired`. Then send a new create with a new `reference`. Do not send the same create again. - 401: Only a merchant can create a customer, a plan, a subscription or an installment. An enterprise merchant creates its own. An agent, admin or staff user gets `401`. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 409: `upstream_conflict`: the exchange refused the create because of the current condition at the provider. Bayarcash keeps the subscription as `failed`. - 422: `customer_already_subscribed`: you have a subscription for this customer and plan with the status `pending`, `active` or `paused`. Bayarcash sent and recorded nothing. Cancel the old one first. The provider can also have such a subscription that you do not have. Then Bayarcash keeps the new subscription as `failed`. Or a different validation error. - 429: `rate_limited`: the exchange got too many requests. Nothing was created. Bayarcash keeps the subscription as `failed`, and you cannot use the reference again. Wait for the time in `Retry-After`. Then send the request with a new reference. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ### Get a subscription `GET /v3/subscriptions/{subscriptionId}` Get a subscription. Bayarcash reads the status from the provider. If it cannot connect to the provider, it gives the last record that it has. The response does not have the charges. To get them, use `GET /v3/subscriptions/{id}/payments`. While the subscription is `pending` and Bayarcash knows the card page, the response has `redirect_url`. The card page is available for 20 minutes after `created_at`. After that, cancel the subscription or wait for `expired` (approximately 30 minutes after the create). Then send a new create with a new `reference`. Until then, a new create for the same customer and plan gets `422` `customer_already_subscribed`. Parameters: - `subscriptionId` (path, string, required) Responses: - 200: The subscription - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Change the status of a subscription `PATCH /v3/subscriptions/{subscriptionId}` Pause, continue, cancel or terminate a subscription. Use the American spelling `canceled`. The API refuses `cancelled`. Bayarcash first reads the current status from the provider. These changes are permitted: - `pending` to `canceled`. - `active` to `paused`, `terminated` or `canceled`. - `paused` to `active`, `terminated` or `canceled`. You cannot change a subscription that ended, also not to the same status. All other changes get `422` `invalid_transition`, and Bayarcash sends nothing to the provider. You cannot change the card of a subscription. Terminate it, and enrol the customer again. Parameters: - `subscriptionId` (path, string, required) Request body (JSON): - `status` (string, required, one of: active, canceled, terminated, paused) - `next_payment_date` (string, optional): Optional. It must be in the future. Responses: - 200: The updated subscription - 401: Only the merchant that owns the record can change it. This applies to a plan update, a status change, a charge and a saved card. An enterprise or agent user can read the record of a child merchant, but gets `401` for a change. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 422: - `validation_error`: a field in the body is not correct. This includes a `portal_key` that is not yours, that has no card channel, or that is of a merchant with no card recurring. `fields.portal_key` tells you. - `recurring_not_configured`: card recurring is not set up for the card gateway of the merchant. This is not the same as `recurring_not_enabled` (`403`). - `upstream_rejected`: the payment exchange refused the request. `fields` gives the details. - `invalid_transition`: on a status change, the current status does not permit the new status. - `reference_already_used`: on a create of a subscription, an installment or a charge, you used the `reference` before. Bayarcash sends and records nothing. - `customer_email_exists`: the payment exchange has the email of the `customer` object outside your records. Or one of your customers in a card account that you do not use now has it. Bayarcash sends and records nothing. - `customer_already_subscribed`: on a create of a subscription, you have a subscription for the same customer and plan with the status `pending`, `active` or `paused`. Cancel it first. - `plan_code_already_used`: on a create of a plan, you have a plan with the `code`. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ## Installments An installment divides a total amount into 2 to 60 charges at a fixed interval. It has no plan. See [Card Recurring Overview](#tag/card-recurring-overview). ### Get a list of installments `GET /v3/installments` Parameters: - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) - `customer_id` (query, string, optional) - `status` (query, string, optional, one of: pending, active, paused, canceled, expired, terminated, failed, completed) - `reference` (query, string, optional): Your own `reference`, an exact match. The case is ignored. Use it to find a create that got no response. Responses: - 200: A list of installments, in pages. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. ### Create an installment `POST /v3/installments` Create an installment at the provider. It works the same as [Create a subscription](#tag/subscriptions/create-subscription). The response has the status `pending` and a `redirect_url`, the card page of the provider. **Send the customer to `redirect_url`.** An installment has its own amount, interval and number of charges. It has no plan. - **Your reference:** each create has your own `reference`, unique among your installments. There is no `Idempotency-Key`. A reference that you used before gets `422` `reference_already_used` before all other checks. Bayarcash sends and records nothing. - **`202`:** the payment exchange did not answer. Bayarcash recorded the installment as `pending`. Get it with `GET /v3/installments/{id}`. The status usually changes in 6 minutes, a maximum of approximately 10 minutes. - **No response, or a `5xx`:** get `GET /v3/installments?reference={reference}`. If the list is empty, send the request again. If not, read the installment. - **The exchange refused the create:** usually `422` `upstream_rejected`, or `429` `rate_limited` or `502` `upstream_auth`. Nothing was created. Bayarcash keeps the installment as `failed`. Correct the request, and send it with a new reference. Do not send a create again. Read it. `redirect_url` is in each response while the installment is `pending` and Bayarcash knows the card page. The card page is available for 20 minutes after the create. Use `created_at` to calculate the time that remains. After 20 minutes the link does not work, also when the status is `pending`. Then send a new create with a new `reference`. The provider cancels a `pending` installment approximately 30 minutes after the create. It then has the status `expired`. The charges come to `callback_url`. The customer goes to `return_url`. Get the installment to see its status. Request body (JSON): - `portal_key` (string, required): The portal of this sale. It is required on the 3 requests that move money, `POST /v3/subscriptions`, `POST /v3/installments` and `POST /v3/payments`. It must be one of your own portals, not the portal of a child merchant. It must have the Cards channel, because a recurring charge is a card payment. A customer and a plan belong to your account, not to a portal. Save a card uses `portal_key` the same as `POST /v3/payment-intents`. - `reference` (string, required): **Required.** Your own reference for this subscription, installment or on-demand charge. Use letters, digits, `_` and `-`, a maximum of 36 characters. It is unique for each merchant and each type, for all time. You cannot use it again, also after the record failed or ended. The comparison ignores the case. A reference that you used before gets `422` `reference_already_used` before all other checks. After a `202`, a timeout or a `5xx`, read the result. Do not send the create again. Each charge gives the reference back as `order_number`. - `customer_id` (string, optional): Required if you do not send `customer`. Do not send it with `customer`. - `customer` (object, optional): Create a customer, or use a customer, in the same request. Do not send it with `customer_id`. If you have a customer with the email, Bayarcash uses that customer. If that customer is in a card account that you do not use now, the API returns `422` `customer_email_exists`, and Bayarcash records and sends nothing. - `total_amount` (number, required): The total amount to collect. The minimum is MYR 5.00. - `currency` (string, optional) - `interval` (string, required, one of: day, week, month, year): The interval of the charges of a plan or an installment. - `installment_count` (integer, required) - `description` (string, required): The item that the customer pays for. An installment has no plan to give a name. - `start_date` (string, required): A full ISO 8601 timestamp, a minimum of 1 hour in the future. The first charge occurs when the customer completes the card page. The schedule then starts from this date. - `callback_url` (string, optional): Bayarcash sends the Recurring Charge Callback here for each charge of this installment, at each status change. Use a public http or https URL, a maximum of 500 characters. A private, loopback or internal host gets `422`. - `return_url` (string, optional): The customer goes here after the card page. The query string has the status of the agreement and a checksum. See Recurring Return URL in the Card Recurring Overview. Use a public http or https URL, a maximum of 500 characters. A private, loopback or internal host gets `422`. Responses: - 201: Bayarcash created the installment at the provider, with the status `pending`. Send the customer to `redirect_url`. - 202: The payment exchange did not answer. Bayarcash recorded the installment as `pending`, with no `redirect_url` yet. The status usually changes in 6 minutes, a maximum of approximately 10 minutes. Get it with `GET /v3/installments/{id}`. While it is `pending`, the response has `redirect_url`. The card page is available for 20 minutes after the create. After that, send a new create with a new `reference`. Do not send the same create again. - 401: Only a merchant can create a customer, a plan, a subscription or an installment. An enterprise merchant creates its own. An agent, admin or staff user gets `401`. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 409: `upstream_conflict`: the exchange refused the create because of the current condition at the provider. Bayarcash keeps the installment as `failed`. - 422: - `validation_error`: a field in the body is not correct. This includes a `portal_key` that is not yours, that has no card channel, or that is of a merchant with no card recurring. `fields.portal_key` tells you. - `recurring_not_configured`: card recurring is not set up for the card gateway of the merchant. This is not the same as `recurring_not_enabled` (`403`). - `upstream_rejected`: the payment exchange refused the request. `fields` gives the details. - `invalid_transition`: on a status change, the current status does not permit the new status. - `reference_already_used`: on a create of a subscription, an installment or a charge, you used the `reference` before. Bayarcash sends and records nothing. - `customer_email_exists`: the payment exchange has the email of the `customer` object outside your records. Or one of your customers in a card account that you do not use now has it. Bayarcash sends and records nothing. - `customer_already_subscribed`: on a create of a subscription, you have a subscription for the same customer and plan with the status `pending`, `active` or `paused`. Cancel it first. - `plan_code_already_used`: on a create of a plan, you have a plan with the `code`. - 429: `rate_limited`: the exchange got too many requests. Nothing was created. Bayarcash keeps the installment as `failed`, and you cannot use the reference again. Wait for the time in `Retry-After`. Then send the request with a new reference. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ### Get an installment `GET /v3/installments/{installmentId}` Get an installment. Bayarcash reads the status and the remaining amount from the provider. The response does not have the charges. To get them, use `GET /v3/installments/{id}/payments`. While the installment is `pending` and Bayarcash knows the card page, the response has `redirect_url`. The card page is available for 20 minutes after `created_at`. After that, send a new create with a new `reference`. Parameters: - `installmentId` (path, string, required) Responses: - 200: The installment - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Change the status of an installment `PATCH /v3/installments/{installmentId}` Pause, continue, cancel or terminate an installment. Use the American spelling `canceled`. Bayarcash first reads the current status from the provider. These changes are permitted: - `pending` to `canceled`. - `active` to `paused`, `terminated` or `canceled`. - `paused` to `active`, `terminated` or `canceled`. You cannot change an installment that ended (`canceled`, `terminated`, `completed` or `failed`), also not to the same status. All other changes get `422` `invalid_transition`, and Bayarcash sends nothing to the provider. You cannot change the card of an installment. Terminate it, and enrol the customer again. Parameters: - `installmentId` (path, string, required) Request body (JSON): - `status` (string, required, one of: active, canceled, terminated, paused) - `next_payment_date` (string, optional) Responses: - 200: The updated installment - 401: Only the merchant that owns the record can change it. This applies to a plan update, a status change, a charge and a saved card. An enterprise or agent user can read the record of a child merchant, but gets `401` for a change. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 422: - `validation_error`: a field in the body is not correct. This includes a `portal_key` that is not yours, that has no card channel, or that is of a merchant with no card recurring. `fields.portal_key` tells you. - `recurring_not_configured`: card recurring is not set up for the card gateway of the merchant. This is not the same as `recurring_not_enabled` (`403`). - `upstream_rejected`: the payment exchange refused the request. `fields` gives the details. - `invalid_transition`: on a status change, the current status does not permit the new status. - `reference_already_used`: on a create of a subscription, an installment or a charge, you used the `reference` before. Bayarcash sends and records nothing. - `customer_email_exists`: the payment exchange has the email of the `customer` object outside your records. Or one of your customers in a card account that you do not use now has it. Bayarcash sends and records nothing. - `customer_already_subscribed`: on a create of a subscription, you have a subscription for the same customer and plan with the status `pending`, `active` or `paused`. Cancel it first. - `plan_code_already_used`: on a create of a plan, you have a plan with the `code`. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ## Charges Charge a saved card, and read the charges of a customer, a subscription or an installment. Each charge is a transaction record, the same as `GET /v3/transactions/{transaction_id}`. ### Get a list of the charges of a customer `GET /v3/customers/{customerId}/payments` Get all the charges of a customer, newest first. The list has the charges of all the agreements of the customer **and** the on-demand charges. This is the only endpoint that lists on-demand charges. Each row is a transaction record, the same as `GET /v3/transactions/{transaction_id}`. Each row has `recurring_customer_id`. A charge from an agreement also has `subscription` or `installment`. `exchange_transaction_id` is the charge ID for `GET /v3/payments/{paymentId}`. Parameters: - `customerId` (path, string, required) - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) Responses: - 200: A list of charges, in pages. Each charge is a transaction record. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Get a list of the charges of a subscription `GET /v3/subscriptions/{subscriptionId}/payments` Get all the charges of this subscription, newest first. Each row is a transaction record, the same as `GET /v3/transactions/{transaction_id}`, with the subscription in `subscription`. `exchange_transaction_id` is the charge ID for `GET /v3/payments/{paymentId}`. Parameters: - `subscriptionId` (path, string, required) - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) Responses: - 200: A list of charges, in pages. Each charge is a transaction record. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Get a list of the charges of an installment `GET /v3/installments/{installmentId}/payments` Get all the charges of this installment, newest first. Each row is a transaction record, the same as `GET /v3/transactions/{transaction_id}`, with the installment in `installment`. `exchange_transaction_id` is the charge ID for `GET /v3/payments/{paymentId}`. Parameters: - `installmentId` (path, string, required) - `per_page` (query, integer, optional): The number of rows on each page. The maximum is 100. - `page` (query, integer, optional) Responses: - 200: A list of charges, in pages. Each charge is a transaction record. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ### Charge a saved card `POST /v3/payments` **Charge the saved card now.** The response is the charge, as a transaction record. `GET /v3/transactions/{id}` and `GET /v3/payments/{id}` give the same record. There is no customer page and no `return_url`. The response is the result. - `status` `3`: the charge is successful. - `status` `2`: the card declined the charge. This is a failed charge, not an error. - `status` `1`: the provider did not complete the charge yet. The final status comes to `callback_url` as the Recurring Charge Callback. The customer must have a saved card. `422` `customer_no_saved_card` tells you to save a card first with [Save a card](#tag/customers/save-card). Then send the charge with a new reference. `422` `charge_rejected` tells you that the provider refused the request. ## Your reference Your own `reference` stops a second charge. You do not need an `Idempotency-Key`. The API ignores it. - **A reference that you used before** gets `422` `reference_already_used` before all other checks. This occurs in all conditions: a different status, the same body or a different body, a different case, and a request that is not complete. Bayarcash sends, charges and records nothing. **Do not send a charge again. Read it.** - **`202` `{"reference", "status": "pending"}`**: the payment exchange did not answer, or did not complete the charge yet. **The card can have a charge.** Wait for the callback on `callback_url`. Or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand` after Bayarcash records the charge. - **No response, or a `5xx`** (for example a `504` from a proxy): do the same steps as for a `202`. The reference cannot charge 2 times. If Bayarcash recorded the first request, the same reference gets `422` `reference_already_used`. After a `202`, an empty search result is not proof that there is no charge. Bayarcash first checks the charge 15 minutes after it records it, then each 5 minutes. This usually takes approximately 20 minutes. It can take longer when Bayarcash cannot connect to the exchange, or when the exchange did not complete the charge. Use the callback. Charge again with a new reference only after a failed charge callback. Or charge again when the search is still empty a long time after that. If the provider refuses a charge after the exchange recorded it, Bayarcash records a failed transaction with your reference. A `429` `rate_limited` or a `502` `upstream_auth` means that there is no charge. Bayarcash can keep a failed record with your reference. After a `429`, wait for the time in `Retry-After`. Then send the charge with a new reference. Bayarcash sends `description` to the provider. The provider accepts only letters, digits, spaces, full stops and hyphens. Thus, the API refuses `Invoice #1042`. Request body (JSON): - `portal_key` (string, required): The portal of this sale. It is required on the 3 requests that move money, `POST /v3/subscriptions`, `POST /v3/installments` and `POST /v3/payments`. It must be one of your own portals, not the portal of a child merchant. It must have the Cards channel, because a recurring charge is a card payment. A customer and a plan belong to your account, not to a portal. Save a card uses `portal_key` the same as `POST /v3/payment-intents`. - `reference` (string, required): **Required.** Your own reference for this subscription, installment or on-demand charge. Use letters, digits, `_` and `-`, a maximum of 36 characters. It is unique for each merchant and each type, for all time. You cannot use it again, also after the record failed or ended. The comparison ignores the case. A reference that you used before gets `422` `reference_already_used` before all other checks. After a `202`, a timeout or a `5xx`, read the result. Do not send the create again. Each charge gives the reference back as `order_number`. - `customer_id` (string, optional): Required if you do not send `customer`. Do not send it with `customer`. - `customer` (object, optional): Create a customer, or use a customer, in the same request. Do not send it with `customer_id`. If you have a customer with the email, Bayarcash uses that customer. If that customer is in a card account that you do not use now, the API returns `422` `customer_email_exists`, and Bayarcash records and sends nothing. - `amount` (number, required) - `currency` (string, optional) - `description` (string, required) - `callback_url` (string, optional): Bayarcash sends the Recurring Charge Callback here for this charge, at each status change. Use a public http or https URL, a maximum of 500 characters. A private, loopback or internal host gets `422`. There is no `return_url`, because the response gives the result. Responses: - 201: The charge, as a transaction record. `status` `3` is successful, `2` is declined, `1` is not complete yet. `order_number` is your `reference`. `exchange_reference_number` is the `BPGR-` reference of the exchange. - 202: The charge is pending, and Bayarcash did not record it yet. The payment exchange did not answer, or did not complete it. The card can have a charge. Wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. Do not send the charge again. An empty result soon after the `202` is not proof. Bayarcash checks the charge 15 minutes after it records it, then each 5 minutes. This usually takes approximately 20 minutes. Charge again with a new reference only after a failed charge callback. Or charge again when the search is still empty a long time after that. - 401: Only the merchant that owns the record can change it. This applies to a plan update, a status change, a charge and a saved card. An enterprise or agent user can read the record of a child merchant, but gets `401` for a change. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. - 422: - `validation_error`: a field is not correct. - `reference_already_used`: you used the reference before. There is no charge. - `customer_no_saved_card`: the customer has no saved card. Save a card with `POST /v3/customers/{id}/save-card`. Then send the charge with a new reference. - `charge_rejected`: the provider refused the charge request. - `customer_email_exists`: the payment exchange has the email of the `customer` object outside your records. Or one of your customers in a card account that you do not use now has it. There is no charge. - `upstream_rejected`: the payment exchange refused the request. `fields` gives the details. You cannot use the reference again. - 429: `rate_limited`: the exchange got too many requests. There is no charge. Bayarcash can keep a failed record with the reference, and then you cannot use the reference again. Wait for the time in `Retry-After`. Then send the charge with a new reference. - 502: Your request did not cause this error. - `upstream_error`: Bayarcash cannot connect to the payment exchange, or the exchange has a fault. - `upstream_auth`: the exchange refused the credentials of Bayarcash. - `upstream_integrity`: Bayarcash cannot verify the answer of the exchange. It recorded nothing from it. On a create of a subscription, an installment or a charge, a timeout or a `5xx` of the exchange gives `202`, not `502`. A fault when Bayarcash gets or creates the `customer` object still gives `502`. An `upstream_auth` or a `429` `rate_limited` on the create or the charge means that nothing was created. Bayarcash can keep a failed record with the `reference`. Send the request again with a new reference. Do not send these 3 creates again with the same `reference`. A record from before the fault can have it, and the API then returns `422` `reference_already_used`. Read the result: - For a subscription or an installment, get the list with `?reference=`. If the list is empty, send the request again. - For a charge, wait for the callback, or get `GET /v3/transactions?order_number={reference}&recurring_type=on_demand`. This usually takes approximately 20 minutes. Charge again only when the callback says that the charge failed, or when the search is still empty a long time after that. `409` `upstream_conflict`: the provider refused the change because of the current condition of the record. This is not a repeated customer. That is `422` `customer_email_exists`. Get the record again before you try again. ### Get a charge `GET /v3/payments/{paymentId}` Get a charge as a transaction record, the same as `GET /v3/transactions/{id}`. The record has `recurring_customer_id`. A scheduled charge also has the `subscription` or `installment`. Send the charge ID of the provider (`exchange_transaction_id` in the charge lists and the callback), **or** the `trx_` transaction ID. On each card recurring charge, `order_number` is your `reference`, and `exchange_reference_number` is the `BPGR-` reference of the exchange. The callback sends the same values. Parameters: - `paymentId` (path, string, required) Responses: - 200: The charge, as a transaction record. - 403: `recurring_not_enabled`: card recurring is not switched on for this merchant. All card recurring endpoints give this error, also the reads. A retry does not help. Ask Bayarcash to switch it on. - 404: `not_found`: the record does not exist, or it is not a record of your account. The API does not tell you which. ## Merchant ## Merchant Portal ### Get a list of merchant portals `GET /v3/portals` Responses: - 200: Successful response ### Create a merchant portal `POST /v3/portals` Request body (JSON): - `merchant_id` (string, optional) - `name` (string, required) - `website_url` (string, optional) - `merchant_transaction_notification_email` (string, required) - `secondary_merchant_transaction_notification_email` (string, optional) - `fpx_landing_page_payment_button_text_label` (string, optional) - `payment_channels` (string, required): The IDs of the payment channels to switch on for the portal. See [Payment Channels](#tag/payment-channels) for each channel. - `enabled_sms_on_successful_transaction` (boolean, optional): Default false - `split_payment_enabled` (boolean, optional): Default false - `split_payment_merchants` (string, optional): Split payment setting. Format as below: |- [ { "merchant_email": "merchant@example.com", "type": "fix_amount", // fix_amount or percentage "value": 10 }. { ... } ] - `bank_accounts` (array of object, optional): Optional. Required when the Manual Bank Transfer channel (id 2) is enabled. Each item describes a bank account. - `cashier_id` (integer, optional): Optional. Required when the DuitNow QR channel (id 6) is enabled. Responses: - 201: Successful response ### Get a merchant portal `GET /v3/portals/{portal_id}` Parameters: - `portal_id` (path, string, required): Portal ID Responses: - 200: Successful response ### Update a merchant portal `PUT /v3/portals/{portal_id}` Parameters: - `portal_id` (path, string, required): Portal ID Request body (JSON): - `name` (string, required) - `website_url` (string, optional) - `merchant_transaction_notification_email` (string, required) - `secondary_merchant_transaction_notification_email` (string, optional) - `fpx_landing_page_payment_button_text_label` (string, optional) - `payment_channels` (array of items, optional): The IDs of the payment channels to switch on for the portal. See [Payment Channels](#tag/payment-channels) for each channel. - `enabled_sms_on_successful_transaction` (boolean, optional): Default false - `split_payment_enabled` (boolean, optional): Default false - `split_payment_merchants` (array of items, optional): Split payment setting. Each item: { merchant_email, type (fix_amount|percentage), value }. - `bank_accounts` (array of items, optional): Optional. Required when the Manual Bank Transfer channel (id 2) is enabled. Each item describes a bank account. - `cashier_id` (integer, optional): Optional. Required when the DuitNow QR channel (id 6) is enabled. Responses: - 200: Successful response. The updated portal object is returned. ### Delete a merchant portal `DELETE /v3/portals/{portal_id}` Delete a portal. After you delete it, you cannot use it to create payment intents. Parameters: - `portal_id` (path, string, required): Portal ID Responses: - 200: Portal successfully deleted ## Merchant Settlement ### Get a list of merchant settlements `GET /v3/payouts` Get all the settlements of the merchant. Bayarcash settles and pays most of them. Boost settles and pays its own settlements. - `settled_by` tells you who settled each settlement. - The ID starts with `pay_` for Bayarcash and `bpay_` for Boost. The prefix is part of the ID, because the numbers of the two parties can be the same. Parameters: - `X-API-KEY` (header, string, required): Enterprise partner API key - `settled_by` (query, string, optional, one of: Bayarcash, Boost): Show only the settlements of `Bayarcash` or `Boost`. To get both, send a comma-separated list or do not send the filter. An unknown value gives an empty list. - `per_page` (query, integer, optional): The number of rows on each page. The default is 15. The maximum is 100. - `page` (query, integer, optional): The page number. The first page is 1. Responses: - 200: Successful response ### Get a merchant settlement `GET /v3/payouts/{payout_id}` Parameters: - `X-API-KEY` (header, string, required): Enterprise partner API key - `payout_id` (path, string, required): The settlement ID from the list, with its prefix. For example, `pay_qK7gOq` for Bayarcash or `bpay_9Kq3Xm` for Boost. An ID with no known prefix gives "not found". Responses: - 200: Successful response ## Service ## Health Check ### Get the API server status `GET /v3/up` Check that the API server is available. Responses: - 200: Successful response ## Callbacks (webhooks) Bayarcash sends these requests to the URLs that you give. ### Transaction callback `POST transactionCallback` Bayarcash sends this request from its server to your server when a payment has its final status. Set the address with `callback_url` on the payment intent. Always check the `checksum` before you use the data. Use the callback as the final result. Do not use the browser redirect for this, because the payer can stop it. Your server must return HTTP 200. If it returns a different status, Bayarcash sends the callback again. It tries up to 5 times, 300 seconds (5 minutes) after the last try. | `status` | Meaning | |---|---| | 0 | New | | 1 | Pending | | 2 | Failed | | 3 | Successful | | 4 | Cancelled | | 5 | Abandoned | | 6 | Authorized | | 7 | Void | | 8 | Refund | Request body (JSON): - `record_type` (string, required): Always `transaction`. - `transaction_id` (string, required): The Bayarcash transaction ID. - `exchange_reference_number` (string, optional): The reference number from the payment network. - `exchange_transaction_id` (string, optional): The transaction ID from the payment network. - `order_number` (string, required): The `order_number` that you sent in the request. - `currency` (string, optional): The ISO 4217 currency code. - `amount` (string, required): The amount, as a decimal string. - `payer_name` (string, optional): The name of the payer. - `payer_email` (string, optional): The email address of the payer. - `payer_bank_name` (string, optional): The bank that the payer used. - `status` (integer, required): The transaction status code: 0 new, 1 pending, 2 failed, 3 successful, 4 cancelled, 5 abandoned, 6 authorized, 7 void, 8 refund. - `status_description` (string, optional): The status as text. - `datetime` (string, optional): The date and time of the event. - `checksum` (string, required): The HMAC-SHA256 of the data, made with your API Secret Key. Check it before you use the callback. Responses: - 200: Return 200 to confirm. If Bayarcash gets a different status, it sends the callback again. It tries up to 5 times, 300 seconds (5 minutes) after the last try. ### Direct Debit - authorization callback `POST mandateAuthorizationCallback` Bayarcash sends this when a payer completes or stops an enrolment, a change or a termination in their online banking. `application_type` tells which one. Request body (JSON): - `record_type` (string, required): Always `authorization`. - `mandate_id` (string, required): The mandate ID. - `transaction_id` (string, optional): The Bayarcash transaction ID. - `exchange_reference_number` (string, optional): The reference number from the payment network. - `exchange_transaction_id` (string, optional): The transaction ID from the payment network. - `order_number` (string, required): The `order_number` that you sent in the request. - `currency` (string, optional): The ISO 4217 currency code. - `amount` (string, optional): The amount, as a decimal string. - `payer_name` (string, optional): The name of the payer. - `payer_email` (string, optional): The email address of the payer. - `payer_bank_name` (string, optional): The bank that the payer used. - `status` (integer, required): The transaction status code: 0 new, 1 pending, 2 failed, 3 successful, 4 cancelled, 5 abandoned, 6 authorized, 7 void, 8 refund. - `status_description` (string, optional): The status as text. - `datetime` (string, optional): The date and time of the event. - `application_type` (string, optional): The type of mandate application: `01` enrolment, `02` maintenance (a change), `03` termination. - `checksum` (string, required): The HMAC-SHA256 of the data, made with your API Secret Key. Check it before you use the callback. Responses: - 200: Return 200 to confirm. If Bayarcash gets a different status, it sends the callback again. It tries up to 5 times, 300 seconds (5 minutes) after the last try. ### Direct Debit - bank approval callback `POST mandateBankApprovalCallback` Bayarcash sends this when the bank of the payer approves or rejects a mandate. This can come some days after the enrolment. Request body (JSON): - `record_type` (string, required): Always `bank_approval`. - `approval_date` (string, optional): The date of the decision of the bank. - `approval_status` (string, required): The decision of the bank. - `mandate_id` (string, required): The mandate ID. - `mandate_reference_number` (string, optional): The reference number of the mandate. - `order_number` (string, optional): The `order_number` that you sent in the request. - `payer_bank_code` (string, optional): The bank code of the account of the payer. - `payer_bank_code_hashed` (string, optional): The bank code, hashed. - `payer_bank_account_no` (string, optional): The bank account number of the payer, partly hidden. - `application_type` (string, optional): The type of mandate application: `01` enrolment, `02` maintenance (a change), `03` termination. - `checksum` (string, required): The HMAC-SHA256 of the data, made with your API Secret Key. Check it before you use the callback. Responses: - 200: Return 200 to confirm. If Bayarcash gets a different status, it sends the callback again. It tries up to 5 times, 300 seconds (5 minutes) after the last try. ### Direct Debit - transaction callback `POST mandateTransactionCallback` Bayarcash sends this for each deduction from an active mandate. Request body (JSON): - `record_type` (string, required): Always `transaction`. - `batch_number` (string, optional): The deduction batch of the transaction. - `mandate_id` (string, required): The mandate ID. - `mandate_reference_number` (string, optional): The reference number of the mandate. - `transaction_id` (string, optional): The Bayarcash transaction ID. - `exchange_reference_number` (string, optional): The reference number from the payment network. - `exchange_transaction_id` (string, optional): The transaction ID from the payment network. - `order_number` (string, optional): The `order_number` that you sent in the request. - `currency` (string, optional): The ISO 4217 currency code. - `amount` (string, required): The amount, as a decimal string. - `payer_name` (string, optional): The name of the payer. - `payer_email` (string, optional): The email address of the payer. - `payer_bank_name` (string, optional): The bank that the payer used. - `status` (integer, required): The transaction status code: 0 new, 1 pending, 2 failed, 3 successful, 4 cancelled, 5 abandoned, 6 authorized, 7 void, 8 refund. - `status_description` (string, optional): The status as text. - `datetime` (string, optional): The date and time of the event. - `checksum` (string, required): The HMAC-SHA256 of the data, made with your API Secret Key. Check it before you use the callback. Responses: - 200: Return 200 to confirm. If Bayarcash gets a different status, it sends the callback again. It tries up to 5 times, 300 seconds (5 minutes) after the last try. ### Recurring Charge Callback `POST recurringChargeCallback` The only card recurring webhook. Bayarcash sends it for **each** charge of a subscription, an installment or an on-demand charge, also the first charge of an enrolment. It sends it at **each change** of the charge status. - Bayarcash sends it to the `callback_url` of the agreement. For an on-demand charge, it uses the `callback_url` of `POST /v3/payments`. - A pending charge comes with `status` `1`. Then it comes again with `3` (successful) or `2` (failed). - Bayarcash does not send the same status 2 times. - If your server returns a status that is not 2xx, Bayarcash sends the callback again, up to 5 times. There is no webhook for a change of the subscription or installment status. See [Notifications](#tag/card-recurring-overview) in the Card Recurring Overview. ## Check the checksum The body is form-encoded. Form encoding removes each field that has a null value. The checksum signs these fields as empty strings. Thus, make the fixed list of fields below, and use `''` for each field that is not in the body. Do not use only the fields that came in the body. Do not change a value that you received. For example, use `amount` exactly as Bayarcash sent it. On a recurring charge, `payer_bank_name` is always null, so it is never in the body. ```php $callbackData['record_type'] ?? '', "transaction_id" => $callbackData['transaction_id'] ?? '', "exchange_reference_number" => $callbackData['exchange_reference_number'] ?? '', "exchange_transaction_id" => $callbackData['exchange_transaction_id'] ?? '', "order_number" => $callbackData['order_number'] ?? '', "currency" => $callbackData['currency'] ?? '', "amount" => $callbackData['amount'] ?? '', "payer_name" => $callbackData['payer_name'] ?? '', "payer_email" => $callbackData['payer_email'] ?? '', "payer_bank_name" => $callbackData['payer_bank_name'] ?? '', "status" => $callbackData['status'] ?? '', "status_description" => $callbackData['status_description'] ?? '', "datetime" => $callbackData['datetime'] ?? '', "charge_source" => $callbackData['charge_source'] ?? '', "subscription_id" => $callbackData['subscription_id'] ?? '', "installment_id" => $callbackData['installment_id'] ?? '', "customer_id" => $callbackData['customer_id'] ?? '', "card_brand" => $callbackData['card_brand'] ?? '', "card_country" => $callbackData['card_country'] ?? '', "card_last4" => $callbackData['card_last4'] ?? '', "card_exp_month" => $callbackData['card_exp_month'] ?? '', "card_exp_year" => $callbackData['card_exp_year'] ?? '', ]; ksort($payloadData); // Sort the payload data by key $payloadString = implode('|', $payloadData); // Join the values with '|' $validResponse = hash_equals(hash_hmac('sha256', $payloadString, $secretKey), $callbackChecksum); ``` The checksum does not sign `payment_gateway_id` and `payer_telephone_number`. It signs the fields that identify the charge and the card. Thus, nobody can connect a charge to a different subscription or a different card with a valid checksum. Request body (JSON): - `record_type` (string, required): Always `recurring_charge`. - `transaction_id` (string, required): The Bayarcash transaction ID. `GET /v3/transactions/{transaction_id}` accepts it. - `exchange_reference_number` (string, optional): The `BPGR-` reference of the payment exchange for the charge. - `exchange_transaction_id` (string, optional): The charge ID of the provider. `GET /v3/payments/{paymentId}` accepts it. - `order_number` (string, required): Your `reference`. For an on-demand charge, the reference of `POST /v3/payments`. For a scheduled charge, the reference of the agreement. - `charge_source` (string, required, one of: subscription, installment, on_demand): `subscription`, `installment` or `on_demand`. - `subscription_id` (string, optional): Only when `charge_source` is `subscription`. - `installment_id` (string, optional): Only when `charge_source` is `installment`. - `customer_id` (string, optional): The recurring customer. An on-demand charge has a customer, but no agreement. - `currency` (string, optional): The ISO 4217 currency code. - `amount` (string, required): The amount, as a decimal string. - `payer_name` (string, optional): The name of the payer. - `payer_email` (string, optional): The email address of the payer. - `payer_telephone_number` (string, optional): The phone number of the payer. The checksum does not sign it. - `payer_bank_name` (string, optional): Always null on a recurring charge, so it is not in the body. - `status` (integer, required, one of: 1, 2, 3): `1` pending, `2` failed, `3` successful. - `status_description` (string, optional): The status as text. - `datetime` (string, optional): Kuala Lumpur time as `Y-m-d H:i:s`, with no offset. - `payment_gateway_id` (string, optional): The checksum does not sign it. - `card_brand` (string, optional): The card scheme, as the provider gives it. Not in the body when the provider did not give it. - `card_country` (string, optional): The country of the card issuer (ISO 3166-1 alpha-2). - `card_last4` (string, optional): The last 4 digits of the card. Bayarcash never sends a token. - `card_exp_month` (string, optional): The expiry month of the card. - `card_exp_year` (string, optional): The expiry year of the card. - `checksum` (string, required): The HMAC-SHA256 of the data, made with your API Secret Key. Check it before you use the callback. Responses: - 200: Return a 2xx status to confirm. If Bayarcash gets a different status, it sends the callback again, up to 5 times.