SureLink Open Platform

Idempotency & Best Practices ​

In payment and crypto clearing systems, network timeouts, automatic retries, and concurrent requests are inevitable. To safeguard funds and prevent double-spending or dropped orders, the SureLink Gateway provides robust idempotency controls and dual verification patterns.

1. Idempotency (Idempotency-Key) ​

1.1 What is Idempotency? ​

An idempotent operation guarantees that: making multiple identical requests with the same idempotency key produces the exact same outcome as a single request, preventing accidental duplicate operations.

1.2 How SureLink Enforces Idempotency ​

All mutating endpoints (POST /api/v1/orders, POST /api/v1/withdrawals, POST /api/v1/crypto-deposit-orders) support the Idempotency-Key header:

  1. Unique Key Generation: Generate a unique UUID v4 (e.g., a9b2c3d4-e5f6-7890-1234-567890abcdef) for each client-side business action.
  2. Automatic Fallback: If Idempotency-Key is omitted from the request headers, the gateway automatically falls back to using merchantOrderNo.
  3. Atomic Execution & Caching: The gateway acquires a distributed Redis lock on the key. Once processed, the successful HTTP response is cached. Replays with the identical idempotency key immediately return the stored response without executing database mutations again.

Retry Pattern

Whenever a client experiences a network glitch (e.g., HTTP 504, connection reset), retry the request using the exact same Idempotency-Key and request payload.

2. Dual Verification (Webhooks + Polling) ​

While Webhooks are highly reliable, transient network partitions can delay delivery. We recommend implementing a "Webhook-first, Polling-fallback" pattern:

mermaid
flowchart TD
    Create["1. Create Order via API"] --> Wait["2. Listen for Webhook Event"]
    Wait -->|Webhook Received & Signature Verified| Update["3. Mark Local Order as COMPLETED"]
    Wait -->|Timeout without Webhook| Poll["4. Query GET /api/v1/orders/:orderNo"]
    Poll --> Check{"5. Gateway Order Status?"}
    Check -->|Completed| Update
    Check -->|Pending / Processing| Delay["Wait 30s & Poll Again"] --> Poll
    Check -->|Cancelled / Expired| Fail["Mark Local Order as CANCELLED"]
  • First 15 minutes: Poll every 15–30 seconds while the buyer is interacting with the checkout portal.
  • 15 to 30 minutes: Poll every 1–2 minutes.
  • Over 30 minutes: If still unresolved after expiry, mark for automated reconciliation or customer support review.

3. Financial Security Safeguards ​

  1. Database Row Locks & Optimistic Locking:
    • When receiving an order.completed callback, update your internal ledger using WHERE status = 'PENDING'. Avoid unconditional status overwrites to prevent race conditions.
  2. Secure Credential Storage:
    • Never embed your API Secret in client-side code, mobile apps, or frontend bundles. All signing must occur on secure, backend servers.
    • Payout recipient bank account information constitutes sensitive PII. The gateway encrypts it using AES-256-GCM at rest and masks it in all logs and lists.
  3. Daily Reconciliation:
    • Implement an automated T+1 reconciliation job (e.g., at 02:00 UTC) comparing daily settled orders against internal financial ledger entries.