PSP / aggregator flows

If you're a PSP or an aggregator onboarding merchants you've signed up onto your own platform, this is your flow. You authenticate with PSP credentials (PSP ID + API password generated in the Portal) and create merchants under your own PSP relationship.

For the Acquirer version of the same API, see Acquirer flows. For the operation reference, see Onboarding overview.

PSP credentials

Your PSP credentials are:

The Basic Auth username is psp-{your-psp-id} (e.g. psp-13). Together with the API password, this authenticates every onboarding API call.

⚠️

Renewing the PSP API password invalidates the previous one immediately. Coordinate with your deploy or the automation that uses it. Plan rotation as a deploy event.

Create a merchant (PSP)

curl -X POST "https://qa.scantopay.io/portal/restful/merchant/create" \
  -u "psp-13:$PSP_API_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"
    }
  }'

PSP-specific notes:

• No pspId field needed in the body — your credentials identify which PSP relationship the merchant sits under.
• acquirerMerchantId is set automatically based on your PSP's pre-configured acquirer relationship. If your PSP has multiple acquirers, you'll set this at the PSP-level configuration; individual merchant creates inherit it.
• merchantCategoryCode defaults to your PSP's standard MCC; override per-merchant only if you have varied retail categories.

Response includes the assigned merchantId. The merchant's admin email receives a welcome email to log in to the Portal and complete their setup.

Set up the merchant's environment

After create, complete the merchant's setup with three API calls:

# 1. Add the merchant's notification URL
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/notification/add/25" \
  -u "psp-13:$PSP_API_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{ "url": "https://merchant.example/webhooks/scantopay" }'

# 2. Generate the merchant's API password
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/password/25" \
  -u "psp-13:$PSP_API_PASSWORD"

# Returns: { "apiPassword": "..." }

# 3. (Only if the merchant uses Lib Lite SDK) Generate the Lib Lite token
curl -X POST "https://qa.scantopay.io/portal/restful/merchant/libliteToken/25" \
  -u "psp-13:$PSP_API_PASSWORD"

You now hand the merchant their API username (merchant-{merchantId}) and the generated API password. They use these to call /code/create, /purchase/*, and other merchant-facing endpoints from their backend.

List your merchants

Get a paginated list of all merchants under your PSP:

curl -X GET "https://qa.scantopay.io/portal/restful/merchant/list?page=0&size=50" \
  -u "psp-13:$PSP_API_PASSWORD"

Useful for reconciliation, periodic audits, or building your own merchant-management dashboard on top of the API.

Suspend / unsuspend for compliance

If a merchant violates your terms (chargeback ratio threshold breached, compliance issue, account closure), suspend them:

curl -X POST "https://qa.scantopay.io/portal/restful/merchant/suspend/25" \
  -u "psp-13:$PSP_API_PASSWORD"

The merchant immediately stops being able to accept new transactions. Existing in-flight transactions complete normally — suspension applies forward, not retroactively. Unsuspend with the corresponding endpoint when the issue is resolved.

Permissions and scoping

Your PSP credentials can:

What's next

• Full operation reference → Onboarding overview
• Business rules → Business rules
• The acquirer counterpart of this page → Acquirer flows
• What your merchants do after they're onboarded → Quickstart
• Test the onboarding flow → Testing