Merchant onboarding overview

The Merchant Onboarding API at /portal/restful/merchant/* lets you create, suspend, update, and manage merchants programmatically. This page is the canonical reference: every operation, auth setup, and the lifecycle from create-to-live.

For the per-audience request shapes, see Acquirer flows and PSP / Aggregator flows. For the rules, see Business rules. For the full call-by-call REST reference (every endpoint, every field), see Portal API → Merchant management.

Base URL and auth

Username and password come from one of two sources depending on whether you're an acquirer or a PSP — see Business rules > Credentials.

Operations

The API exposes 11 operations, grouped by lifecycle phase:

Lifecycle

Notifications

Credentials

The onboarding lifecycle

   Your platform              Scan to Pay platform           The new merchant
   ─────────────              ─────────────────────           ────────────────
        │                              │                            │
        │  POST /create                │                            │
        ├─────────────────────────────►│                            │
        │                              │                            │
        │◄──── merchantId + creds ─────┤                            │
        │                              │                            │
        │                              │   email sent to admin ────►│
        │                              │                            │
        │  POST /notification/add      │                            │
        ├─────────────────────────────►│                            │
        │                              │                            │
        │  POST /password              │                            │
        ├─────────────────────────────►│                            │
        │                              │                            │
        │◄──── API password ───────────┤                            │
        │                              │                            │
        │  (merchant can now create codes and accept payments)      │
        │                              │                            │
        │                              │                            │
        │  POST /suspend (later, if needed)                         │
        ├─────────────────────────────►│                            │

Five steps:

1. Create the merchant. Supply name, email, URL, and other details. The platform returns a merchantId.
2. Add a notification URL if the merchant will use webhooks. Each merchant has at most one HTTP notification URL.
3. Generate an API password for the merchant. Returns the credentials they'll use on subsequent code-create / purchase calls.
4. (Optional) Generate a Lib Lite token if the merchant integrates the Library Lite SDK. Separate from the API password — see In-App Payments.
5. (Later) Suspend / Unsuspend / Update as needed for ongoing management.

Merchants are auto-activated on create — they can immediately accept payments. There's no separate "activate" step.

Create — request shape

curl -X POST "https://qa.scantopay.io/portal/restful/merchant/create" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "[email protected]",
    "name": "Acme Coffee Pty Ltd",
    "tradingName": "Acme Coffee",
    "url": "https://acmecoffee.example",
    "phoneNumber": "27101234567",
    "currencyCode": "ZAR",
    "merchantCategoryCode": "5814",
    "address": {
      "line1": "1 Main Road",
      "city": "Cape Town",
      "country": "ZA",
      "postalCode": "8001"
    }
  }'

Response includes the assigned merchantId. The email you supply receives an automated welcome message confirming the merchant was created.

For the full set of optional fields (including super-merchant settings, MCC overrides, currency caps), see the auto-rendered API Reference.

The exact request body differs slightly between acquirers and PSPs — see Acquirer flows and PSP / Aggregator flows.

Update — keep merchant data in sync

If a merchant's name, URL, or contact details change, push the update through the API:

curl -X POST "https://qa.scantopay.io/portal/restful/merchant/update/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://acmecoffee.com",
    "phoneNumber": "27107654321"
  }'

⚠️

Update can break transactions if used incorrectly. Avoid changing the merchant's currency, acquirer linkage, or MID once live payments are flowing. Updates to non-financial fields (name, URL, contact) are always safe.

Suspend and unsuspend

For temporary suspension (e.g. during a billing dispute, account investigation, or merchant-requested pause):

# Suspend
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/suspend/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD"

# Unsuspend
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/unsuspend/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD"

A suspended merchant cannot create codes or receive payments. Existing codes return 434 CLIENT_SUSPENDED on scan.

Notification URL operations

A merchant has at most one HTTP notification URL. Add or renew it via API:

# Add
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/notification/add/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://merchant.example/webhooks/scantopay" }'

# Renew the key (rotates the notification decryption key)
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/notification/renew/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD"

⚠️

Renewing the notification key invalidates the old one immediately. Coordinate with the merchant's deploy. See Signing and verifying webhooks.

API password and Lib Lite token

Generate the merchant's credentials:

# API password — used for code/create, purchase, refund, queryRef calls
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/password/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD"

# Lib Lite token — only for merchants integrating the SDK
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/libliteToken/25" \
  -u "$ONBOARDING_USERNAME:$ONBOARDING_PASSWORD"

The API password and the Lib Lite token are different credentials. Don't conflate them. See Authentication.

Errors

See Errors for the full reference.

What's next

• The PSP / aggregator flow → PSP / Aggregator flows
• The acquirer flow → Acquirer flows
• Business rules and constraints → Business rules
• Test the onboarding flow → Testing
• What the merchant does after they're onboarded → Quickstart
• The Lib Lite token vs the API password → Authentication