Bridge Operations

Run safer Soledgic bridge smokes, trace webhook delivery, and clean sandbox data without touching live ledgers.

Smoke Run Shape

A truthful bridge smoke creates real sandbox resources, completes or fails them through Soledgic sandbox controls, waits for signed webhooks, and verifies the customer app moved to the expected state.

create participant and wallets
  -> create checkout session
  -> complete or fail sandbox checkout
  -> receive signed webhook
  -> reconcile local order/payment state
  -> inspect webhook deliveries by checkout, order, or payment ID
  -> cleanup only this smoke run

Trace Fields

Store the same identifiers in your app records, Soledgic metadata, and support logs. That keeps one failed order searchable across both systems.

Field	Use
`source`	Stable app or smoke suite name, such as bridge_smoke
`run_id`	One disposable test run boundary for cleanup and debugging
`checkout_id`	Hosted checkout session created by Soledgic
`external_order_id`	Customer app order, request, booking, or purchase ID
`payment_id`	Payment or sale reference used for funding and refund checks
`delivery_id`	Webhook delivery ID used for replay, retry, and support escalation

Sandbox Scenarios

Use sandbox checkout completion for the happy path. Use canned scenarios for failure and operational paths that are hard to trigger through a hosted checkout page.

const completed = await soledgic.sandbox.completeCheckout({
  checkoutSessionId: checkout.checkoutSession.id,
  idempotencyKey: 'sandbox_complete_order_1001',
});

await soledgic.sandbox.sendScenario({
  scenario: 'dispute.created',
  idempotencyKey: 'sandbox_dispute_order_1001',
  source: 'bridge_smoke',
  runId: 'run_2026_05_13_001',
  checkoutId: checkout.checkoutSession.id,
  orderId: 'order_1001',
  paymentId: completed.checkoutSession.paymentId || 'pay_test_123',
  amountCents: 2999,
  reason: 'customer_dispute',
});

Supported canned scenarios include checkout.failed, refund.created, sale.refunded, payout.failed, dispute.created, chargeback events, and hold events.

Delivery Debugging

Filter webhook deliveries by the identifiers already stored on the order. Replay a specific delivery only after the receiving endpoint is idempotent for duplicate event IDs.

const deliveries = await soledgic.webhooks.listDeliveries({
  eventType: 'checkout.completed',
  checkoutId: 'chk_test_123',
  orderId: 'order_1001',
  paymentId: 'pay_test_123',
  status: 'failed',
  limit: 25,
});

const replayed = await soledgic.webhooks.replayDelivery(deliveries.data[0].id);

Operators can also inspect deliveries in Developers / Webhooks, including endpoint filters, response status, payload, replay, retry, and secret rotation.

Cleanup

Prefer run-scoped cleanup for CI and customer smoke tests. Full sandbox ledger cleanup is for resetting a test ledger while preserving webhook endpoint configuration.

const preview = await soledgic.sandbox.cleanup({
  scope: 'run',
  source: 'bridge_smoke',
  runId: 'run_2026_05_13_001',
});

const cleanup = await soledgic.sandbox.cleanup({
  scope: 'run',
  source: 'bridge_smoke',
  runId: 'run_2026_05_13_001',
  confirm: true,
});

Go-Live Checklist

Use separate test and live API keys, webhook secrets, endpoint URLs, and environment variables.
Reject live webhooks in test environments and reject sandbox webhooks in live environments.
Persist Soledgic checkout, payment, refund, payout, and delivery IDs before marking local state complete.
Make webhook handlers idempotent by event or delivery ID before enabling replay.
Run refund, payout failure, dispute, chargeback, and hold scenarios before production traffic.
Document the rollback path: disable endpoint, rotate secret, pause checkout creation, and reconcile open orders.