Tokenized Payment — Getting Started

Tokenized payment lets your mobile app charge a ShopBack user's linked payment method without redirecting them to a checkout page on every transaction. The user links their ShopBack account once; from then on, your backend initiates charges directly using a long-lived payment token.

---

How it works

The integration has two stages:

---

Choose your payment mode

Once you have a paymentToken, you have two options for taking payment:

Pre-authorization (hold, then capture)

Place a hold on the user's funds when a service starts, then settle the exact amount once you know it. The capture amount can differ from the original hold.

Best for: ride-hailing, hotel bookings, metered services — any use case where the final amount isn't known at the start.

Flow: POST /pre-auths → (service completes) → POST /pre-auths/{id}/capture

Immediate charge (auth + capture in one step)

Charge the user's linked method in a single API call. No separate capture step.

Best for: fixed-price purchases — food delivery, top-ups, on-demand services with a known price.

Flow: POST /charge

---

End-to-end overview

┌─────────────────────────────────────────────────┐
│             ACCOUNT LINKING (once)              │
│  Merchant App → ShopBack consent → paymentToken │
└───────────────────────┬─────────────────────────┘
                        │ paymentToken
          ┌─────────────┴─────────────┐
          ▼                           ▼
┌─────────────────┐         ┌───────────────────┐
│  Pre-auth flow  │         │  Immediate charge │
│ POST /pre-auths │         │   POST /charge    │
│       ↓         │         │       ↓           │
│ POST .../capture│         │  Order created    │
└─────────────────┘         └───────────────────┘

---

Prerequisites

Before you start:

1. Merchant credentials — You need a merchant JWT to authenticate requests. Obtain this from our integration engineer.

2. Registered callback URL — The callbackUrl you pass during account linking must be on the allowlist configured for your merchant channel. Contact ShopBack to add URLs.

3. Mobile app with in-app browser — Account linking opens a ShopBack-hosted consent page inside your app using an in-app browser (e.g. SFSafariViewController on iOS, Custom Tabs on Android).

4. Base URL — All endpoints below are relative to your merchant gateway base URL provided by ShopBack.

---

Authentication

All merchant gateway requests require a Bearer token in the Authorization header:

Authorization: Bearer <merchant_jwt>

---

Pages in this guide