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: required: - consumerEmail - createdAt - merchantOrderId - merchantRef - orderType - orderUuid - status - uuid - paymentType type: object properties: uuid: type: string description: Randomly generated order uuid readOnly: true example: 4d33044e-f182-4079-aee4-faa46fbf334e orderUuid: type: string description: Randomly generated order uuid. Same as uuid readOnly: true example: 4d33044e-f182-4079-aee4-faa46fbf334e createdAt: type: string description: Order creation time format: date-time readOnly: true example: '2019-01-28T10:56:28.995Z' status: type: string description: Order status provided to the merchant readOnly: true example: INITIATED enum: - INITIATED - APPROVED - CANCELLED - REJECTED - REFUNDED orderType: type: string description: Order type readOnly: true example: ONLINE enum: - INSTORE - ONLINE merchantRef: type: string description: Merchant's Order Id readOnly: true example: '#2020-82445' merchantOrderId: type: string description: Merchant's Order Id. Same as merchantRef readOnly: true example: '#2020-82445' consumerEmail: type: string description: Consumer's email readOnly: true example: bruce.willis@shopback.com paymentMethod: type: string description: Customer’s payment method. Populated for completed and refunded orders only. This field is deprecated. readOnly: true example: PAYLATER enum: - PAYLATER - PAY paymentType: type: string description: (NOT LIVE YET) Customer’s payment type. Populated for completed and refunded orders only. readOnly: true example: PAYLATER enum: - PAYLATER - PAY ErrorResponse: type: object properties: statusCode: type: integer description: HTTP Status Code. errorId: type: string description: An error Id unique to the error received. errorMessages: type: array description: The reason why the error occured. name: type: string description: ShopBack system defined error name. errorCode: type: string description: ShopBack system defined error code. code: type: string description: ShopBack system defined error code. helpUrl: type: string description: Information on where you can receive additional assistance from our wonderful support team. ImmediateChargeRequestDto: 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. Must match the merchantUserId used when the paymentToken was issued. example: merchant_rider_42 amount: type: number description: Charge amount. Must be > 0. example: 17 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. Used for idempotent duplicate detection. example: trip-456-tip useCashback: type: boolean description: Whether to apply available cashback to this charge. example: true default: true callbackUrl: type: string description: 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: https://merchant.example.com/webhooks/shopback ImmediateChargeResponseDto: required: - uuid - orderUuid - status - orderType - merchantRef - merchantOrderId - consumerEmail - failureReason - createdAt type: object properties: uuid: type: string description: Charge UUID. example: 550e8400-e29b-41d4-a716-446655440000 orderUuid: type: string description: UUID of the settled order created by this charge. example: 7b3f1234-ab12-4321-b123-000000000001 status: type: string description: Order status after charge. example: APPROVED orderType: type: string description: Order type. example: ONLINE merchantRef: type: string description: Merchant's reference ID supplied at charge creation. example: trip-456-tip merchantOrderId: type: string description: Merchant's order ID. example: order-789 consumerEmail: type: string description: Consumer's email address. example: user@example.com failureReason: type: string description: Failure reason if the charge failed; null on success. example: null nullable: true createdAt: type: string description: ISO 8601 creation timestamp. example: '2026-04-30T10:00:00.000Z' UserHintDto: type: object properties: phone: type: string description: Pre-redacted phone number as registered with the merchant (e.g. "+6591xxxx67"). Displayed as-is on the consent page. The merchant is responsible for redacting before sending. example: +6591xxxx67 maxLength: 30 email: type: string description: Pre-redacted email address as registered with the merchant (e.g. "r***@example.com"). Displayed as-is on the consent page. The merchant is responsible for redacting before sending. example: r***@example.com maxLength: 254 InitiateLinkSessionRequest: required: - callbackUrl - state - merchantUserId - userHint type: object properties: callbackUrl: type: string description: Merchant callback URL; must be on the per-channel allowlist. example: https://merchant-name.sg/link/callback state: type: string description: Merchant-supplied CSRF nonce; stored verbatim and echoed back unchanged in the callback redirect. example: a8f3c2e1d7b4509f merchantUserId: type: string description: Merchant's opaque user ID. Used to verify that tokenized payments can only be made to the same customer who initiated the link session. example: merchant_user_42 userHint: description: Identity hints from the merchant displayed on the ShopBack consent page so the user can verify the linking request was intended for them. At least one sub-field must be present. ShopBack does not validate these values — they are display-only. allOf: - $ref: '#/components/schemas/UserHintDto' InitiateLinkSessionResponse: required: - linkToken - redirectUrl - expiresAt - appToken type: object properties: linkToken: type: string description: Opaque UUID identifying the linking session. Not embedded in `redirectUrl`. example: 550e8400-e29b-41d4-a716-446655440000 redirectUrl: type: string description: Base ShopBack URL. Does NOT include any token; the merchant appends token(s) themselves before opening the in-app browser. Valid until `expiresAt`. example: https://pay.shopback.com/link expiresAt: type: string description: Session TTL from creation. After this, the session is EXPIRED. example: '2026-04-30T10:20:00.000Z' appToken: type: string description: HS256-signed JWT binding this response to the link session. The payload contains { linkToken } and expires at the same time as the session. Pass this as the X-ShopBack-App-Token header when opening the in-app browser. example: InitiateOnlineOrderRequest: required: - billingAddress - currency - items - shippingAddress - totalAmount type: object properties: totalAmount: minimum: 1 type: number description: Total amount of order, includes all items originalAmount: type: number description: Pre discount amount of order, includes all items voucherCode: type: string description: Any voucher code to be applied on order example: FLAT50 discount: type: number description: The discount amount example: 10 consumerEmail: type: string description: Consumer's email example: bruce.willis@shopback.com consumerPhoneNumber: type: string description: Consumer's Phone Number example: '+6512341234' callbackUrl: type: string description: The server to server payment notification (payment notification webhook). Refer [here](https://docs.shopback.com/docs/server-to-server-payment-notification-payment-notification-webhook) for more details example: http://merchant.com/order/193123123/callback closeUrl: type: string description: The URL to which merchant would like to redirect users once the charging is completed for failed transaction example: http://merchant.com/order/193123123/close returnToShopUrl: type: string description: The URL to which merchant would like to redirect users once transaction is completed for successful transaction example: http://merchant.com/order/193123123/returnToShop platformVersion: type: string description: Platform Version example: 12.2.3 consumerPhoneNumberExtension: type: integer description: Consumer's country code format: int32 example: 65 consumerTitle: type: string description: Title of the consumer example: Mr consumerFirstName: type: string description: Consumer's First Name example: Bob consumerLastName: type: string description: Consumer's Last Name example: Mann consumerMiddleName: type: string description: Consumer's Middle Name example: John taxAmount: type: number description: Total tax for the order currency: type: string description: Currency of the order in the 3 figure code as per ISO 4217 example: SGD shippingMethod: type: string description: Shipping method preferred for order example: NORMAL enum: - NORMAL - EXPRESS - PICKUP - FREE - MERCHANT_SPECIFIED shippingAddress: $ref: '#/components/schemas/ShippingAddressRequest' billingAddress: $ref: '#/components/schemas/BillingAddressRequest' items: type: array description: List of order items items: $ref: '#/components/schemas/OrderItemRequest' merchantRef: type: string description: Merchant order reference. This is the field that the merchant uses to identify the order from their side on. This field is deprecated. Please use cartId or merchantOrderId depending on your order creation strategy. example: abc1234xyz shippingAmount: type: number description: This field captures the shipping fees associated with the chosen shipping method example: 10 merchantOrderId: type: string description: The final merchant order id. This is applicable for platforms which creates the order id as soon as the checkout process starts, for e.g. Woocommerce orders. Platforms such as Shopify does not create an order until the callback is triggered. Such platforms make use of an internal reference id, also called cart Id - use the field merchantRef for internal reference id. cartId: type: string description: Merchant's cart id. This field stores the merchant's card id value. This is the internal order reference number until the order is created at the merchant's store. example: abc1234xyz storeUuid: type: string description: Merchant's Online Store identifier at ShopBack side. If it is omitted latest created Online Store will be used example: 281ac28b-e785-429d-bf12-5a50e9db9377 partner: description: Merchant information for ShopBack partner $ref: '#/components/schemas/PartnerMerchantInfoRequest' PartnerMerchantInfoRequest: required: - merchantId type: object properties: merchantId: type: string description: Partner's unique merchant ID. This field is required if partner field is provided merchantCategoryCode: type: number description: Merchant ISO 18245 category code determined by the partner merchantTradingName: type: string description: Trading name of the merchant to help with customer UX when completing a purchase with ShopBack merchantEntityId: type: string description: Legally registered ID with the regulatory in country of registration example: UEN in Singapore OrderItemImageRequest: required: - imageLocation type: object properties: imageLocation: type: string description: ImageLocation example: https://homepages.cae.wisc.edu/~ece533/images/serrano.png OrderItemRequest: required: - name type: object properties: name: type: string description: The name of the item example: radioactive man comic book quantity: type: integer description: Quantity of the item format: int32 price: type: number description: Actual price of the item sku: type: string description: Store keeping unit at the merchant level example: '93847598347' ean: type: string description: The items EAN description: type: string description: Short description of the item example: radioactive man comic book detailedDescription: type: string description: Detailed description of the item originalPrice: type: number description: Pre discount amount of the item taxAmount: type: number description: Tax amount of the item images: type: array description: List of order item images items: $ref: '#/components/schemas/OrderItemImageRequest' merchantItemId: type: string description: The unique ID for each order item, if SKU is not explicitly used. warranty: type: number description: This field captures the warranty amount per order item example: 100 discount: type: number description: This field captures the discount amount per order item example: 10 InitiatedOrderResponse: required: - orderId type: object properties: orderContextToken: type: string orderId: type: integer format: int64 orderUuid: type: string BillingAddressRequest: type: object properties: line1: type: string description: line1 of address example: Blk 35 Mandalay Road line2: type: string description: line2 of address example: '# 13-37 Mandalay Towers' line3: type: string description: line3 of address suburb: type: string description: suburb example: Sentosa city: type: string description: city example: Malacca City province: type: string description: province example: Shanghai state: type: string description: state example: Selangor district: type: string description: District. A required field for addresses in Honk Kong, India, Indonesia, Pakistan example: New Delhi subDistrict: type: string description: Sub-District. This is an optional field for addresses in Indonesia - called Kecamatan in Indonesia. example: Kecamatan Walakaka municipality: type: string description: Municipality. This is an optional field for addresses in Japan, Philippines and India. example: Sapporo village: type: string description: Village. This is an optional field for addresses in Bengladesh, Pakistan and India. example: Kakran road: type: string description: Road. This is an optional field for addresses in Thailand. example: 111 Chaengwatthana Road county: type: string description: County. This is an optional field for addresses in Bangladesh - functionally same as Upazila/Thana, South Korea - functionally same as Gun, United Kingdom among other countries. example: Pudong viaName: type: string description: via route. This is an optional field for addresses in India. example: New Delhi taluk: type: string description: Taluk. This is an optional field for addresses in India. example: Meenachil Taluk postcode: type: string description: postcode example: '308215' countryCode: type: string description: countryCode example: SG ShippingAddressRequest: type: object properties: line1: type: string description: line1 of address example: Blk 35 Mandalay Road line2: type: string description: line2 of address example: '# 13-37 Mandalay Towers' line3: type: string description: line3 of address suburb: type: string description: suburb example: Sentosa city: type: string description: city example: Malacca City province: type: string description: province example: Shanghai state: type: string description: state example: Selangor district: type: string description: District. A required field for addresses in Honk Kong, India, Indonesia, Pakistan example: New Delhi subDistrict: type: string description: Sub-District. This is an optional field for addresses in Indonesia - called Kecamatan in Indonesia. example: Kecamatan Walakaka municipality: type: string description: Municipality. This is an optional field for addresses in Japan, Philippines and India. example: Sapporo village: type: string description: Village. This is an optional field for addresses in Bengladesh, Pakistan and India. example: Kakran road: type: string description: Road. This is an optional field for addresses in Thailand. example: 111 Chaengwatthana Road county: type: string description: County. This is an optional field for addresses in Bangladesh - functionally same as Upazila/Thana, South Korea - functionally same as Gun, United Kingdom among other countries. example: Pudong viaName: type: string description: via route. This is an optional field for addresses in India. example: New Delhi taluk: type: string description: Taluk. This is an optional field for addresses in India. example: Meenachil Taluk postcode: type: string description: postcode example: '308215' countryCode: type: string description: countryCode example: SG RRVResponseDetailsModel: required: - merchantFeeAmount - transactionFeeAmount type: object properties: transactionFeeAmount: type: number description: Transaction fee amount merchantFeeAmount: type: number description: Merchant fee amount RRVResponseModel: required: - code - message - status - type type: object properties: status: type: string description: Request processing status example: ACCEPTED, REJECTED, DONE, FAILED enum: - ACCEPTED - REJECTED - DONE - FAILED requestId: type: string description: Request identifier. Present only if request has been accepted. example: d04f56e9-412c-4e7a-8cb7-3f405ff96a13 createdAt: type: string description: Request creation date-time in ISO-8601 date-time format. Present only if request has been accepted. format: date-time example: '2022-04-01T04:01:41.041Z' type: type: string description: Type of refund. example: FULL enum: - FULL - PARTIAL code: type: string description: Response code. Useful to extract error details. example: accepted, in_process, duplicated_request, invalid_order_status, no_active_merchant_fee_schema_found, refund_amount_too_large, refund_limit_exceeded message: type: string description: Response message example: Request accepted details: $ref: '#/components/schemas/RRVResponseDetailsModel' PartialRefundItemRequestModel: required: - sku type: object properties: sku: type: string description: Store keeping unit at the merchant level. Needed to link requests with specific order items. example: '93847598347' PartialRefundRequestModel: required: - amount - description type: object properties: description: maxLength: 1024 minLength: 0 type: string description: Operation description example: Out of stock/Color is not fit to my bedroom refundedByEmail: maxLength: 1024 minLength: 0 type: string description: Refunded by email - coming from business.shopback.* portal example: user@email.com webhookUrl: maxLength: 1024 minLength: 0 type: string description: Webhook address - when operation will be done specified endpoint will be invoked example: https://mystore.com/shopback/hooks amount: type: number description: Amount to refund items: type: array description: Optional list of order items to be refunded items: $ref: '#/components/schemas/PartialRefundItemRequestModel' LoginRequest: required: - password - username type: object properties: username: type: string description: This will be the merchant ID provided by ShopBack example: abcde-12345-abcde12345 password: type: string description: This will be the merchant secret proviced by ShopBack. TK_ for Sandbox, PK_ for Production example: TK_sandbox123 LoginResponse: type: object properties: token: type: string description: Auth token provided by ShopBack to the merchant example: local-RUZvpBJr56eC5X0ZVXog4TnZ3Rp8GsF9UWZyWv9o7iM expiresAt: type: string description: Token expiry format: date-time example: '2019-01-05T20:18:32.651+05:30' SwapPaymentTokenRequest: required: - code type: object properties: code: type: string description: The short-lived auth code. Single-use, has TTL. example: a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4 SwapPaymentTokenResponse: required: - paymentToken type: object properties: paymentToken: type: string description: Long-lived opaque token scoped to (merchant, user, country). Re-linking the same user returns the same value. example: aBcD1234eFgH5678iJkL9012mNoP3456 UnlinkPaymentTokenRequest: required: - paymentToken type: object properties: paymentToken: type: string description: Payment token to revoke. Sent in the request body (not the URL) to prevent the value from appearing in access logs and APM telemetry. example: aBcD1234eFgH5678iJkL9012mNoP3456 UnlinkPaymentTokenResponse: required: - paymentToken - status type: object properties: paymentToken: type: string description: The payment token that was revoked. example: aBcD1234eFgH5678iJkL9012mNoP3456 status: type: string description: New status of the payment token after revocation. enum: - LINKED - UNLINKED example: UNLINKED VoidPreAuthRequest: type: object properties: reason: type: string description: Optional free-text reason for voiding. Stored verbatim on the pre-auth lifecycle. example: Rider cancelled before driver arrived maxLength: 500 merchantMetadata: type: object description: Opaque JSON blob stored verbatim on the pre-auth row, replacing any value set at creation. Max 5 keys; each string value must not exceed 200 characters. example: replacesPaymentId: ord-D tripId: trip-456 x-tagGroups: - name: Orders tags: - Orders - name: Authentication tags: - Authentication - name: Platform tags: - Platform - name: Tokenized Payment tags: - Account Linking - Pre-Auth x-apievangelist-assembly: method: searched note: Assembled verbatim from the per-operation OpenAPI definitions ShopBack publishes on each API reference page of docs.shopback.com (ReadMe .md export). No content was authored or altered; path items, schemas and security schemes are exactly as published. fetched: '2026-08-02' index: https://docs.shopback.com/llms.txt sources: - https://docs.shopback.com/reference/capture-pre-auth.md - https://docs.shopback.com/reference/create-pre-auth.md - https://docs.shopback.com/reference/get-cashback-balance.md - https://docs.shopback.com/reference/get-link-session.md - https://docs.shopback.com/reference/get-pre-auth.md - https://docs.shopback.com/reference/getorderinfo.md - https://docs.shopback.com/reference/immediate-charge.md - https://docs.shopback.com/reference/initiate-link-session.md - https://docs.shopback.com/reference/initiateorder.md - https://docs.shopback.com/reference/initiateorderrefund.md - https://docs.shopback.com/reference/login.md - https://docs.shopback.com/reference/swap-payment-token.md - https://docs.shopback.com/reference/unlink-payment-token.md - https://docs.shopback.com/reference/void-pre-auth.md http_status: 200