Webhook Subscriptions

Webhooks are automated notifications generated by system events that occur in your organizations. You can enroll in a sale or refund event and designate a URL to receive notifications when the event updates. You set up your webhook subscriptions only once.

Webhooks are supported only with the REST API. If you are integrating with the Pay by Bank Simple Order API, consider the APIs when integrating webhooks.

Notifications that contain sensitive, personally identifiable information such as account numbers are sent using message-level encryption.

Transport Layer Security is required in order to ensure data integrity.

Endpoints

Production
:

https://api.cybersource.com/notification-subscriptions/v2/webhooks

Test
:

https://apitest.cybersource.com/notification-subscriptions/v1/webhooks

Notification Statuses

Webhook subscriptions send these status notifications:

ABANDONED

: The customer did not complete the transaction.

CANCELLED

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

COMPLETED

: The transaction is complete.

FAILED

: The payment failed.

PENDING

: The payment was initiated.

REFUNDED

: The settled amount is successfully refunded.

SETTLED

: The sale request is settled for the requested amount.

Additional Requirements

Webhooks API Developer Guide: There are additional requirements for implementing webhooks that are not discussed in this guide. For more information, see the Webhooks Implementation Guide
for the REST API.
Create New Webhooks: To create an alternative payment notification webhook, see the Create a Webhook section in the Cybersource REST API Reference
.

Required Fields for Subscribing to a Webhook

healthCheckUrl
organizationId
products.eventTypes: Set to
payments.payments.updated
.
products.productId: Set to
alternativePaymentMethods
.
webhookUrl

REST
Example: Subscribing to a Webhook

There are additional requirements for implementing webhooks that are not discussed in this guide. For more information, see the Webhooks Implementation Guide
for the REST API.

Request

{
  "name": "My Custom Webhook",
  "description": "Sample Webhook from Developer Center",
  "organizationId": "organizationId",
  "productId": "alternativePaymentMethods",
  "eventTypes": [
      "payments.payments.updated"
  ],
  "webhookUrl": "https://MyWebhookServer.com:8443/simulateClient",
  "healthCheckUrl": "https://MyWebhookServer.com:8443/simulateClientHealthCheck",
  "notificationScope": "SELF",
  "retryPolicy": {
      "algorithm": "ARITHMETIC",
      "firstRetry": 1,
      "interval": 1,
      "numberOfRetries": 3,
      "deactivateFlag": "false",
      "repeatSequenceCount": 0,
      "repeatSequenceWaitTime": 0
  },
  "securityPolicy": {
      "securityType": "KEY",
      "proxyType": "external"
      }
  }

Encrypted Response to Successful Request

{
  "eventType": "payments.payments.updated",
  "productId": "alternativePaymentMethods",
  "organizationId": "organizationId",
  "transactionTraceId": "6584251287300178228949",
  "payload": "{CBC}nL1LK67IH1LQKad3qyhilPoeDGrHo/6ClIZ17HSC5YX9TQFIgCOhVPi139kmB/xiVCALGdU8YjqmOEwo3iUXKy6oq517eDiTHv/Crq0pOiEzs0dtuTvYhriXrpvQCF+XxqfqTPPFyus/10/FlyEK7ZKIc66DrmA3IfdlYTpL7gICAOttQrMWNGODFu7JXaFyQahDarhFCPsvWMwyRK9yOLwihWj3lC1yPD/1xA7xpTGp9kX3ABKzzZxKjHoC5OYOhSLQm7MPnN4BND+Hs+cU/mYzLYxfN7GSDSbqZwhbJgXaKapT8lMeXUTlPejyqGyCPagWNqZJFHx6q1OBJKB8XZ0pZIpT+v+bMe5EnbQyv9Nj6BJX1BBgqhvKmXrSqD16",
      "metadata": {
          "notificationTypeID": "5",
          "notificationReason": "payment"
      }
  }

Decrypted Response to Successful Request

{
  "id": "6584251287300178228949",
  "reconcillationID": "85100194sale",
  "status": "settled",
  "submitTimeUTC": "2022-07-21T17:38:48Z",
  "clientReferenceInformation.code": "TC85100-1",
  "orderInformation.amountDetails.totalAmount": "1999.99",
  "orderInformation.amountDetails.currency": "GBP"
  
  }