API credentials

This page covers rotation of the merchant's API password — the credential a merchant uses on Basic-Auth calls to the Remote API, Querying transactions, and other Scan to Pay transactional APIs. It's separate from the Portal login credential and separate from the webhook encryption key.

For the broader credential story, see Authentication.

Endpoint

Merchant must be in ACTIVE state.

Rotate the API password

Request:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/renewApiKey \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{ "merchantId": 25 }'

Request fields:

Response:

{
  "merchantId": 25,
  "apiKey": "4F8B2A6C1D3E9F7B2A6C1D3E9F7B2A6C"
}

The new password is a 32-character hex string (16 random bytes, base16-encoded, uppercase). It's the only time the password is returned — store it securely.

⚠️

Rotation is immediate. The previous password stops working the instant this call returns. Coordinate your deploy so the new password is in your config before the rotation, or schedule a maintenance window.

Common errors

A safe rotation flow

To avoid downtime when rotating in production:

1. Decide on a cutover window — typically a low-traffic period
2. Update your application config / secret manager with the new password slot, but keep the old one active
3. Call /restful/merchant/renewApiKey — capture the response, push the new password into the active slot
4. Verify by making a benign call against the Remote API with the new password (e.g. getTransactionState for a recent transaction)
5. Decommission the old password (you don't need to do anything — it's invalid the moment the rotation completes)

If your application caches credentials in-memory, restart workers / pods after the rotation so they pick up the new password.

Related credentials

What's next

• Use the new password against the Remote API → Remote API overview
• Rotate the webhook key too → Notifications
• Generate in-app SDK tokens → Lib Lite tokens
• Cross-cutting rules → Business rules