Notifications

The notifications endpoints are the programmatic version of the Portal's Notifications screen. Use them to wire up webhook delivery for a merchant, add Email/SMS recipients for human notifications, and rotate the encryption key used to sign webhook payloads.

For the broader webhook story (payload shape, acknowledgement rules, decryption), see Webhooks and Signing and verifying webhooks.

Endpoints

All endpoints require the target merchant to be in ACTIVE state.

Configure or update the webhook URL

addHttp is the workhorse: it adds a webhook URL if none is set, or updates the URL / version if one already is. On first-time setup it also generates the encryption key. On update of an existing URL, the existing key is preserved.

Request:

curl -X POST https://qa.scantopay.io/portal/restful/merchant/notification/addHttp \
  -u 'PSP_42:yourPspApiPassword' \
  -H 'Content-Type: application/json' \
  -d '{
    "merchantId": 25,
    "url": "https://merchant.example/webhooks/scan-to-pay",
    "version": "V3"
  }'

Fields:

Response — first-time setup:

{
  "merchantId": 25,
  "url": "https://merchant.example/webhooks/scan-to-pay",
  "version": "V3",
  "encryptKey": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
}

The encryptKey is the only time you'll see it — store it securely. Subsequent calls return the existing key only if you re-configure with the same URL.

Response — update with new URL:

If you supply a url different from the current one (or change the version), the platform validates the new URL, updates the record, and returns the existing encryption key (not a new one):

{
  "merchantId": 25,
  "url": "https://merchant.example/webhooks/v2/scan-to-pay",
  "version": "V3",
  "encryptKey": "A1B2C3D4E5F6A7B8C9D0E1F2A3B4C5D6"
}

Common errors:

Rotate the webhook key

When you want a fresh encryption key without changing the URL — typically because the existing key is suspected to be compromised, or as part of a regular rotation policy.

Request:

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

Response:

{
  "merchantId": 25,
  "url": "https://merchant.example/webhooks/scan-to-pay",
  "version": "V3",
  "encryptKey": "F1E2D3C4B5A69788A9B0C1D2E3F4A5B6"
}

⚠️

The new key is active immediately. Webhooks delivered after the rotation will be encrypted with the new key. Update your receiver to accept either key for a transition window, then retire the old key once you're confident no in-flight notifications still use it.

Common errors:

Add an Email or SMS recipient

For human-facing notifications (not webhooks). The platform delivers transaction notifications to Email or SMS recipients in addition to the HTTP webhook.

Request:

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

Fields:

Response: the full updated notification list (see List notifications).

Common errors:

📘

There's no separate "remove recipient" endpoint via Portal API. To remove an Email or SMS recipient, use the Portal UI — log in → email dropdown → Notifications.

List notifications

Returns every notification configured on a merchant — the HTTP webhook URL plus all Email/SMS recipients.

Request:

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

Response:

[
  {
    "type": "HTTP",
    "value": "https://merchant.example/webhooks/scan-to-pay",
    "version": "V3"
  },
  {
    "type": "EMAIL",
    "value": "[email protected]"
  },
  {
    "type": "SMS",
    "value": "27832006283"
  }
]

The HTTP row's encryptKey is not returned by this endpoint — keys are only exposed at the moment they're created or rotated via addHttp / renewKey. If you've lost the key, rotate it.

What's next

• Webhook payload shape and acknowledgement rules → Webhooks
• Decrypt and verify the encrypted webhook body → Signing and verifying webhooks
• Rotate the merchant's API password → API credentials
• Cross-cutting rules → Business rules