In your host-to-host integration with the plataforma de pagamentos da Adyen you will make API requests to various endpoints. Some endpoints are specific for making host-to-host transactions with your own terminals. Other endpoints are also used in other integration types, such as ecommerce, for making payment modifications like cancellations.
This page gives an overview of the test endpoints, certification endpoints, and live endpoints to use. Your requests to these endpoints must be authenticated with an API key.
Requirements
Take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | A host-to-host integration. |
| API credential roles | Make sure that you have an API key and the following role:
|
| Hardware | A payment terminal. |
| Limitations | Your host-to-host setup must be certified for compliance with the card schemes. |
| Setup steps | If you have an existing host-to-host integration, make sure that you have migrated to the latest supported endpoints. |
API key and versioning
To authenticate your API requests, you need to have an API credential with an API key and the following role:
- POS HostToHost Integration
You must specify the API key in the X-API-Key header of your requests.
If you do not have an API key yet, you can create an API key in your test Customer Area.
To access live endpoints, you need to create a new API key in your live Customer Area.
API versioning
Versioning is handled as part of the endpoint URL. For example, to make a payment using version 1 of POS payments API, use:
https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v1/paymentsTest endpoints
The following table lists the endpoints for building a host-to-host integration.
| Operation | Endpoint | |||
|---|---|---|---|---|
| Payment | https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions |
|||
| Offline Payment | https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/offlinePayments |
|||
| PIN transfer | https://management-test.adyen.com/v#/partners/{companyId}/pos/keys |
|||
| Authorization adjustment, asynchronous | https://checkout-test.adyen.com/checkout/v#/payments/{paymentPspReference}/amountUpdates |
|||
| Authorization adjustment, synchronous | https://pal-test.adyen.com/pal/servlet/Payment/v#/adjustAuthorisation |
|||
| Manual capture | https://checkout-test.adyen.com/checkout/v#/payments/{paymentPspReference}/captures |
|||
| Cancel | https://checkout-test.adyen.com/checkout/v#/payments/{paymentPspReference}/cancels |
|||
| Refund, referenced | https://checkout-test.adyen.com/checkout/v#/payments/{paymentPspReference}/refunds |
|||
| Refund, unreferenced | https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspreference}/completions |
Find the latest version for the following endpoints in our API Explorer :
- Authorization adjustment, asynchronous
- Authorization adjustment, synchronous
- Manual capture
- Cancel
- Referenced refund
Certification endpoints
During certification, you need to connect your host to the certification environment using the same endpoints as in the test environment.
| Operation | Endpoint |
|---|---|
| Payment | https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions |
| PIN transfer | https://management-test.adyen.com/v#/partners/{companyId}/pos/keys |
| Cancel | https://checkout-test.adyen.com/checkout/v#/payments/{paymentPspReference}/cancels |
| Refund, unreferenced | https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspreference}/completions |
Live endpoints
The live endpoint URLs differ from the test endpoint URLs. In the table below, pay attention if a live endpoint URL requires you to include:
- Your geographical location.
- A prefix which is unique to your company.
To specify your geographical region, replace YOUR_REGION with the corresponding value from the table below. For example, live-au if your region is Australia: https://hosttohostpaymentgateway-live.au.adyen.com/hosttohostpaymentgateway/v#/offlinePayments
| Endpoint region | Value |
|---|---|
| Europe (EU) live | live |
| United States (US) live | live-us |
| Australia (AU) live | live-au |
| Asia Pacific & Southeast (APSE) live | live-apse |
| India (IN) live | live-in |
To get your {PREFIX}, in your live Customer Area go to Developers > API URLs > Prefix.
| Operation | Prefix | Region | Endpoint |
|---|---|---|---|
| Payment |  |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/payments and https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/payments/{paymentPspReference}/completions |
|
| Offline Payment | |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/offlinePayments |
|
| PIN transfer | https://management-live.adyen.com/v#/partners/{companyId}/pos/keys |
||
| Authorization adjustment, asynchronous | |
https://{PREFIX}-checkout-live.adyenpayments.com/checkout/v#/payments/{paymentPspReference}/amountUpdates |
|
| Authorization adjustment, synchronous | |
https://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Payment/v#/adjustAuthorisation |
|
| Manual capture | |
https://{PREFIX}-checkout-live.adyenpayments.com/checkout/v#/payments/{paymentPspReference}/captures |
|
| Cancel | |
https://{PREFIX}-checkout-live.adyenpayments.com/checkout/v#/payments/{paymentPspReference}/cancels |
|
| Refund, referenced | |
https://{PREFIX}-checkout-live.adyenpayments.com/checkout/v#/payments/{paymentPspReference}/refunds |
|
| Refund, unreferenced | |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds and https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspReference}/completions |
To access the live endpoints, you need an API key from your live Customer Area.
Find the latest version for the following endpoints in our API Explorer :
- Authorization adjustment, asynchronous
- Authorization adjustment, synchronous
- Manual capture
- Cancel
- Referenced refund
Migrate to the latest endpoints
If you have an existing host-to-host integration, you need to migrate to the latest endpoint.
We have updated the endpoints for the following operations:
- Payments
- Unreferenced refunds
- Offline payments
You must migrate to the new endpoints for:
API versioning
The new endpoints are not tied to a new version of the API. The new endpoints can be used with any API version.
Test endpoints
The following table lists the test endpoints that you need to update.
| Operation | Old endpoint | New endpoint |
|---|---|---|
| Payment | https://checkout-test.adyen.com/checkout/pos/v#/payments and https://checkout-test.adyen.com/checkout/pos/v#/payments/{paymentPspsReference}/completions |
https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/payments/{paymentPspsReference}/completions |
| Refund, unreferenced | https://checkout-test.adyen.com/checkout/pos/v#/unreferencedRefunds and https://checkout-test.adyen.com/checkout/pos/v#/unreferencedRefunds/{pspreference}/completions |
https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds and https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspreference}/completions |
| Offline Payment | https://checkout-test.adyen.com/checkout/pos/v1/offlinePayments |
https://hosttohostpaymentgateway-test.adyen.com/hosttohostpaymentgateway/v#/offlinePayments |
Live endpoints
The following table lists the live endpoints that you need to update.
Make sure that you include the {PREFIX} and YOUR_REGION where required.
| Operation | Old endpoint | New endpoint |
|---|---|---|
| Payment | https://{PREFIX}-checkout-live.adyenpayments.com/checkout/pos/v#/payments and https://{PREFIX}-checkout-live.adyenpayments.com/checkout/pos/v#/payments/{paymentPspReference}/completions |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/payments and https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/payments/{paymentPspReference}/completions |
| Offline Payment | https://{PREFIX}-checkout-live.adyenpayments.com/checkout/pos/v#/offlinePayments |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/offlinePayments |
| Refund, unreferenced | https://{PREFIX}-checkout-live.adyenpayments.com/checkout/pos/v#/unreferencedRefunds and https://hosttohostpaymentgateway-live.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspReference}/completions |
https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds and https://hosttohostpaymentgateway-{YOUR_REGION}.adyen.com/hosttohostpaymentgateway/v#/unreferencedRefunds/{pspReference}/completions |