---
title: "Create a pre-authorization"
method: POST
path: "/tokenized-payment/v1/pre-auths"
tags: ["Pre-Auth"]
---

# Create a pre-authorization

`POST /tokenized-payment/v1/pre-auths`

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

## Headers

- `X-ShopBack-Idempotent-Id` string, required

## Request body

- CreatePreAuthRequestDto
  - `paymentToken` string, required — Payment token from POST /token. Resolves the user and their default card.
  - `merchantUserId` string, required — Merchant's opaque identifier for the end user (e.g. user ID). Used to verify the payment token belongs to this user.
  - `amount` number, required — Hold amount. Must be > 0. Also the capture amount.
  - `currency` string, required — 3-letter ISO currency code. Must match the merchant channel country currency.
  - `merchantRef` string, required — Merchant's reference ID (e.g. trip ID). Used for idempotent duplicate detection.
  - `merchantMetadata` object — Opaque JSON blob stored verbatim and returned on read endpoints. Max 5 keys; each string value must not exceed 200 characters.

## Response `201`

- PreAuthResponseDto
  - `id` string, required — Pre-authorization UUID.
  - `merchantRef` string, required — Merchant's reference ID supplied at creation.
  - `status` 'PENDING' | 'AUTHORIZED' | 'CAPTURE_INITIATED' | 'CAPTURED' | 'VOIDED' | 'DECLINED' | 'EXPIRED', required — Lifecycle state of the pre-authorization.
  - `amount` number, required — Hold amount in major currency units.
  - `currency` string, required — 3-letter ISO currency code.
  - `orderUuid` string, nullable, required — UUID of the settled order. Non-null after capture.
  - `orderStatus` string, nullable, required — Status of the settled order. Non-null after capture.
  - `failureReason` string, nullable, required — Failure reason if the pre-auth was declined or expired.
  - `merchantMetadata` object, nullable, required — Merchant-supplied metadata stored verbatim at creation.
  - `createdAt` string, required — ISO 8601 creation timestamp.
  - `updatedAt` string, required — ISO 8601 last-updated timestamp.

## Other responses

- `400` — One or more required fields are missing, the amount must be greater than zero, or the currency is invalid.
- `401` — The payment token was not found, has been unlinked, or belongs to a different merchant.

---

[API](https://skmtc.net/shopback/apis/online-payments-api.md) · [All operations](https://skmtc.net/shopback/apis/online-payments-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shopback/online-payments-api/revisions/160fc287769e/schema)