Bayarcash Payment Gateway Rust SDK
An idiomatic, async Rust client for the Bayarcash Payment Gateway API — a feature-parity port of the official Bayarcash PHP SDK. It supports API v2 (default) and v3, and is byte-compatible with the gateway for checksum generation and callback verification.
Table of Contents
- Requirements
- Installation
- Getting Started
- Quick Start: Accept a Payment
- Payment Channels
- Creating a Payment Intent
- Handling Callbacks
- Payment & Transaction Status
- Transactions
- FPX Direct Debit
- Manual Bank Transfer
- Portals & FPX Banks
- Error Handling
- Response Objects
- Security Recommendations
Requirements
- Rust 1.75+ and an async runtime (examples use
tokio). - Two credentials from your Bayarcash console:
- API token — authenticates SDK requests.
- API secret key — signs request checksums and verifies callbacks.
Installation
# Cargo.toml
[]
= "0.1"
= { = "1", = ["full"] }
The crate uses reqwest with rustls (no system OpenSSL dependency).
Getting Started
use ;
let client = new
.use_sandbox // remove this in production
.set_api_version // 'V2' (default) or 'V3'
.set_timeout; // request timeout in seconds (default 30)
assert_eq!;
Configure the client (
use_sandbox()/set_api_version()) before making requests. Omituse_sandbox()in production to hit the live gateway.
Quick Start: Accept a Payment
A complete FPX payment flow, from creating the payment to redirecting the payer:
use ;
# async
After payment, Bayarcash calls your callback_url (server-to-server) and redirects the payer to your return_url. Verify both — see Handling Callbacks.
Payment Channels
Pass one of these constants (or a Vec<i32> of them) as the payment channel. They are available both as Bayarcash::FPX and in the [channels] module.
FPX // 1 — FPX Online Banking
MANUAL_TRANSFER // 2 — Manual Bank Transfer
FPX_DIRECT_DEBIT // 3 — FPX Direct Debit
FPX_LINE_OF_CREDIT // 4 — FPX Line of Credit
DUITNOW_DOBW // 5 — DuitNow Online Banking
DUITNOW_QR // 6 — DuitNow QR
SPAYLATER // 7 — ShopeePayLater
BOOST_PAYFLEX // 8 — Boost PayFlex
QRISOB // 9 — QRIS Online Banking
QRISWALLET // 10 — QRIS Wallet
NETS // 11 — NETS
CREDIT_CARD // 12 — Credit Card
ALIPAY // 13 — Alipay
WECHATPAY // 14 — WeChat Pay
PROMPTPAY // 15 — PromptPay
TOUCH_N_GO // 16 — Touch 'n Go eWallet
BOOST_WALLET // 17 — Boost Wallet
GRABPAY // 18 — GrabPay
GRABPL // 19 — Grab PayLater
SHOPEE_PAY // 21 — ShopeePay (note: there is no channel 20)
Select multiple channels by passing a vector:
# use ;
# let req = new
.payment_channel
# ;
Creating a Payment Intent
PaymentIntentRequest::new(portal_key, order_number, amount, payer_name, payer_email) takes the required fields; the rest are builder methods:
| Field | Required | Description |
|---|---|---|
portal_key |
✅ | Your portal key. |
order_number |
✅ | Your reference. Max 30 chars. |
amount |
✅ | String with up to 2 decimals, e.g. "10.00". |
payer_name |
✅ | Max 150 chars. |
payer_email |
✅ | Valid email, max 250 chars. |
.payment_channel(...) |
➖ | A channel id, or a Vec<i32> of ids. If omitted, the payer chooses. |
.payer_telephone_number(...) |
➖ | Required for e-wallet / DuitNow channels. |
.return_url(...) |
➖ | Browser redirect after payment. |
.callback_url(...) |
➖ | Server-to-server notification URL. |
.metadata(...) |
➖ | Extra data echoed back. |
.signed(secret) / .checksum(...) |
➖ | Recommended. See below. |
Checksum
The checksum protects the request from tampering. It is computed from payment_channel, order_number, amount, payer_name, and payer_email (HMAC-SHA256). Append it with .signed(secret), or compute it explicitly:
# use ;
# let client = new;
# let mut request = new;
let checksum = client.create_payment_intent_checksum_value;
request = request.checksum;
Handling Callbacks
Bayarcash sends notifications you must verify with your API secret key before trusting. Collect the form/query fields into any type implementing [CallbackData] — HashMap<String, String>, serde_json::Value, etc. — then call the matching verifier. Each returns true only when the checksum matches (constant-time comparison).
use Bayarcash;
use HashMap;
# let client = new;
# let callback_data: = new;
let secret = "YOUR_API_SECRET_KEY";
// Transaction callback (sent to your callback_url)
if client.verify_transaction_callback_data
// Payer redirect (sent to your return_url)
if client.verify_return_url_callback_data
// Pre-transaction callback
if client.verify_pre_transaction_callback_data
Mandate-specific verifiers: verify_direct_debit_bank_approval_callback_data, verify_direct_debit_authorization_callback_data (includes the application_type field), and verify_direct_debit_transaction_callback_data.
Payment & Transaction Status
Status is an integer code. Use the helpers instead of hardcoding numbers:
use Fpx;
STATUS_NEW; // 0
STATUS_PENDING; // 1
STATUS_FAILED; // 2
STATUS_SUCCESS; // 3
STATUS_CANCELLED; // 4
assert_eq!;
Transaction and mandate models expose .status_code() to parse the status string into an i32:
# use ;
# let transaction = default;
if transaction.status_code == Some
There are also [FpxDirectDebit] status/type helpers and [duitnow::Dobw] for DuitNow.
Transactions
# use ;
# async
The following query helpers require API v3 and return Err(Error::Unsupported(_)) on v2:
# use ;
# async
FPX Direct Debit
Constants live on the [FpxDirectDebit] type:
use FpxDirectDebit;
// Payer ID type
NRIC; // 1
OLD_IC; // 2
PASSPORT; // 3
BUSINESS_REGISTRATION; // 4
OTHERS; // 5
// Frequency mode
MODE_DAILY; // "DL"
MODE_WEEKLY; // "WK"
MODE_MONTHLY; // "MT"
MODE_YEARLY; // "YR"
1. Enrolment
use ;
# async
2. Maintenance
use ;
# async
3. Termination
use ;
# async
Retrieving mandates
# use Bayarcash;
# async
Manual Bank Transfer
Submit a manual (offline) bank transfer with proof of payment. payment_gateway must be 2 (Bayarcash::MANUAL_TRANSFER).
use ;
# async
The response is a [ManualBankTransferResponse] enum (HtmlForm, Json, Raw, or Redirect). Update the status of an existing transfer:
use ;
# async
Portals & FPX Banks
# use Bayarcash;
# async
Error Handling
Operations return Result<T, bayarcash::Error>. Match on the typed error:
use ;
# async
| Variant | HTTP | Meaning |
|---|---|---|
Error::Validation |
422 | Invalid data. Call .errors() for details. |
Error::FailedAction |
400 | Request failed. Carries the gateway message. |
Error::NotFound |
404 | Resource not found. |
Error::RateLimitExceeded |
429 | Rate limited. resets_at holds the reset time. |
Error::Api |
other | Any other non-2xx response (status + body). |
Error::Unsupported |
— | A v3-only method was called on v2. |
Error::InvalidArgument |
— | A required argument was missing or invalid. |
Response Objects
API methods return typed structs with Option fields; anything the gateway returns that is not modelled is preserved in each struct's extra: HashMap<String, serde_json::Value>. All models derive serde::Serialize, so serde_json::to_value(&model) is the equivalent of the PHP toArray().
PaymentIntent — url, id, status, amount, order_number, payer_name, payer_email, …
Transaction — id, status (+ .status_code()), status_description, amount, order_number, exchange_reference_number, payer_name, payer_email, …
Mandate, MandateApplication, Portal, FpxBank mirror their PHP resource counterparts.
Security Recommendations
- Always send a
checksumwith payment and mandate requests (.signed(secret)). - Verify every callback with the provided verification methods before acting on it.
- Store and check transaction ids to prevent duplicate processing.
- Use HTTPS for your
return_urlandcallback_url. - Keep your API token and secret key out of source control.
API Documentation
For full API details, see the Official Bayarcash API Documentation.
License
Open-sourced software licensed under the MIT license.