Sign in

v1

latestOpenAPI 3.0.12026-07-24204977.5 KB
Pre-Auth

Create a pre-authorization

Places a hold on the funds associated with a payment token. Use capture to settle or void to release the hold.

post/tokenized-payment/v1/pre-auths

Headers

X-ShopBack-Idempotent-Idstring required

Unique key to safely retry the request without duplicate holds. Use a UUID per logical pre-auth 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 (e.g. user ID). Used to verify the payment token belongs to this user.

amountnumber required

Hold amount. Must be > 0. Also the capture amount.

currencystring required

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

merchantRefstring required

Merchant's reference ID (e.g. trip ID). Used for idempotent duplicate detection.

merchantMetadataobject

Opaque JSON blob stored verbatim and returned on read endpoints. Max 5 keys; each string value must not exceed 200 characters.

Example request

{
  "paymentToken": "aBcD1234eFgH5678iJkL9012mNoP3456",
  "merchantUserId": "merchant_rider_42",
  "amount": 20.5,
  "currency": "SGD",
  "merchantRef": "trip-456",
  "merchantMetadata": {
    "tripId": "trip-456",
    "estimatedMinutes": 30
  }
}

Response

idstring required

Pre-authorization UUID.

merchantRefstring required

Merchant's reference ID supplied at creation.

status'PENDING' | 'AUTHORIZED' | 'CAPTURE_INITIATED' | 'CAPTURED' | 'VOIDED' | 'DECLINED' | 'EXPIRED' required

Lifecycle state of the pre-authorization.

amountnumber required

Hold amount in major currency units.

currencystring required

3-letter ISO currency code.

orderUuidstring nullable required

UUID of the settled order. Non-null after capture.

orderStatusstring nullable required

Status of the settled order. Non-null after capture.

failureReasonstring nullable required

Failure reason if the pre-auth was declined or expired.

merchantMetadataobject nullable required

Merchant-supplied metadata stored verbatim at creation.

createdAtstring required

ISO 8601 creation timestamp.

updatedAtstring required

ISO 8601 last-updated timestamp.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "merchantRef": "trip-456",
  "status": "AUTHORIZED",
  "amount": 20.5,
  "currency": "SGD",
  "orderUuid": "7b3f1234-ab12-4321-b123-000000000001",
  "orderStatus": "COMPLETED",
  "merchantMetadata": {
    "tripId": "trip-456"
  },
  "createdAt": "2026-04-30T10:00:00.000Z",
  "updatedAt": "2026-04-30T10:05:00.000Z"
}