Developers

One encrypted call to create a payment, one webhook when the bank confirms it. Everything below is also in a single file for your AI.

Quickstart

  1. Get your keysCreate a merchant on dash.baray.io and generate an API key, sk and iv under Developers.
  2. Create a paymentEncrypt the amount and your order number, POST it, send the customer to the link you get back.
  3. Handle the webhookMark the order paid when Baray tells you the bank has confirmed it.

Create a payment

POST https://api.baray.io/pay with your API key in x-api-key and the payment AES-256 encrypted in data. Send the same order_id again and you get the same payment back, never a second one.

FieldWhat it is
amount requiredA decimal string: "12.50" in USD, "50000" in KHR.
currency requiredUSD or KHR.
order_id requiredYour order number. Sending it again returns the same payment, never a second one.
intent_lifetime optionalMinutes the checkout link stays usable.
payment_lifetime optionalMinutes each bank QR or deeplink stays valid.
tracking optionalYour own key–value tags, searchable in the dashboard.
custom_success_url optionalWhere the customer lands after paying.
const crypto = require('crypto');
// Your credentials from dash.baray.io
const API_KEY = 'bry_live_xxxxxxxxxxxx';
const SK = 'Base64EncodedSecretKey32Bytes...';
const IV = 'Base64EncodedIV16Bytes...';
// Encrypt payload for API request
function encrypt(payload) {
const key = Buffer.from(SK, 'base64');
const ivBuffer = Buffer.from(IV, 'base64');
const cipher = crypto.createCipheriv('aes-256-cbc', key, ivBuffer);
let encrypted = cipher.update(JSON.stringify(payload), 'utf8');
encrypted = Buffer.concat([encrypted, cipher.final()]);
return encrypted.toString('base64');
}
// Decrypt webhook response
function decrypt(encryptedData) {
const key = Buffer.from(SK, 'base64');
const ivBuffer = Buffer.from(IV, 'base64');
const decipher = crypto.createDecipheriv('aes-256-cbc', key, ivBuffer);
let decrypted = decipher.update(Buffer.from(encryptedData, 'base64'));
decrypted = Buffer.concat([decrypted, decipher.final()]);
return decrypted.toString('utf8');
}
// Create payment intent
const payload = { amount: '10.00', currency: 'USD', order_id: 'ORDER-12345' };
const response = await fetch('https://api.baray.io/pay', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'x-api-key': API_KEY },
body: JSON.stringify({ data: encrypt(payload) })
});
const { _id: intentId } = await response.json();
redirect(`https://pay.baray.io/${intentId}`);
// Handle webhook
app.post('/webhook/baray', (req, res) => {
const orderId = decrypt(req.body.encrypted_order_id);
// Update order status
res.status(200).send('OK');
});

Webhooks

Once the bank has confirmed a payment, Baray posts to your webhook URL. Decrypt encrypted_order_id with your sk and iv to find the order.

POST https://your-site.com/webhooks/baray

{ "encrypted_order_id": "…", "bank": "ABA", "payment_option": "khqr" }

If we have issued you a webhook signing secret, each delivery also carries X-Baray-Signature, X-Baray-Timestamp and X-Baray-Event-Id: check the signature so a replayed webhook is refused. Failed deliveries are retried. Every attempt is listed under Health in the dashboard, where you can resend one.

Errors

Match on type, never on the message.

invalid_api_key400The x-api-key header is missing or unknown.
invalid_encryption400data could not be decrypted with this key.
invalid_amount400The amount is not a valid number for its currency.
amount_below_minimum400Below the smallest amount the banks accept.
intent_expired422The checkout link has passed its lifetime.
payment_held409The customer is already paying this in another window.
rate_limited429Too many requests. Retry after the Retry-After header.
bank_unavailable503That bank is switched off for maintenance. Offer another.

Test mode

Development keys use simulated banks: no bank is contacted and no money moves. Pick the outcome on the checkout and your webhook fires as it would live.

Bank status

A bank that's down or under maintenance comes off checkout automatically. Starting a payment on it returns bank_unavailable.