In this section, we’ll delve into the webhook API operations, encompassing the processes of webhook creation, webhook list retrieval, and webhook updates, covering various aspects such as the operation method, endpoint, and request details.
Create webhook
In this segment we will explore the process of creating webhooks, outlining the necessary steps, parameters, and authentication details.
Endpoints:
| Operation | Operation Type | Operation Method & Endpoint | Operation Description |
|---|---|---|---|
| Create Webhook Request | Call | POST version-id/acquirers/{acquirer-id}/merchants/{merchant-id}/terminal/webhook | Set up a Webhook creation resource. |
The following table presents the details required for initiating a Create Webhook operation:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Path | acquirer-id | Max25NumericText | Mandatory | Acquirer code |
| Path | merchant-id | Max10NumericText | Mandatory | Acquirer code |
| Query Parameter | acceptorId | Max10NumericText | Optional | Acceptor code in Merchant |
| Query Parameter | terminalId | Max10NumericText | Optional | Terminal code |
Header parameters:
| Data Element | Type | Condition | Description |
|---|---|---|---|
| Content-Type | String | Mandatory | application/json |
| Authorization | String | Mandatory | Bearer Token. Based on OAuth2 authentication performed in a pre-step. |
| x-ibm-client-id | String | Mandatory | Token that identifies a client organisation. It is provided during onboarding process and must be used in every call. |
| TPP-Request-ID | String | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
| User-ID | String | Mandatory | Identification of the user responsible for the request (required for audit purposes). |
| User-Organization-ID | String | Mandatory | Identification of the organization responsible for the request (required for audit purposes). |
Request parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Body | notificationConfigurationCode | Max35Text | Mandatory | Notification configuration UUID. |
| Request Body | requestOperationType | Max3Text | Mandatory | Request operation type code Enum: INS – Insert DEL – Delete Set with ‘INS’. |
| Request Body | paymentMethods | Payment methods | Mandatory | Array of payment methods. |
| Request Body.paymentMethods | paymentMethodNotificationCode | Max15Text | Mandatory | Payment method notification type code Enum: CARD-‘Card Payments’ PYBL-‘Pay By Link – Blue Media’ PLKV-‘Pay By Link – kevin’ BLIK-‘BLIK’ XPAY-‘XPAY Payments’ GRPY-‘Giropay’ SFRT-‘Sofort’ BNCT-‘Bancontact’ IDEL-‘Ideal’ |
| Request Body | channelTypeNotification | Channel Type Notification | Mandatory | It comprises all channel type notification related data. |
| Request Body.channelTypeNotification | notificationType | Max5Text | Mandatory | Notification type code Enum: URL |
| Request Body.channelTypeNotification | value | Max2048Text | Mandatory | Notification value (email or URL) |
| Request Body.channelTypeNotification | security | Security | Conditional | It comprises all security related data. This structure (and all related data elements only) should be presented if Notification type code value is ‘URL’. |
| Request Body.channelTypeNotification.security | key | Max32Text (Base64) | Conditional | Security key (secret). |
| Request Body.channelTypeNotification.security | supportEmail | Max256Text | Conditional | Support email. |
| Request Body.channelTypeNotification.security | algorithm | Max70Text | Conditional | Algorithm. Set with ‘AES-256-GCM’. |
Here, you can review the response structure resulting from the Create Webhook operation:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Response Header | TPP-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
| Response Body | transactionStatus | Transaction Status | Mandatory | Transaction Status. Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”. |
| Response Body | returnStatus | Return Status | Mandatory | |
| Response Body.returnStatus | statusCode | Message Code | Mandatory | “000” for success. Values different from “000” refer to errors. |
| Response Body.returnStatus | statusMsg | Message Type | Mandatory | Result message. |
| Response Body.returnStatus | statusDescription | Max512Text | Mandatory | Additional explaining text. |
Get webhook list
In this section, we provide the details on the Get Webhook List operation, encompassing the operation method, endpoint, and necessary elements to retrieve a list of webhooks, with both the API request and response structures for your reference.
| Operation | Operation Type | Operation Method & Endpoint | Operation Description |
|---|---|---|---|
| Get Webhook List Request | Call | POST version-id/webhooks | Get webhook list. |
The table below outlines the required data elements and their conditions for initiating the request.
Header parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Header | Content-Type | String | Mandatory | application/json |
| Request Header | Authorization | String | Mandatory | Bearer Token. Based on OAuth2 authentication performed in a pre-step. |
| Request Header | x-ibm-client-id | String | Mandatory | Token that identifies a client organization. It is provided during onboarding process and must be used in every call. |
| Request Header | TPP-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
| Request Header | User-ID | String | Mandatory | Identification of the user responsible for the request (required for audit purposes). |
| Request Header | User-Organization-ID | String | Mandatory | Identification of the organization responsible for the request (required for audit purposes). |
Request parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Body | acquirerId | Max25NumericText | Mandatory | Acquirer code |
| Request Body | merchantId | Max10NumericText | Mandatory | Merchant code |
| Request Body | acceptorId | Max10NumericText | Optional | Acceptor code |
| Request Body | terminalId | Max10NumericText | Optional | Terminal code |
This table outlines the expected response elements:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Response Header | TPP-Request-ID | UUID | Mandatory | ID of the Response, unique to the call, as determined by the initiating party. |
| Response Body | transactionStatus | Transaction Status | Mandatory | Transaction Status. Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”. |
| Response Body | returnStatus | Return Status | Mandatory | |
| Response Body.returnStatus | statusCode | Status Code | Mandatory | “000” for success. Values different from “000” refer to errors. |
| Response Body.returnStatus | statusMsg | Message Type | Mandatory | Result message. |
| Response Body.returnStatus | statusDescription | Max512Text | Mandatory | Additional explaining text. |
| Response Body | webhooks | Array of webhooks | Conditional | Webhook details resource data list. Only present in success responses. |
| Response Body.webhooks | webhook | Webhook | Mandatory | Array webhooks. |
| Response Body.webhooks.webhook | notificationConfigurationCode | Max36Text | Mandatory | Notification configuration UUID. |
| Response Body | paymentMethods | payment methods | Mandatory | Array of payment methods. |
| Response Body.paymentMethods | paymentMethodNotificationCode | Max15Text | Mandatory | Payment method notification type code Enum: CARD-‘Card Payments’ PYBL-‘Pay By Link – Blue Media’ PLKV-‘Pay By Link – kevin’ BLIK-‘BLIK’ XPAY-‘XPAY Payments’ BNPL-‘Buy Now Pay Later -Paywerk’ GRPY-‘Giropay’ SFRT-‘Sofort’ BNCT-‘Bancontact’ IDEL-‘Ideal’ |
| Response Body.webhooks.webhook | channelTypeNotification | Channel Type Notification | Mandatory | It comprises all channel type notification related data. |
| Response Body.webhooks.webhook.channelTypeNotification | notificationType | Max5Text | Mandatory | Notification type code Enum: URL |
| Response Body.webhooks.webhook.channelTypeNotification | value | Max2048Text | Mandatory | Notification value (email or URL). |
| Response Body.webhooks.webhook.channelTypeNotification | security | Security | Conditional | It comprises all security related data. This structure (and all related data elements only) should be presented if Notification type code value is ‘URL’. |
| Response Body.webhooks.webhook.channelTypeNotification.security | key | Max32Text (Base64) | Conditional | Security key (secret). |
| Response Body.webhooks.webhook.channelTypeNotification.security | supportEmail | Max256Text | Conditional | Support email. |
| Response Body.webhooks.webhook.channelTypeNotification.security | algorithm | Max70Text | Conditional | Algorithm. |
Update webhooks
Here we address the operation method, endpoint, and relevant elements required for modifying a webhook resource. This includes a coverage of the API request and response structures for your reference.
| Operation | Operation Type | Operation Method & Endpoint | Operation Description |
|---|---|---|---|
| Update Webhook Request | Call | PUT version-id/acquirers/{acquirer-id}/merchants/{merchant-id}/terminal/webhook | Update a Webhook resource. |
The following table presents the essential elements for initiating an Update Webhook request:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Path | acquirer-id | Max25NumericText | Mandatory | Acquirer code. |
| Path | merchant-id | Max10NumericText | Mandatory | Merchant code. |
| Query Parameter | acceptorId | Max10NumericText | Optional | Acceptor code in Merchant. |
| Query Parameter | terminalId | Max10NumericText | Optional | Terminal code. |
Header parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Header | Content-Type | String | Mandatory | application/json |
| Request Header | Authorization | String | Mandatory | Bearer Token. Based on OAuth2 authentication performed in a pre-step. |
| Request Header | x-ibm-client-id | String | Mandatory | Token that identifies a client organisation. It is provided during onboarding process and must be used in every call. |
| Request Header | TPP-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
| Request Header | User-ID | String | Mandatory | Identification of the user responsible for the request (required for audit purposes). |
| Request Header | User-Organization-ID | String | Mandatory | Identification of the organization responsible for the request (required for audit purposes). |
Request parameters:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Request Body | notificationConfigurationCode | Max35Text | Mandatory | Notification configuration UUID. |
| Request Body | requestOperationType | Max3Text | Mandatory | Request operation type code Enum: INS – Insert DEL – Delete Set with ‘INS’. |
| Request Body | paymentMethods | payment methods | Mandatory | Array of payment methods. |
| Request Body.paymentMethods | paymentMethodNotificationCode | Max15Text | Mandatory | Payment method notification type code Enum: CARD-‘Card Payments’ PYBL-‘Pay By Link – Blue Media’ PLKV-‘Pay By Link – kevin’ BLIK-‘BLIK’ XPAY-‘XPAY Payments’ BNPL-‘Buy Now Pay Later -Paywerk’ GRPY-‘Giropay’ SFRT-‘Sofort’ BNCT-‘Bancontact’ IDEL-‘Ideal’ |
| Request Body | channelTypeNotification | Channel Type Notification | Mandatory | It comprises all channel type notification related data. |
| Request Body.channelTypeNotification | notificationType | Max5Text | Mandatory | Notification type code Enum: URL |
| Request Body.channelTypeNotification | value | Max2048Text | Mandatory | Notification value (email or URL) |
| Request Body.channelTypeNotification | security | Security | Conditional | It comprises all security related data. This structure (and all related data elements only) should be presented if Notification type code value is ‘URL’. |
| Request Body.channelTypeNotification.security | key | Max32Text | Conditional | Security key (secret). |
| Request Body.channelTypeNotification.security | supportEmail | Max256Text | Conditional | Support email. |
| Request Body.channelTypeNotification.security | algorithm | Max70Text | Conditional | Algorithm. Set with ‘AES-256-GCM’. |
This table outlines the response components for the Update Webhook operation:
| Location | Data Element | Type | Condition | Description |
|---|---|---|---|---|
| Response Header | TPP-Request-ID | UUID | Mandatory | ID of the request, unique to the call, as determined by the initiating party. |
| Response Body | transactionStatus | Transaction Status | Mandatory | Transaction Status. Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”. |
| Response Body | returnStatus | Return Status | Mandatory | |
| Response Body.returnStatus | statusCode | Message Code | Mandatory | “000” for success. Values different from “000” refer to errors. |
| Response Body.returnStatus | statusMsg | Message Type | Mandatory | Result message. |
| Response Body.returnStatus | statusDescription | Max512Text | Mandatory | Additional explaining text. |