Merchant management

The merchant-management endpoints are the programmatic way for PSPs and acquirers to onboard, update, and lifecycle-manage their merchants. They're the API behind the Portal UI's merchant screens.

For the conceptual walk-through and decision tree, see Merchant Onboarding. For auth setup, see Authentication.

Endpoints

All requests use Basic Auth with a ROLE_REMOTE-enabled profile — see Authentication.

List merchants

Returns every merchant in your scope. For a PSP, that's merchants where pspId matches the caller. For an acquirer, that's merchants where acquirer matches the caller.

Request:

curl -X GET https://qa.scantopay.io/portal/restful/merchant/list \
  -u 'PSP_42:yourPspApiPassword'

Response:

[
  {
    "merchantId": 25,
    "merchantName": "Acme Coffee Pty Ltd",
    "merchantCategoryCode": "5812",
    "cardAcceptorTerminalId": "12345678",
    "cardAcceptorIdentificationCode": "8765432",
    "cardAcceptorNameLocation": "ZA",
    "email": "[email protected]",
    "acquirer": "SBSA",
    "pspId": 42,
    "merchantStatus": "ACTIVE",
    "acceptedCards": ["master", "visa"],
    "acceptedPayments": "AMT,SECURE_CODE"
  }
]

Returns an empty array if you own no merchants. There's no pagination today — the full list comes back in one response.

Create a merchant

Onboards a new merchant on the platform. Returns the freshly-created merchant including its assigned merchantId.

Request body — ApiMerchantBean:

Nested address object:

Sample request:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/create \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantName": "Acme Coffee Pty Ltd",
    "merchantCategoryCode": "5812",
    "cardAcceptorTerminalId": "12345678",
    "cardAcceptorIdentificationCode": "8765432",
    "cardAcceptorNameLocation": "ZA",
    "email": "[email protected]",
    "acquirer": "SBSA",
    "acceptedCards": ["master", "visa"],
    "address": {
      "addressLine1": "1 Main Road",
      "city": "Cape Town",
      "country": "South Africa",
      "postalCode": "8001"
    }
  }'

Response:

The full ApiMerchantBean of the new merchant, including the assigned merchantId and current merchantStatus.

Common errors:

Update a merchant

Two modes:

Selective update is the safer choice for most use cases.

Sample request — selective update changing only the email:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/update \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 25,
    "updateOnlyPresentFields": true,
    "email": "[email protected]"
  }'

Response: the updated ApiMerchantBean.

Update constraints:

• merchantId is mandatory
• Merchant must be in ACTIVE state
• Ownership check applies (PSP/acquirer can only update merchants they own)
• acquirer can be changed (PSP-only) provided the new acquirer is in the supported list

For the rules around mutating PayShap info, see PayShap management.

Suspend a merchant

Moves a merchant from ACTIVE to SUSPENDED. The merchant stops being able to accept new transactions until unsuspended.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/suspend \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 25,
    "reason": "Compliance hold pending document review"
  }'

Request fields:

Response: HTTP 200 OK with no body.

Common errors:

Unsuspend a merchant

Reverses a suspension — moves from SUSPENDED back to ACTIVE.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/unsuspend \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 25,
    "reason": "Documents received and verified"
  }'

Same request body as suspend. The reason is captured in the audit log.

Common errors:

What about activation?

Newly-created merchants are activated automatically as part of the /restful/merchant/create flow — no separate activation step is required. The legacy /restful/merchant/activate/{merchantId} endpoint is deprecated and not documented here.

If a merchant ends up in WAITING ACTIVATION for some reason (typically a back-office configuration step), contact [email protected] to resolve.

What's next

• Conceptual walk-through of onboarding → Merchant Onboarding
• Configure the merchant's webhook → Notifications
• Generate the merchant's API password → API credentials
• Generate Lib Lite tokens for in-app payments → Lib Lite tokens
• Cross-cutting rules → Business rules