Authentication

Every Portal API call is authenticated with a username + password (HTTP Basic Auth). The username's prefix tells the platform what kind of caller you are — PSP, acquirer, or merchant — and what endpoints you're allowed to hit.

For the broader Scan to Pay authentication story (Remote API, JWT/PKI, etc.), see Authentication.

The ROLE_REMOTE opt-in

By default, Portal credentials authenticate the web UI only. To call the REST API with the same credentials, the profile must additionally have ROLE_REMOTE granted.

ROLE_REMOTE is provisioned by Scan to Pay Operations — it's not self-serve. Request it for a profile via [email protected] with:

• The profile type (PSP, acquirer, or merchant)
• The profile ID (PSP ID, acquirer name, or merchant ID)
• The environment (sandbox, production, or both)

Once granted, the same credentials you use to log into the Portal will work against /restful/... endpoints.

⚠️

Without ROLE_REMOTE, every API call returns 401 Unauthorized regardless of whether the password is correct. Check this first if you see persistent 401s.

Caller prefixes

The Portal API distinguishes callers by the prefix of the authenticated username. Three caller types are supported:

You don't choose your prefix — it's determined when your profile is provisioned. The platform uses it to route each request to the right authorization check.

Per-endpoint caller restrictions

Not every endpoint accepts every caller type. The general pattern:

A caller that hits an endpoint outside its allowed list gets a 401 Unauthorized — even with valid credentials. Each endpoint page lists its allowed callers in the reference table.

Ownership validation

In addition to the caller-prefix gate, every endpoint that touches a specific merchant runs an ownership check: does this caller actually own (or have authority over) the merchant they're trying to act on?

A failed ownership check returns HTTP 400 BAD_REQUEST with "Invalid 'merchantId'". You can't act on a merchant outside your scope — and you can't enumerate merchants outside your scope either (use Merchant management → List merchants to see what you own).

Basic Auth on the wire

Every request must include:

Authorization: Basic <base64(username:password)>
Content-Type: application/json

curl example:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/list \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json'

HTTPS is mandatory. HTTP is rejected at the load balancer.

Rotating your own credentials

The Portal API doesn't expose a self-service password-rotation endpoint for the Portal credential itself — change it via the Portal UI: log in → email dropdown → Change Password.

For rotating a merchant's API password (the one used to call the Remote API and other transactional APIs), see API credentials.

For rotating webhook encryption keys, see Notifications.

Common authentication errors

If a 401 persists despite correct credentials, the most likely cause is missing ROLE_REMOTE on the profile.

What's next

• Onboard a merchant → Merchant management
• Configure webhook delivery → Notifications
• Rotate a merchant's API password → API credentials
• Cross-cutting rules → Business rules
• Get help → Support