openapi: 3.0.1
info:
title: Online Payments API
version: '2.0'
servers:
- url: https://integrations-sandbox.shopback.com/demo/merchant
description: staging environment
tags:
- name: Pre-Auth
- name: Account Linking
- name: Orders
- name: Authentication
paths:
/tokenized-payment/v1/pre-auths/{id}/capture:
post:
operationId: capture-pre-auth
summary: Capture a pre-authorization
description: Executes the held funds for a pre-authorization and creates an order. The pre-auth
must be in AUTHORIZED status.
tags:
- Pre-Auth
security:
- bearer: []
parameters:
- name: id
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CapturePreAuthRequestDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CapturePreAuthResponseDto'
'401':
description: Missing or invalid merchant JWT.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'404':
description: Pre-authorization not found or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'409':
description: The pre-authorization has already been captured, voided, declined, or has expired.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/capture-pre-auth
/tokenized-payment/v1/pre-auths:
post:
operationId: create-pre-auth
summary: Create a pre-authorization
description: Places a hold on the funds associated with a payment token. Use capture to settle or
void to release the hold.
tags:
- Pre-Auth
security:
- bearer: []
parameters:
- name: X-ShopBack-Idempotent-Id
in: header
description: Unique key to safely retry the request without duplicate holds. Use a UUID per logical
pre-auth attempt.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePreAuthRequestDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PreAuthResponseDto'
'400':
description: One or more required fields are missing, the amount must be greater than zero,
or the currency is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'401':
description: The payment token was not found, has been unlinked, or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/create-pre-auth
/tokenized-payment/v1/tokens/cashback-balance:
post:
operationId: get-cashback-balance
summary: Get cashback balance for a payment token
description: Returns the user's available cashback balance for the merchant channel associated with
the payment token.
tags:
- Pre-Auth
security:
- bearer: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GetCashbackBalanceRequest'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetCashbackBalanceResponse'
'400':
description: The paymentToken field is required.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'401':
description: Missing or invalid merchant JWT, or the payment token was not found, has been unlinked,
or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/get-cashback-balance
/tokenized-payment/v1/link-sessions/link/{linkToken}:
get:
operationId: get-link-session
summary: Get link session status
description: Returns the current state of a tokenized payment link session. Poll this endpoint after
redirecting the user to determine when the consent flow is complete.
tags:
- Account Linking
security:
- bearer: []
parameters:
- name: linkToken
required: true
in: path
description: The link session UUID returned by `POST /link-sessions/link`.
example: 550e8400-e29b-41d4-a716-446655440000
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetLinkSessionResponse'
'401':
description: Missing or invalid merchant JWT.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'404':
description: Link session not found or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/get-link-session
/tokenized-payment/v1/pre-auths/{id}:
get:
operationId: get-pre-auth
summary: Get a pre-authorization by ID
description: Returns the current state of a pre-authorization. Use this to poll for status transitions
after create, capture, or void operations.
tags:
- Pre-Auth
security:
- bearer: []
parameters:
- name: id
required: true
in: path
description: Pre-authorization UUID returned by POST /pre-auths.
example: 550e8400-e29b-41d4-a716-446655440000
schema:
type: string
responses:
'200':
description: Pre-auth found and returned.
content:
application/json:
schema:
$ref: '#/components/schemas/PreAuthResponseDto'
'400':
description: The provided ID is not in a valid format.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'401':
description: Missing or invalid merchant JWT.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'404':
description: Pre-authorization not found or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/get-pre-auth
/order/{uuid}:
get:
tags:
- Orders
summary: Get order status
operationId: getOrderInfo
parameters:
- name: Authorization
in: header
description: Authorization
required: true
schema:
type: string
- name: uuid
in: path
description: order uuid
required: true
schema:
type: string
- name: X-ShopBack-Idempotent-Id
in: header
description: Idempotent Id for the request. If this is absent, every request will be treated
as unique and will be processed as such. (This is optional for now, but will be made required
in the future)
schema:
example: faa5e09a-8cf3-43f7-8309-d94deb426e66
type: string
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/MerchantOrderResponse'
'404':
description: Not Found, Merchant not found/Currency not found, No order found for provided uuid
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'412':
description: Precondition Failed, Provided token is invalid or expired
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error, Something went wrong on servers's end.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-source-doc: https://docs.shopback.com/reference/getorderinfo
/tokenized-payment/v1/charge:
post:
operationId: immediate-charge
summary: Immediate tokenized payment charge (auth + capture)
description: 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.
tags:
- Pre-Auth
security:
- bearer: []
parameters:
- name: X-ShopBack-Idempotent-Id
in: header
description: Unique key to safely retry the request without duplicate charges. Use a UUID per
logical charge attempt.
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ImmediateChargeRequestDto'
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ImmediateChargeResponseDto'
'400':
description: One or more required fields are missing, the amount must be greater than zero,
or the currency is invalid.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'401':
description: The payment token was not found, has been unlinked, or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/immediate-charge
/tokenized-payment/v1/link-sessions/link:
post:
operationId: initiate-link-session
summary: Initiate a tokenized payment link session
description: Creates a PENDING link session and returns a `redirectUrl` and `appToken`. The merchant
opens `redirectUrl` in an in-app browser and passes `appToken` as `X-ShopBack-App-Token`.
tags:
- Account Linking
security:
- bearer: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateLinkSessionRequest'
responses:
'200':
description: Link session created; merchant should redirect user to `redirectUrl`.
content:
application/json:
schema:
$ref: '#/components/schemas/InitiateLinkSessionResponse'
'400':
description: Invalid request body, malformed `callbackUrl`, `callbackUrl` not on the channel
allowlist, or `userHint` missing or contains no sub-fields.
'401':
description: Missing or invalid merchant JWT.
x-source-doc: https://docs.shopback.com/reference/initiate-link-session
/order/initiate:
post:
tags:
- Orders
summary: Create order
description: This is where you can initiate an order with ShopBack, by using the **initiateOrder**
method. We also provide a number of methods to refund orders. For example if the consumer returns
one (or all) item(s) of an order, you can initiate a full or partial refund. You would be asked
to send us the SKU number of the items to be refunded.
operationId: initiateOrder
parameters:
- name: Authorization
in: header
description: Authorization
required: true
schema:
type: string
- name: X-ShopBack-Idempotent-Id
in: header
description: Idempotent Id for the request. If this is absent, every request will be treated
as unique and will be processed as such. (This is optional for now, but will be made required
in the future)
schema:
example: faa5e09a-8cf3-43f7-8309-d94deb426e66
type: string
requestBody:
content:
'*/*':
schema:
$ref: '#/components/schemas/InitiateOnlineOrderRequest'
required: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/InitiatedOrderResponse'
'404':
description: Not Found, Merchant not found/Currency not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'412':
description: 'Precondition Failed.**Example of** possible error messages:
* Provided token is invalid or expired
* Order with requested external ids already exists
* Consumer country is not supported for this operation
* BillingAddress Country is not merchant supported
* There was an error with the scanned QR code. Please ensure that you have scanned the correct
QR code from our merchant partners.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error, Something went wrong on servers's end.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codegen-request-body-name: body
x-source-doc: https://docs.shopback.com/reference/initiateorder
/order/{orderUuid}/refund:
post:
tags:
- Orders
summary: Order refund
operationId: initiateOrderRefund
parameters:
- name: orderUuid
in: path
description: order uuid
required: true
schema:
type: string
- name: Authorization
in: header
description: Authorization
required: true
schema:
type: string
- name: X-ShopBack-Idempotent-Id
in: header
description: Idempotent Id for the request. If this is absent, every request will be treated
as unique and will be processed as such. (This is optional for now, but will be made required
in the future)
schema:
example: faa5e09a-8cf3-43f7-8309-d94deb426e66
type: string
requestBody:
content:
'*/*':
schema:
$ref: '#/components/schemas/PartialRefundRequestModel'
required: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/RRVResponseModel'
'404':
description: Not Found, Merchant not found/Currency not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'412':
description: 'Precondition Failed.**Example of possible error messages:**
* Provided token is invalid or expired
* Unable to Refund Order in status [INITIATED]
* This request has been accepted earlier, Unable to Refund Order in status [REFUNDED]
* You are not permitted to perform this operation.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: Internal Server Error, Something went wrong on servers's end.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
x-codegen-request-body-name: body
x-source-doc: https://docs.shopback.com/reference/initiateorderrefund
/auth/login:
post:
tags:
- Authentication
description: There is a clean Login and Logout process associated with the Authentication process.
Before you can Login, you need to obtain credentials from ShopBack - provided after registering
a set of valid merchant details.
parameters:
- name: X-ShopBack-Idempotent-Id
in: header
description: Idempotent Id for the request. If this is absent, every request will be treated
as unique and will be processed as such. (This is optional for now, but will be made required
in the future)
schema:
example: faa5e09a-8cf3-43f7-8309-d94deb426e66
type: string
summary: Login
operationId: login
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/LoginRequest'
required: false
responses:
'200':
description: successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/LoginResponse'
'201':
description: Created, Entity is created successfully
content: {}
'401':
description: Unauthorized Access, You are providing invalid credentials
content: {}
'412':
description: Precondition Failed, Username/Email is already exists
content: {}
'422':
description: Unprocessable Entity, Could not process the entity as it has invalid data
content: {}
'500':
description: Internal Server Error, Something went wrong on servers's end
content: {}
x-codegen-request-body-name: body
x-source-doc: https://docs.shopback.com/reference/login
/tokenized-payment/v1/link-sessions/token:
post:
operationId: swap-payment-token
summary: Exchange an auth code for a payment token
description: Validates the one-time auth code issued after the user completes the ShopBack consent
flow and returns a reusable payment token scoped to the merchant channel.
tags:
- Account Linking
security:
- bearer: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SwapPaymentTokenRequest'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SwapPaymentTokenResponse'
'400':
description: The auth code is missing, the link session is not ready to exchange a code, the
auth code has expired, or the auth code is incorrect.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'401':
description: Missing or invalid merchant JWT.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'404':
description: Link session not found or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/swap-payment-token
/tokenized-payment/v1/tokens/unlink:
post:
operationId: unlink-payment-token
summary: Revoke a linked payment token
description: Unlinks a payment token for the authenticated merchant channel. Returns 400 if an active
pre-auth (AUTHORIZED) is still open for the account.
tags:
- Account Linking
security:
- bearer: []
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UnlinkPaymentTokenRequest'
responses:
'200':
description: Payment token successfully unlinked.
content:
application/json:
schema:
$ref: '#/components/schemas/UnlinkPaymentTokenResponse'
'400':
description: paymentToken field is missing from the body, or an active pre-auth blocks the unlink.
'401':
description: Missing or invalid merchant JWT.
'404':
description: Payment token not found or already unlinked.
x-source-doc: https://docs.shopback.com/reference/unlink-payment-token
/tokenized-payment/v1/pre-auths/{id}/void:
post:
operationId: void-pre-auth
summary: Void a pre-authorization
description: Releases the held funds for a pre-authorization. The pre-auth must be in AUTHORIZED
status. If the provider rejects the void, the pre-auth stays AUTHORIZED and the merchant may retry.
tags:
- Pre-Auth
security:
- bearer: []
parameters:
- name: id
required: true
in: path
description: Pre-authorization UUID returned by POST /pre-auths.
example: 550e8400-e29b-41d4-a716-446655440000
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/VoidPreAuthRequest'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PreAuthResponseDto'
'401':
description: Missing or invalid merchant JWT.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'404':
description: Pre-authorization not found or belongs to a different merchant.
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
'409':
description: The pre-authorization is in a state that cannot be voided (already captured, voided,
declined, or expired).
content:
application/json:
schema:
$ref: '#/components/schemas/MgsExternalErrorResponseDto'
x-source-doc: https://docs.shopback.com/reference/void-pre-auth
components:
securitySchemes:
bearer:
type: http
scheme: bearer
bearerFormat: JWT
description: Merchant JWT obtained from POST /merchant-gateway/auth/login.
schemas:
MgsExternalErrorResponseDto:
required:
- statusCode
- errorMessages
- errorId
- name
- errorCode
- code
- helpUrl
type: object
properties:
statusCode:
type: number
example: 404
errorMessages:
example:
- Pre-auth not found
type: array
items:
type: string
errorId:
type: string
example: trace-id-abc123
name:
type: string
example: NOT_FOUND
errorCode:
type: string
example: NOT_FOUND
code:
type: string
example: pre-auth.not-found
helpUrl:
type: string
example: https://support.hoolah.co/error?code=pre-auth.not-found
CapturePreAuthRequestDto:
type: object
properties:
useCashback:
type: boolean
description: Whether to apply available cashback balance at capture. Defaults to true.
example: true
merchantMetadata:
type: object
description: Opaque JSON blob stored verbatim and returned on read endpoints. Max 5 keys; each
string value must not exceed 200 characters.
example:
tripId: trip-456
callbackUrl:
type: string
description: HTTPS URL to receive order status webhook notifications. When provided, ShopBack
will POST the order outcome to this URL upon capture.
example: https://merchant.example.com/webhooks/shopback
CapturePreAuthResponseDto:
required:
- uuid
- orderUuid
- status
- orderType
- merchantRef
- merchantOrderId
- consumerEmail
- createdAt
- failureReason
type: object
properties:
uuid:
type: string
description: Pre-authorization UUID.
example: 550e8400-e29b-41d4-a716-446655440000
orderUuid:
type: string
description: UUID of the settled order created by this capture.
example: 7b3f1234-ab12-4321-b123-000000000001
status:
type: string
description: Order status after capture.
example: APPROVED
orderType:
type: string
description: Order type.
example: ONLINE
merchantRef:
type: string
description: Merchant's reference ID supplied at pre-auth creation.
example: trip-456
merchantOrderId:
type: string
description: Merchant's order ID.
example: order-789
consumerEmail:
type: string
description: Consumer's email address.
example: user@example.com
createdAt:
type: string
description: ISO 8601 creation timestamp.
example: '2026-04-30T10:00:00.000Z'
failureReason:
type: string
nullable: true
description: null on a successful capture; error code when the payment is declined.
example: null
CreatePreAuthRequestDto:
required:
- paymentToken
- merchantUserId
- amount
- currency
- merchantRef
type: object
properties:
paymentToken:
type: string
description: Payment token from POST /token. Resolves the user and their default card.
example: aBcD1234eFgH5678iJkL9012mNoP3456
merchantUserId:
type: string
description: Merchant's opaque identifier for the end user (e.g. user ID). Used to verify the
payment token belongs to this user.
example: merchant_rider_42
amount:
type: number
description: Hold amount. Must be > 0. Also the capture amount.
example: 20.5
currency:
type: string
description: 3-letter ISO currency code. Must match the merchant channel country currency.
example: SGD
merchantRef:
type: string
description: Merchant's reference ID (e.g. trip ID). Used for idempotent duplicate detection.
example: trip-456
merchantMetadata:
type: object
description: Opaque JSON blob stored verbatim and returned on read endpoints. Max 5 keys; each
string value must not exceed 200 characters.
example:
tripId: trip-456
estimatedMinutes: 30
PreAuthResponseDto:
required:
- id
- merchantRef
- status
- amount
- currency
- orderUuid
- orderStatus
- failureReason
- merchantMetadata
- createdAt
- updatedAt
type: object
properties:
id:
type: string
description: Pre-authorization UUID.
example: 550e8400-e29b-41d4-a716-446655440000
merchantRef:
type: string
description: Merchant's reference ID supplied at creation.
example: trip-456
status:
type: string
description: Lifecycle state of the pre-authorization.
enum:
- PENDING
- AUTHORIZED
- CAPTURE_INITIATED
- CAPTURED
- VOIDED
- DECLINED
- EXPIRED
example: AUTHORIZED
amount:
type: number
description: Hold amount in major currency units.
example: 20.5
currency:
type: string
description: 3-letter ISO currency code.
example: SGD
orderUuid:
type: string
description: UUID of the settled order. Non-null after capture.
example: 7b3f1234-ab12-4321-b123-000000000001
nullable: true
orderStatus:
type: string
description: Status of the settled order. Non-null after capture.
example: COMPLETED
nullable: true
failureReason:
type: string
description: Failure reason if the pre-auth was declined or expired.
example: null
nullable: true
merchantMetadata:
type: object
description: Merchant-supplied metadata stored verbatim at creation.
example:
tripId: trip-456
nullable: true
createdAt:
type: string
description: ISO 8601 creation timestamp.
example: '2026-04-30T10:00:00.000Z'
updatedAt:
type: string
description: ISO 8601 last-updated timestamp.
example: '2026-04-30T10:05:00.000Z'
GetCashbackBalanceRequest:
required:
- paymentToken
type: object
properties:
paymentToken:
type: string
description: Payment token issued by ShopBack to identify the linked ShopBack user.
example: aBcD1234eFgH5678iJkL9012mNoP3456
GetCashbackBalanceResponse:
required:
- cashbackBalance
- currency
type: object
properties:
cashbackBalance:
type: number
description: Available cashback balance in major units (e.g. 15.00 = $15.00).
example: 15
currency:
type: string
description: 3-letter ISO currency code for the balance.
example: SGD
GetLinkSessionResponse:
required:
- linkToken
- status
- expiresAt
- authCode
- authCodeExpiresAt
type: object
properties:
linkToken:
type: string
description: Opaque UUID identifying the linking session (the merchant-facing `linkToken`).
example: 550e8400-e29b-41d4-a716-446655440000
status:
type: string
description: Current lifecycle state of the link session.
enum:
- PENDING
- CODE_ISSUED
- COMPLETED
- EXPIRED
example: PENDING
expiresAt:
type: string
description: Overall session TTL (20 min from creation). After this the session transitions
to EXPIRED.
example: '2026-04-30T10:20:00.000Z'
authCode:
type: string
description: Short-lived auth code issued after rider consent. Non-null only when `status =
CODE_ISSUED`; pass to `POST /token` to complete the exchange.
example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4
nullable: true
authCodeExpiresAt:
type: string
description: 60-second TTL on `authCode`. Non-null only when `status = CODE_ISSUED`.
example: '2026-04-30T10:01:05.000Z'
nullable: true
MerchantOrderResponse:
# --- truncated at 32 KB (60 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/shopback/refs/heads/main/openapi/shopback-online-payments-openapi.yml