Webhooks

Webhooks are automated notifications generated by system events that occur in your organization. You can create a webhook subscription and designate a URL to receive notifications when a sale status updates. By setting up automatic webhook notifications, you do not need to send check status requests to monitor a sale status.

Webhook notifications are only sent when a sale status changes.

You must be set up for message-level encryption to receive webhook notifications. Notifications that contain sensitive, personally identifiable information (PII), such as account numbers, are sent using message-level encryption. To set up message-level encryption, see Set Up a JSON Web Token Message Using P12 Certificates - Enable Message-Level Encryption.

Transport Layer Security (TLS) is required to ensure data integrity.

Endpoints

Send a POST request to one of these endpoints:

POST /notification-subscriptions/v2/webhooks

Test Your Webhook Requests

You can use the REST API Reference to send webhook-related test requests. See the Create a Webhook section in the REST API Reference.

Example

This section shows examples of successful webhook responses for PayTo Pay by Bank.

{    "name": "My Custom Webhook",    "description": "Sample Webhook from Developer Center",    "organizationId": "paytotestapm003",    "productId": "alternativePaymentMethods",    "eventTypes": [        "payments.payments.updated"    ],    "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",    "notificationScope": "SELF",    "securityPolicy": {        "securityType": "KEY",        "proxyType": "external"    }}

{    "eventType": "payments.payments.updated",    "webhookId": "4a9df9ed-b20a-5521-e063-a3588d0a851d",    "productId": "alternativePaymentMethods",    "organizationId": "paytotestapm003",    "eventDate": "2026-02-12T13:44:01",    "transactionTraceId": "435ad79928ced797f5764baf587e70fd17992f35e205134ce8b128a37bf347ed",    "retryNumber": 0,    "payload": {        "processingInformation": {            "linkId": 7709037965466418704807        },        "message": "Request was processed successfully.",        "responseCode": "00005",        "processorInformation": {            "responseCode": "00005"        },        "status": "FUNDED",        "id": "7709038107206054703814",        "submitTimeUtc": "2026-02-12T13:43:30Z"    },    "requestType": "NEW",    "metadata": {        "version": "1.0"    }}

{    "eventType": "payments.payments.updated",    "webhookId": "4a9df9ed-b20a-5521-e063-a3588d0a851d",    "productId": "alternativePaymentMethods",    "organizationId": "paytotestapm003",    "eventDate": "2026-02-12T19:08:54",    "transactionTraceId": "587a5de008bf6ca873cdd81c7be31b4e6b2d5dc7fe5fed7bc380cbc015349677",    "retryNumber": 0,    "payload": {        "processingInformation": {            "linkId": 7709233228416545904807        },        "message": "Request was processed successfully.",        "status": "ACTIVE",        "responseCode": "00015",        "id": "7709233345896495103813",        "submitTimeUtc": "2026-02-12T19:08:54Z"    },    "requestType": "NEW",    "metadata": {        "version": "1.0"    }}

{    "eventType": "payments.payments.updated",    "webhookId": "4a9df9ed-b20a-5521-e063-a3588d0a851d",    "productId": "alternativePaymentMethods",    "organizationId": "paytotestapm003",    "eventDate": "2026-02-12T19:18:45",    "transactionTraceId": "b5a75536feece2a7b75a9ee15fcd2b03e7dda08216232c7f272f5b9a1781c9a6",    "retryNumber": 0,    "payload": {        "processingInformation": {            "linkId": 7709239212266031404806        },        "message": "Request was processed successfully.",        "responseCode": "00006",        "processorInformation": {            "responseCode": "00006"        },        "status": "REFUNDED",        "id": "7709239255426728603813",        "submitTimeUtc": "2026-02-12T19:18:45Z"    },    "requestType": "NEW",    "metadata": {        "version": "1.0"    }}

Field	Type	Description
`description`		For more information, see the description field reference.
`name`
`organizationId`
`eventTypes`		Set the value of this field to `payments.payments.updated`.
`productId`		Set the value of this field to `alternativePaymentMethods`.
`securityPolicy.securityType`		Set to `KEY`.
`webhookUrl`

Optional Fields

Field	Type	Description
`deactivateflag`		Required if the `healthCheckUrl` field is present. Set to `true` to automatically activate the subscription.
`healthCheckUrl`		Set to the health check URL. Required to auto-activate the subscription. If you do not include this field, the created subscription is inactive. An inactive subscription does not send notifications.
`retryPolicy.deactivateFlag`
`retryPolicy.firstRetry`
`retryPolicy.interval`
`retryPolicy.numberOfRetries`
`retryPolicy.repeatSequenceCount`
`retryPolicy.repeatSequenceWaitTime`

Notification Statuses

Webhook subscriptions send these notification statuses:

CANCELLED: The customer did not complete the checkout using the redirect URL.

FAILED: The sale request failed.

FUNDED: The sale request is funded for the requested amount.

SETTLE_INITIATED: The customer completed checkout and PayTo Pay by Bank is processing the sale.

SETTLED: The sale is settled for the requested amount.

Was this page helpful?

Last published: September 29, 2026