Quick Start

Get a BSync payment integration running in under 5 minutes.

OpenAPI: /docs/api-reference
SDK: @bsync/node-sdk

Flow

flowchart TD
    createKey[1_Create_API_Key] --> installSdk[2_Install_SDK]
    installSdk --> initClient[3_Initialize_Client]
    initClient --> createPayment[4_Create_Payment_Intent]
    createPayment --> redirectUser[5_Redirect_to_checkoutUrl]
    redirectUser --> receiveWebhook[6_Receive_Webhook]
    receiveWebhook --> verifyPayment[7_Verify_Payment]

Step 1: Create an API Key

Log in to the BSync Dashboard.
Go to Settings → API Keys.
Create a new key. Use a bsync_test_* key for sandbox testing.
Copy the key — it is shown only once.

There is no token issuance endpoint. Keys are created in the Dashboard only.

Step 2: Install the SDK

npm install @bsync/node-sdk

Requires Node.js 18+ (native fetch).

Step 3: Initialize the Client

import { BSync } from "@bsync/node-sdk";
 
const bsync = new BSync({
  apiKey: process.env.BSYNC_API_KEY,
});

For local development:

const bsync = new BSync({
  apiKey: process.env.BSYNC_API_KEY,
  baseUrl: "http://localhost:3000",
});

Step 4: Create a Payment

const payment = await bsync.paymentIntents.create({
  amount: 150,
  currency: "EGP",
  externalOrderId: "ORD-1001",
  customerPhone: "+201012345678",
  successUrl: "https://merchant.example/success",
  cancelUrl: "https://merchant.example/cancel",
  redirectDelay: 3,
});
 
console.log(payment.paymentId);
console.log(payment.checkoutUrl);

Equivalent curl:

curl -X POST https://api.bsyncapp.com/v1/payment-intents \
  -H "Authorization: Bearer bsync_test_your_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": 150,
    "currency": "EGP",
    "externalOrderId": "ORD-1001",
    "redirectDelay": 3
  }'

Response shape (see OpenAPI PaymentIntent schema):

{
  "success": true,
  "data": {
    "paymentId": "pay_abc123",
    "status": "pending",
    "checkoutUrl": "https://bsyncapp.com/checkout/token_xyz",
    "amount": 150,
    "currency": "EGP",
    "expiresAt": "2026-07-14T19:00:00.000Z",
    "createdAt": "2026-07-14T18:30:00.000Z"
  }
}

Step 5: Redirect the User

Send the customer to payment.checkoutUrl. BSync hosts the checkout page — you do not build a payment UI.

res.redirect(payment.checkoutUrl);

The customer selects a provider, enters their sender phone, and completes payment on the hosted page.

Step 6: Receive a Webhook

Configure your webhook endpoint in the Dashboard. BSync delivers events to your server:

POST https://merchant.example/webhooks/bsync
X-BSYNC-EVENT: PAYMENT_PAID
X-BSYNC-SIGNATURE: a1b2c3d4...
Content-Type: application/json

{
  "eventId": "evt_abc123",
  "eventType": "PAYMENT_PAID",
  "createdAt": "2026-07-14T18:35:00.000Z",
  "data": {
    "paymentId": "pay_abc123",
    "amount": 150
  }
}

Step 7: Verify Payment

Always verify webhook signatures and confirm status server-side:

import { verifySignature } from "@bsync/node-sdk";
 
const isValid = verifySignature({
  payload: rawBody,
  signature: req.headers["x-bsync-signature"],
  secret: process.env.BSYNC_WEBHOOK_SECRET,
});
 
if (isValid) {
  const status = await bsync.paymentIntents.getStatus(paymentId);
  if (status.status === "paid") {
    // Fulfill the order
  }
}

Next Steps

Authentication — key management and security
Payment Intents — full create/status/cancel reference
Webhooks — all events, retries, duplicate protection
Going Live — production checklist
Examples — Express, Next.js, webhook receiver samples

Production Tip

Never trust the frontend to confirm payment. Always verify via webhook + server-side getStatus() before fulfilling orders.

Was this page helpful?

Authentication