Depending on what you want to achieve, third parties can:<\/p>\n
- \n
- Send non-payment requests to your terminals, like input requests<\/a> for gathering answers from your customers, and display requests<\/a> to show information like a 'Thank you' message.<\/li>\n
- Receive Terminal API display notifications.
\nThese notifications are generated by the terminal, are sent as webhooks, and contain updates on the progress of a payment on the terminal.<\/li>\n- Receive standard webhooks.
\nThese webhooks are generated on the plataforma de pagamentos da Adyen and contain transaction details.<\/li>\n<\/ul>\nThird-party interaction with the terminal doesn't interrupt the payment process.<\/p>\n
\nThird-party interactions currently do not work with the OPI integration.<\/p>\n<\/div>\n
Security and requirements<\/h2>\n
Third parties cannot send payment or card acquisition requests to your terminals. If they try to send such a request, the request is refused with an HTTP status code of
010 Not Allowed<\/code>.<\/p>\nThird-party interaction is possible:<\/p>\n
- \n
- In a Terminal API integration with WebSockets enabled.
\nYou can check the WebSockets setting in your Customer Area<\/a>, under In-person payments<\/strong> > Terminal settings<\/strong> > Integrations<\/strong>.<\/li>\n- With specific terminal models: M400, P400 Plus, V210, V400m.<\/li>\n<\/ul>\n
How it works<\/h2>\n
To enable third-party interactions you need to complete the setup as follows:<\/p>\n
- \n
- \n
You set up display notifications<\/a> for the third party. For every step of the tender<\/a> process, the third party receives a display notification that contains:<\/p>\n
- \n
- The
POIID<\/code> of the terminal. This tells the third party where to send a request.<\/li>\n- The
TransactionID<\/code>: the tender reference. When the payment is completed, the terminal sends a TENDER_FINAL<\/strong><\/span> display notification. In this notification, the PSP reference is added in the format `[tender reference].[PSP reference] is appended with the PSP reference: for cross-reference with a standard webhooks.<\/li>\n<\/ul>\n<\/li>\n- \n
You set up standard webhooks<\/a> for the third party. For every payment, the third party will receive a webhook that includes the outcome of the payment, the amount, the PSP reference, and more. Based on the PSP reference, the third party can link the customer's transaction to their rating, for richer reporting.<\/p>\n<\/li>\n
- \n
You set up an API credential<\/a> for the third party. This enables the third party to authenticate the input and display requests that they send.<\/p>\n<\/li>\n<\/ol>\n
Third-party interaction flow<\/h2>\n
The message flow with third-party interaction is as follows:<\/p>\n
- \n
- \n
The POS app sends a payment request to the payment terminal.<\/p>\n<\/li>\n
- \n
The terminal sends display notifications to the third party for every step of the tender process, from TENDER_CREATED<\/a> when the payment starts, to TENDER_FINAL<\/a> when the payment is completed.<\/p>\n<\/li>\n
- \n
When the payment process is finished, the third party sends an input request to the terminal.<\/p>\n<\/li>\n
- \n
The customer provides their input on the terminal, and the third party receives the response.<\/p>\n<\/li>\n
- \n
To thank the customer, the third party sends a display request with an image. The image disappears after the time-out set in the request, or after a default time-out of three seconds. (This step is not shown in the diagram below.)<\/p>\n<\/li>\n
- \n
The third party receives a standard webhook for the payment from the plataforma de pagamentos da Adyen.<\/p>\n<\/li>\n<\/ol>\n
The following diagram illustrates the message flow for third-party interaction. In the diagram, the POS uses cloud communications, but with local communications the third-party interaction with the terminal is the same.<\/p>\n
\n![\"\"](\"\/user\/pages\/docs\/03.point-of-sale\/41.shopper-engagement\/06.third-party-interactions\/third-party-interaction-after-payment.svg?decoding=auto&fetchpriority=auto\")
<\/p>\n<\/div>\nSet up third-party webhook endpoints<\/h2>\n
To receive webhooks from Adyen terminals and the plataforma de pagamentos da Adyen, the third party needs to configure their system. Then you need to set up third-party webhooks in your Customer Area.<\/p>\n
Configuration by the third-party<\/h3>\n
- \n
- \n
Inform the third party of the requirements for receiving webhooks:<\/p>\n
- \n
- \n
Their system needs to have:<\/p>\n
- \n
- One or more endpoints that can receive webhooks in JSON format. They may get two kinds of webhooks: display notifications from the terminals, and standard webhooks from the plataforma de pagamentos da Adyen.<\/li>\n
- For the test environment: an open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (443, 8443, or 8843) with TLSv1.2.<\/li>\n
- For the live environment: an open TCP port for HTTPS traffic (443, 8443, or 8843) with TLSv1.2.<\/li>\n
- Optional: a username and password for basic authentication.<\/li>\n<\/ul>\n<\/li>\n
- \n
If they want to receive standard webhooks, they should verify the HMAC signature<\/a> of the standard webhook and they must acknowledge<\/a> every standard webhook with a successful HTTP response status code<\/a>, for example 200<\/strong>. For instructions, refer the third party to our development resources<\/a> for webhooks.<\/p>\n\n<\/li>\n<\/ul>\n<\/li>\n
- \n
Ask the third party for the endpoints and basic authentication credentials they set up for receiving webhooks.
\nYou need to provide those details in your Customer Area in the next steps.<\/p>\n<\/li>\n<\/ol>\nSet up display notifications<\/h3>\n
To set up display notifications for the third party:<\/p>\n
- \n
- \n
Make sure that you know the endpoint where the third party wants to receive display notifications, and the basic authentication credentials.<\/p>\n<\/li>\n
- \n
Log in to your Customer Area<\/a> and switch to the account, store, or terminal that you want to set up notifications for.<\/p>\n<\/li>\n
- \n
Go to In-person payments<\/strong> > Terminal settings<\/strong> > Integrations<\/strong>.<\/p>\n<\/li>\n
- \n
In the Terminal API<\/strong> section, select Decrypted<\/strong>.<\/p>\n<\/li>\n
- \n
Under Display URLs<\/strong>, select the pencil icon <\/i> and then select Add new<\/strong>.<\/p>\n<\/li>\n
- \n
Select the pencil icon <\/i> next to the field that appears.
\nThe Add URL<\/strong> dialog opens.<\/p>\n<\/li>\n- \n
Enter the details:<\/p>\n
- \n
- URL<\/strong>: the URL of the endpoint where the third party wants to receive display notifications.<\/li>\n
- Username<\/strong> and Password<\/strong> (optional): the basic authentication credentials that the third party set up on their server.<\/li>\n
- Public<\/strong>: select this option. Indicates that the specified URL is on a public network.<\/li>\n
- \n
Local<\/strong>: do not select this option; not applicable for third-party interactions.<\/p>\n\n<\/li>\n<\/ul>\n<\/li>\n
- \n
Select Add URL<\/strong> and then Save<\/strong>.<\/p>\n<\/li>\n
- \n
If your integration uses local communications, ask our Support Team<\/a> to ensure display notifications are not encrypted.
\nThis step is necessary because with local communications the terminal generates encrypted notifications and the third party cannot decrypt those.<\/p>\n<\/li>\n<\/ol>\nSet up standard webhooks<\/h3>\n
Currently there are no restrictions enforced on the details that third parties can receive in standard webhooks. We advise you to limit the details to the minimum required for your use case, by enabling as few additional settings as possible.<\/p>\n
To set up third-party standard webhooks:<\/p>\n
In your Customer Area<\/a>, enable and configure webhooks for your company account<\/a>, merchant account<\/a>, and merchant account groups<\/a>. However, we recommend to configure webhooks for your company account<\/a>. To set up a webhook for a specific merchant account, create a webhook for your company account, and configure merchant accounts<\/a> for that webhook.<\/p>\n
- \n
- You can configure Payments webhooks<\/a> on the company, merchant account, and merchant account groups.<\/li>\n
- You can configure Platforms webhooks<\/a> on the company account level only.<\/li>\n<\/ul>\n
To configure a webhook:<\/strong><\/p>\n 1. Make sure that you know the endpoint where the third party wants to receive standard webhooks, and the basic authentication username and password of their webhook server. 2. If the payment terminals that the third party will interact with are boarded to one specific merchant account, switch to that merchant account.
- \n
- \n
In your Customer Area<\/a>, go to Developers<\/strong>\u00a0>\u00a0Webhooks<\/strong>.
\nIf you have a Balance Platform integration, select Payments<\/strong> or Platforms<\/strong> to view the webhooks available to you based on your integration.<\/p>\n<\/li>\n- \n
Select <\/i> Create new webhook<\/strong>.
\nIf you are adding a webhook for your platform and have multiple platforms set up to run on Adyen, select the balance platform where you want to configure your new webhook.<\/p>\n<\/li>\n- \n
From the list of webhooks, select Add<\/strong> for the one to add.<\/p>\n<\/li>\n
- \n
Under General<\/strong>, configure the following:<\/p>\n
- \n
- You can configure Platforms webhooks<\/a> on the company account level only.<\/li>\n<\/ul>\n
- Username<\/strong> and Password<\/strong> (optional): the basic authentication credentials that the third party set up on their server.<\/li>\n
- \n
- \n
- \n
- \n
- The
- The
- With specific terminal models: M400, P400 Plus, V210, V400m.<\/li>\n<\/ul>\n
- Receive Terminal API display notifications.