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’  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: EMAIL 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’ 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: EMAIL 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’ 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: EMAIL 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.