Confirm payments and fulfill once per order
Record payment completion separately from fulfillment. Authenticate order access, then retrieve the locally associated Checkout using your merchant key. Browser-provided status, return URLs and arbitrary Checkout IDs do not authorize delivery.
Server-side confirmation
- Load the durable order, payment attempt, expected amount/currency and associated Checkout ID.
- Retrieve Checkout and verify bindings and values.
- Wait for payment in
openand confirmation inprocessingwithout prompting another payment; handlefailed, and treat request failure as an unknown outcome. - For
succeeded, inspect exceptions and apply business policy. - Commit payment facts and one fulfillment task in an order-level transaction.
Multiple Checkouts may belong to one order. Deduplication by Checkout or event ID alone is insufficient: two successful attempts must not deliver the same order twice. Handle extra funds separately.
Reusable Node client
Download the request and confirmation helper as merchant-client.mjs. It uses Node.js 20+ fetch without dependencies, with HTTPS origins, Bearer authentication, encoded IDs and saved idempotency keys. It does not automatically replay writes.
This complete host-callable function requires an authorized durable savedOrder record and server environment API_BASE/API_KEY. It retrieves status without delivering goods and does not implement a database or queue. Its 15-second query timeout is an adjustable application budget, not a platform limit.
import {createMerchantClient, fulfillmentDecision} from './merchant-client.mjs';
// Node.js 20+. Run inside an authenticated server-side order worker.
// Load these values from trusted durable order/attempt storage.
export async function inspectOrder(savedOrder) {
const client = createMerchantClient({
baseUrl: process.env.API_BASE,
apiKey: process.env.API_KEY,
transport: (url, options) => fetch(url, {
...options, signal: AbortSignal.timeout(15_000),
}),
});
const checkout = await client.retrieveCheckout(savedOrder.checkoutId);
return fulfillmentDecision(checkout, {
checkoutId: savedOrder.checkoutId,
orderId: savedOrder.orderId,
amount: savedOrder.amount,
currency: savedOrder.currency,
});
}
fulfillmentDecision compares up to eight decimal places exactly and verifies Checkout/order/currency bindings. Its conservative example policy sends every fund exception to review. Decide independently whether to fulfill the original normal payment during paidOver; this sample policy is not a platform-mandated refund or state change.
Turn a decision into one delivery
This is transaction pseudocode, not executable database code:
begin database transaction
lock business order
verify checkout-to-order binding and expected amount/currency
if order already fulfilled: commit and return original result
if verified decision != fulfill: record review/wait outcome and commit
else: record payment fact + unique fulfillment outbox entry for this order
commit
worker delivers the unique outbox operation; retries reuse its business identifier
Use a retryable idempotent business identifier for shipping, entitlement or content delivery. Setting fulfilled=true after delivery alone leaves a duplicate window when delivery succeeds but the write fails. Use a transactional outbox or idempotent delivery service.
Query recovery
Schedule server queries with bounded frequency, backoff, timeouts and concurrency. Browsers read your own order outcome. Reconcile unresolved orders through the list operation; retain unknown state instead of creating another payment.
Enabled Webhooks can reduce detection delay, but signature/event deduplication does not replace resource retrieval and order-level idempotency. Keep the same query recovery when notification is unavailable or missed.
Offline practice
Download the local demo beside the helper and run node local-demo.mjs. It uses in-memory responses without service access or real keys, showing open → fulfill and an amount mismatch returning review. No goods are delivered.