Reconcile ramp orders
Join your order model to 0Gate sessions, transaction references, and signed webhook events.
Reconciliation turns hosted 0Gate activity into your durable order or ledger state. Your system should be able to answer: which user action created the session, which webhook events arrived, which event was processed, which transaction ref was produced, and what state your own ledger currently shows.
Recommended data model
| Field | Owner | Notes |
|---|---|---|
order_id or intent_id | Your app | Primary business record. |
gate_session_id | 0Gate | Stored when session creation succeeds. |
gate_client_secret_hash | Your app if needed | Avoid storing raw client_secret broadly. |
user_reference | Your app and 0Gate | Opaque correlation id echoed in events. |
event_id | 0Gate webhook | Unique dedupe key. |
event_type | 0Gate webhook | Drives state transition logic. |
transaction_ref | 0Gate | Present when available for completed flows. |
local_rail_transaction_id | 0Gate transaction or receipt record | Rail-side transaction id for local payment or payout flows. Prefer this over deprecated rail-specific aliases. |
last_request_id | 0Gate API response | Useful for debugging. |
Reconciliation flow
Idempotent handler sketch
async function handleGateEvent(event: GateEvent) {
const existing = await db.gateEvents.findById(event.id);
if (existing) return { status: 'duplicate' };
await db.transaction(async tx => {
const order = await tx.orders.findByGateSession(event.data.id);
if (!order) throw new Error('Unknown 0Gate session');
await tx.gateEvents.insert({
id: event.id,
type: event.type,
gateSessionId: event.data.id,
createdAt: event.created_at,
});
if (event.type === 'gate_session.completed') {
await tx.orders.markCompleted(order.id);
}
});
}Use this as a shape, not a drop-in library. Your production implementation should include raw-body verification, exact event typings, error handling, observability, and retry-safe database writes.
Reconciliation rules
- Deduplicate every event id before side effects.
- Make fulfillment idempotent by order id, not only event id.
- Keep browser callbacks out of the durable ledger path.
- Keep raw webhook body available only where needed for verification and audit.
- Treat missing orders as support events, not reasons to expose internal data.