Skip to content

API operations

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:
OperationOperation TypeOperation Method & EndpointOperation Description
Create Webhook RequestCallPOST version-id/acquirers/{acquirer-id}/merchants/{merchant-id}/terminal/webhookSet up a Webhook creation resource.

The following table presents the details required for initiating a Create Webhook operation:

LocationData ElementTypeConditionDescription
Pathacquirer-idMax25NumericTextMandatoryAcquirer code
Pathmerchant-idMax10NumericTextMandatoryAcquirer code
Query ParameteracceptorIdMax10NumericTextOptionalAcceptor code in Merchant
Query ParameterterminalIdMax10NumericTextOptionalTerminal code
Header parameters:
Data ElementTypeConditionDescription
Content-TypeStringMandatoryapplication/json
AuthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
x-ibm-client-idStringMandatoryToken that identifies a client organisation. It is provided during onboarding process and must be used in every call.
TPP-Request-IDStringMandatoryID of the request, unique to the call, as determined by the initiating party. 
User-IDStringMandatoryIdentification of the user responsible for the request (required for audit purposes).
User-Organization-IDStringMandatoryIdentification of the organization responsible for the request (required for audit purposes). 
Request parameters:
LocationData ElementTypeConditionDescription
Request BodynotificationConfigurationCodeMax35TextMandatoryNotification configuration UUID.
Request BodyrequestOperationTypeMax3TextMandatoryRequest operation type code
Enum:
INS – Insert
DEL – Delete
Set with ‘INS’.
Request BodypaymentMethodsPayment methodsMandatoryArray of payment methods.
Request Body.paymentMethodspaymentMethodNotificationCodeMax15TextMandatoryPayment 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 BodychannelTypeNotificationChannel Type Notification MandatoryIt comprises all channel type notification related data.
Request Body.channelTypeNotificationnotificationTypeMax5TextMandatoryNotification type code
Enum:
EMAIL
URL
Request Body.channelTypeNotificationvalueMax2048TextMandatoryNotification value (email or URL)
Request Body.channelTypeNotificationsecuritySecurityConditionalIt 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.securitykeyMax32Text (Base64)ConditionalSecurity key (secret).
Request Body.channelTypeNotification.securitysupportEmailMax256TextConditionalSupport email.
Request Body.channelTypeNotification.securityalgorithmMax70TextConditionalAlgorithm.
Set with ‘AES-256-GCM’.

Here, you can review the response structure resulting from the Create Webhook operation:

LocationData ElementTypeConditionDescription
Response HeaderTPP-Request-IDUUIDMandatoryID of the request, unique to the call, as determined by the initiating party.
Response BodytransactionStatusTransaction StatusMandatoryTransaction Status. 
Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”.
Response Body returnStatusReturn StatusMandatory
Response Body.returnStatusstatusCodeMessage Code Mandatory“000” for success. Values different from “000” refer to errors.
Response Body.returnStatusstatusMsgMessage TypeMandatoryResult message.
Response Body.returnStatusstatusDescriptionMax512TextMandatoryAdditional 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.

OperationOperation TypeOperation Method & EndpointOperation Description
Get Webhook List RequestCallPOST version-id/webhooksGet webhook list.

The table below outlines the required data elements and their conditions for initiating the request.

Header parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json 
Request HeaderAuthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Headerx-ibm-client-idStringMandatoryToken that identifies a client organization. It is provided during onboarding process and must be used in every call.
Request HeaderTPP-Request-IDUUIDMandatoryID of the request, unique to the call, as determined by the initiating party. 
Request Header User-IDStringMandatoryIdentification of the user responsible for the request (required for audit purposes). 
Request HeaderUser-Organization-IDStringMandatoryIdentification of the organization responsible for the request (required for audit purposes). 
Request parameters:
LocationData ElementTypeConditionDescription
Request BodyacquirerIdMax25NumericTextMandatoryAcquirer code
Request BodymerchantIdMax10NumericTextMandatoryMerchant code
Request BodyacceptorIdMax10NumericTextOptionalAcceptor code
Request BodyterminalIdMax10NumericTextOptionalTerminal code

This table outlines the expected response elements:

LocationData ElementTypeConditionDescription
Response HeaderTPP-Request-IDUUIDMandatoryID of the Response, unique to the call, as determined by the initiating party. 
Response BodytransactionStatusTransaction StatusMandatoryTransaction Status. 
Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”.
Response Body returnStatusReturn StatusMandatory
Response Body.returnStatusstatusCodeStatus Code Mandatory“000” for success. Values different from “000” refer to errors.
Response Body.returnStatusstatusMsgMessage TypeMandatoryResult message.
Response Body.returnStatusstatusDescriptionMax512TextMandatoryAdditional explaining text.
Response BodywebhooksArray of webhooksConditionalWebhook details resource data list.
Only present in success responses.
Response Body.webhookswebhookWebhookMandatoryArray webhooks.
Response Body.webhooks.webhooknotificationConfigurationCodeMax36TextMandatoryNotification configuration UUID.
Response BodypaymentMethodspayment methodsMandatoryArray of payment methods.
Response Body.paymentMethodspaymentMethodNotificationCodeMax15TextMandatoryPayment 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.webhookchannelTypeNotificationChannel Type Notification MandatoryIt comprises all channel type notification related data.
Response Body.webhooks.webhook.channelTypeNotificationnotificationTypeMax5TextMandatoryNotification type code
Enum:
EMAIL
URL
Response Body.webhooks.webhook.channelTypeNotificationvalueMax2048TextMandatoryNotification value (email or URL).
Response Body.webhooks.webhook.channelTypeNotificationsecuritySecurityConditionalIt 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.securitykeyMax32Text (Base64)ConditionalSecurity key (secret).
Response Body.webhooks.webhook.channelTypeNotification.securitysupportEmailMax256TextConditionalSupport email.
Response Body.webhooks.webhook.channelTypeNotification.securityalgorithmMax70TextConditionalAlgorithm.

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.

OperationOperation TypeOperation Method & EndpointOperation Description
Update Webhook RequestCallPUT version-id/acquirers/{acquirer-id}/merchants/{merchant-id}/terminal/webhookUpdate a Webhook resource.

The following table presents the essential elements for initiating an Update Webhook request:

LocationData ElementTypeConditionDescription
Pathacquirer-idMax25NumericTextMandatoryAcquirer code.
Pathmerchant-idMax10NumericTextMandatoryMerchant code.
Query ParameteracceptorIdMax10NumericTextOptionalAcceptor code in Merchant.
Query ParameterterminalIdMax10NumericTextOptionalTerminal code.
Header parameters:
LocationData ElementTypeConditionDescription
Request HeaderContent-TypeStringMandatoryapplication/json
Request HeaderAuthorizationStringMandatoryBearer Token. Based on OAuth2 authentication performed in a pre-step.
Request Headerx-ibm-client-idStringMandatoryToken that identifies a client organisation. It is provided during onboarding process and must be used in every call.
Request HeaderTPP-Request-IDUUIDMandatoryID of the request, unique to the call, as determined by the initiating party. 
Request HeaderUser-IDStringMandatoryIdentification of the user responsible for the request (required for audit purposes). 
Request HeaderUser-Organization-IDStringMandatoryIdentification of the organization responsible for the request (required for audit purposes). 
Request parameters:
LocationData ElementTypeConditionDescription
Request BodynotificationConfigurationCodeMax35TextMandatoryNotification configuration UUID.
Request BodyrequestOperationTypeMax3TextMandatoryRequest operation type code
Enum:
INS – Insert
DEL – Delete
Set with ‘INS’.
Request BodypaymentMethodspayment methodsMandatoryArray of payment methods.
Request Body.paymentMethodspaymentMethodNotificationCodeMax15TextMandatoryPayment 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 BodychannelTypeNotificationChannel Type Notification MandatoryIt comprises all channel type notification related data.
Request Body.channelTypeNotificationnotificationTypeMax5TextMandatoryNotification type code
Enum:
EMAIL
URL
Request Body.channelTypeNotificationvalueMax2048TextMandatoryNotification value (email or URL)
Request Body.channelTypeNotificationsecuritySecurityConditionalIt 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.securitykeyMax32TextConditionalSecurity key (secret).
Request Body.channelTypeNotification.securitysupportEmailMax256TextConditionalSupport email.
Request Body.channelTypeNotification.securityalgorithmMax70TextConditionalAlgorithm.
Set with ‘AES-256-GCM’.

This table outlines the response components for the Update Webhook operation:

LocationData ElementTypeConditionDescription
Response HeaderTPP-Request-IDUUIDMandatoryID of the request, unique to the call, as determined by the initiating party.
Response BodytransactionStatusTransaction StatusMandatoryTransaction Status. 
Possible values are “ACTC-Accepted Technical Validation” and “RJCT-Rejected”.
Response Body returnStatusReturn StatusMandatory
Response Body.returnStatusstatusCodeMessage CodeMandatory“000” for success. Values different from “000” refer to errors.
Response Body.returnStatusstatusMsgMessage TypeMandatoryResult message.
Response Body.returnStatusstatusDescriptionMax512TextMandatoryAdditional explaining text.