Authentication

Scan to Pay supports two authentication methods. Basic Auth is the default and the right choice for most integrators. JWT Bearer with PKI is an opt-in upgrade for tenants that want certificate-based mutual trust.

Both methods authenticate the same accounts and grant the same access — the difference is how you prove your identity on each request. Under the hood, the API accepts both; if a Bearer token is present and valid, it takes precedence over any Basic Auth credentials in the same request.

⚠️

Bearer mode is a hard switch. Once support enables JWT Bearer for your account, your Basic Auth password is invalidated. You cannot use both methods simultaneously on the same account — you can only have both available across different accounts. Read the Going from Basic to JWT section before you ask for the switch.

Quick reference

# Basic Auth (default)
curl -u "merchant-25:your-api-password" \
  https://qa.scantopay.io/pluto/code/123456789

# JWT Bearer (opt-in)
curl -H "Authorization: Bearer eyJhbGci...<snip>..." \
  https://qa.scantopay.io/pluto/code/123456789

Every request, regardless of method, must:

• Use HTTPS — plain HTTP is rejected
• Set Content-Type: application/json on requests with a body
• Authenticate. The only exception is /public/** paths (QR image rendering, public callbacks, monitor) which are intentionally unauthenticated

Basic Auth

The default. Every Scan to Pay account gets a username and an API password. You include them on every request as standard HTTP Basic Auth.

Username format

The {merchantId} is shown on the Scan to Pay Portal home page after first login.

Where the password lives

API passwords are not emailed. They're generated in the Scan to Pay Portal:

1. Log in to the Scan to Pay Portal — sandbox or production — with the administrator email you supplied during onboarding.
2. Open the API tab.
3. Generate a new API password.

Generating a new password invalidates the previous one immediately — all in-flight requests using the old password will start failing with 401 Bad Credentials. Treat rotation as a deploy-coordinated event.

Example request

curl -u "merchant-25:your-api-password" \
  -X POST https://qa.scantopay.io/pluto/code/create \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantReference": "auth-demo",
    "amount": 10.00
  }'

When to rotate

There's no automatic password expiry. Rotate proactively in three scenarios:

• After a suspected credential leak
• When a team member with API access leaves
• On a calendar cadence appropriate to your security policy (industry norm: every 90 days)

JWT Bearer with PKI

A stronger alternative to Basic Auth. Instead of presenting a long-lived password on every request, you exchange a public/private RSA key pair with Scan to Pay once, then perform a challenge-response flow to obtain a short-lived JWT, which you present on subsequent API requests.

When to use this

Choose JWT Bearer when any of the following apply:

• You're a bank, large fintech, or regulated PSP whose security review requires mutual TLS-equivalent trust
• You want to rotate credentials without coordinating with the Scan to Pay support team each time (you control the private key)
• Your platform already issues JWTs for other integrations and you want a consistent pattern

For everyone else, Basic Auth is fine and much simpler.

Prerequisites (one-time setup)

1. Generate a 4096-bit RSA keypair. Store the private key in your secrets manager. Never share it.

   Bash

   openssl req -nodes -x509 -sha256 -newkey rsa:4096 \
     -keyout PrivateKey.key -out PublicKey.crt -days 99999

2. Extract your public key as base64:

   Bash

   openssl x509 -in PublicKey.crt -pubkey -noout \
     | grep -v "\-\-\-" | base64 -d | base64 -w0

3. Send your public key to Scan to Pay support ([email protected]). Ask them to:

   • Configure the public key against your manager identity
   • Switch your auth type from Basic to Bearer
   • Send you Scan to Pay's public key out of band (you'll need it to verify the server)

4. Verify you've received Scan to Pay's public key through a trusted channel before proceeding.

The challenge–response flow

Once configured, every login does four steps:

1. Generate a client challenge. Generate 64 bytes of random data. Encrypt with Scan to Pay's public key using RSA/ECB/OAEPWithSHA-1AndMGF1Padding. Base64-encode. URL-encode for query string (+ becomes space if you don't).

   Store a SHA256 hash of the pre-encrypted 64 bytes — you'll use it to verify the server's response.

2. Call the login-challenges endpoint:

   Bash

   curl "https://qa.scantopay.io/authentication/login-challenges?identity=your-identity&clientChallenge=<urlencoded-base64>"

   Response:

   JSON

   {
     "expires": "2026-05-14T16:07:13.020Z",
     "base64EncodedChallenge": "<server's challenge to you>",
     "base64EncodedClientChallengeResponse": "<server's proof it has STP private key>"
   }

3. Verify the server. Check that base64EncodedClientChallengeResponse matches the SHA256 hash you stored in step 1. If they don't match, stop — you may not be talking to Scan to Pay. If they match, decrypt base64EncodedChallenge with your private key, then SHA256-hash the decrypted bytes.

4. Post the login request with the challenge response and your password:

   Bash

   curl -X POST https://qa.scantopay.io/authentication/login \
     -H 'Content-Type: application/json' \
     -d '{
       "identity": "your-identity",
       "password": "your-password",
       "base64EncodedChallengeHash": "<sha256 of the encrypted server challenge>",
       "base64EncodedChallengeResponse": "<sha256 of the decrypted server challenge>"
     }'

   Response:

   JSON

   {
     "headerName": "Authorization",
     "headerValue": "Bearer eyJhbGci...<snip>...",
     "sessionId": "c056b2d8-d6d1-4ea6-8752-e87f684b2903",
     "expires": "2026-05-14T16:30:13.341Z"
   }

5. Use the token on subsequent Scan to Pay API requests:

   Bash

   curl -X POST https://qa.scantopay.io/pluto/code/create \
     -H "Authorization: Bearer eyJhbGci...<snip>..." \
     -H 'Content-Type: application/json' \
     -d '{ "merchantReference": "jwt-demo", "amount": 10.00 }'

Time windows

The challenge issued in step 2 has a short lifetime. Complete the login (step 4) within:

• Sandbox: 600 seconds (10 minutes)
• Production: 60 seconds

Cache the returned JWT in memory and re-run the flow before it expires. The token's expires field tells you when it will be rejected.

What you can call

Scan to Pay enforces path-level access based on which role your account has. Most integrators only need EXTERNAL access.

If your call returns 403 Forbidden, you're authenticated correctly but your account doesn't have the right role for that path.

Common errors

Going from Basic to JWT

There's no "use both" mode. Migration is one-way per account:

1. Pick a window during which you can tolerate downtime if anything goes wrong.
2. Send Scan to Pay support your public key and ask for Bearer mode.
3. Support flips the switch. Your existing Basic Auth password stops working at this moment.
4. Run the challenge–response flow and start using JWTs.

If you have multiple accounts (e.g. one per environment), migrate non-production first.

📘

Tip: Most integrators run two parallel accounts — one Basic-only for legacy scripts and CI, one Bearer-only for production traffic. Different merchantId, different credentials, same backend logic.

What's next

• Make your first authenticated request → Quickstart
• Switch the test app and try in sandbox → Sandbox and test cards
• Find the right path for what you're trying to do → Choose your integration
• Handle webhook signature verification → Signing and verifying webhooks