Key Concepts

Reference material that applies across all tokenized payment flows.

Idempotency

All write endpoints that create or modify payment state require an idempotency key in the X-ShopBack-Idempotent-Id header.

X-ShopBack-Idempotent-Id: 8a3f9c21-4b17-4e2d-9a31-dc702f81e934

Rules:

• Use a UUID generated fresh for each logical operation attempt.
• If a request times out or returns a 5xx, retry with the same X-ShopBack-Idempotent-Id. ShopBack will return the original result without creating a duplicate.
• If you intentionally want a new pre-auth or charge (e.g. a retry after a decline), generate a new X-ShopBack-Idempotent-Id.

Endpoints that require this header:

⚠️

Don't reuse keys across different logical operations

A key collision between two different intended operations returns the first result, silently. Use a UUID library to generate keys — don't construct them manually.

Payment token lifecycle

A token does not expire on a fixed date under normal circumstances. Treat it as valid until you receive a payment-token.invalid error, at which point prompt the user to relink.

Cashback

ShopBack users accumulate cashback that can be applied as a discount on payments. By default (useCashback: true), ShopBack applies available cashback balance to reduce the net charge amount.

To check available balance before charging:

POST /tokenized-payment/v1/tokens/cashback-balance
Authorization: Bearer <merchant_jwt>
Content-Type: application/json

{
  "paymentToken": "pt_sg_7829_a1b2c3d4e5f6..."
}

Response

{
  "cashbackBalance": 5.00,
  "currency": "SGD"
}

To disable cashback for a specific charge: set "useCashback": false in the pre-auth capture or immediate charge request.

Webhooks

ShopBack delivers an asynchronous order outcome notification to your callbackUrl after a capture or immediate charge completes PSP processing.

Webhook payload

{
  "order_uuid": "61cf9737-5cc3-421a-84c1-ba554c0674ba",
  "order_status": "SUCCESS",
  "order_context_token": "c9393a19-00b0-48cd-9a9e-fdcf0b3cdbb5",
  "cart_id": null,
  "webhook_url": "https://your-app.com/shopback/webhook"
}

Implementation checklist:

• Respond with HTTP 200 as fast as possible. Do your processing asynchronously.
• Verify order_uuid matches a known order in your system before acting on it.
• Handle duplicate deliveries idempotently — the same webhook may be delivered more than once.
• Do not block payment confirmation to your user on webhook delivery. Use the synchronous API response as the source of truth.

Error codes

All error responses follow this shape:

{
  "statusCode": 401,
  "error": "payment-token.invalid",
  "message": "Payment token not found or belongs to a different merchant"
}

Common error codes

Retry strategy

API reference