Sign in

v1

latestOpenAPI 3.0.12026-07-24204977.5 KB
Pre-Auth

Immediate tokenized payment charge (auth + capture)

Charges the user's linked payment method in a single step without a pre-authorization hold. Use this for one-shot payments where you do not need to adjust the amount before capture.

post/tokenized-payment/v1/charge

Headers

X-ShopBack-Idempotent-Idstring required

Unique key to safely retry the request without duplicate charges. Use a UUID per logical charge attempt.

Request body

paymentTokenstring required

Payment token from POST /token. Resolves the user and their default card.

merchantUserIdstring required

Merchant's opaque identifier for the end user. Must match the merchantUserId used when the paymentToken was issued.

amountnumber required

Charge amount. Must be > 0.

currencystring required

3-letter ISO currency code. Must match the merchant channel country currency.

merchantRefstring required

Merchant's reference ID. Used for idempotent duplicate detection.

useCashbackboolean

Whether to apply available cashback to this charge.

callbackUrlstring

HTTPS URL to receive order status webhook notifications. When provided, ShopBack will POST the order outcome to this URL upon payment completion or failure. Must use HTTPS with a valid public domain.

Example request

{
  "paymentToken": "aBcD1234eFgH5678iJkL9012mNoP3456",
  "merchantUserId": "merchant_rider_42",
  "amount": 17,
  "currency": "SGD",
  "merchantRef": "trip-456-tip",
  "useCashback": true,
  "callbackUrl": "https://merchant.example.com/webhooks/shopback"
}

Response

uuidstring required

Charge UUID.

orderUuidstring required

UUID of the settled order created by this charge.

statusstring required

Order status after charge.

orderTypestring required

Order type.

merchantRefstring required

Merchant's reference ID supplied at charge creation.

merchantOrderIdstring required

Merchant's order ID.

consumerEmailstring required

Consumer's email address.

failureReasonstring nullable required

Failure reason if the charge failed; null on success.

createdAtstring required

ISO 8601 creation timestamp.

Example response

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "orderUuid": "7b3f1234-ab12-4321-b123-000000000001",
  "status": "APPROVED",
  "orderType": "ONLINE",
  "merchantRef": "trip-456-tip",
  "merchantOrderId": "order-789",
  "consumerEmail": "user@example.com",
  "createdAt": "2026-04-30T10:00:00.000Z"
}