Testing

Test your BSync integration in the sandbox before going live. Use test API keys and the official tooling.

OpenAPI: /docs/api-reference
Postman: BSync-Server/postman/

Sandbox

The sandbox uses bsync_test_* API keys against the same API host (https://api.bsyncapp.com). No real money moves in test mode.

Create a test key in the Dashboard → Settings → API Keys. Select the test environment.

const bsync = new BSync({
  apiKey: "bsync_test_xxxxxxxx",
});

Test API Keys

Never use live keys in development or CI.

Test Payments

SDK

const payment = await bsync.paymentIntents.create({
  amount: 10,
  currency: "EGP",
  externalOrderId: "TEST-001",
  redirectDelay: 3,
});
 
console.log(payment.checkoutUrl);

Open checkoutUrl in a browser to walk through the hosted checkout flow.

Postman

1. Import BSync Public API.postman_collection.json and BSync Test.postman_environment.json.
2. Set apiKey to your test key.
3. Run Examples → 1. Create a payment intent.
4. Run Examples → 2–4 — variables chain automatically.

See Postman Example.

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: test-$(date +%s)" \
  -d '{"amount": 10, "currency": "EGP", "redirectDelay": 3}'

Review Required Simulation

Some test payments trigger manual review (amount mismatch, duplicate detection). When this happens:

• matchStatus becomes review_required
• verificationStatus becomes manual_review
• Webhook: PAYMENT_REVIEW_REQUIRED

Handle this in your integration:

const status = await bsync.paymentIntents.getStatus(paymentId);
if (status.matchStatus === "review_required") {
  console.log("Payment under review — wait for approval webhook");
}

Webhook Testing

Local receiver

Run the webhook example locally:

cd packages/bsync-node-sdk
BSYNC_WEBHOOK_SECRET=whsec_test npx tsx examples/webhook-verification.ts

Expose via ngrok or similar:

ngrok http 4000

Set the ngrok URL as your webhook endpoint in the Dashboard.

Postman

Set webhookUrl in the Test environment, then send sample payloads from the Webhooks folder in the Postman collection. Each request includes a valid X-BSYNC-SIGNATURE header.

Manual signature test

import { verifySignature } from "@bsync/node-sdk";
import { createHmac } from "node:crypto";
 
const payload = JSON.stringify({ eventId: "evt_test", eventType: "PAYMENT_PAID", data: {} });
const secret = "whsec_test";
const signature = createHmac("sha256", secret).update(payload).digest("hex");
 
console.log(verifySignature({ payload, signature, secret })); // true

Failure Simulation

Test error handling by triggering known error conditions:

SDK error class mapping is tested in packages/bsync-node-sdk/tests/client.test.ts.

Local Development

Run the BSync API server locally:

cd BSync-Server
npm install
npm run dev

Point the SDK at localhost:

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

Interactive docs: http://localhost:3000/docs

Checklist Before Going Live

• Created and tested with bsync_test_* key
• Webhook endpoint receives and verifies events
• Error handling covers 401, 404, 409, 422, 429, 500
• Idempotency keys prevent duplicate payments
• getStatus() called before order fulfillment
• Review-required state handled gracefully

See Going Live for the full production checklist.

Related

• Quick Start
• Webhooks
• Error Handling
• Examples