A set of API endpoints that allow you to initiate, settle, and modify payments on the Adyen payments platform. You can use the API to accept card payments (including One-Click and 3D Secure), bank transfers, ewallets, and many other payment methods.
openapi: 3.1.0
servers:
- url: https://pal-test.adyen.com/pal/servlet/Payment/v68
info:
version: '68'
x-publicVersion: true
title: Adyen Payment API
description: >-
A set of API endpoints that allow you to initiate, settle, and modify
payments on the Adyen payments platform. You can use the API to accept card
payments (including One-Click and 3D Secure), bank transfers, ewallets, and
many other payment methods.
To learn more about the API, visit [Classic
integration](https://docs.adyen.com/classic-integration).
## Authentication
You need an [API
credential](https://docs.adyen.com/development-resources/api-credentials) to
authenticate to the API.
If using an API key, add an `X-API-Key` header with the API key as the
value, for example:
```
curl
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
...
```
Alternatively, you can use the username and password to connect to the API
using basic authentication, for example:
```
curl
-U "[email protected]_COMPANY_ACCOUNT":"YOUR_BASIC_AUTHENTICATION_PASSWORD" \
-H "Content-Type: application/json" \
...
```
## Versioning
Payments API supports
[versioning](https://docs.adyen.com/development-resources/versioning) using
a version suffix in the endpoint URL. This suffix has the following format:
"vXX", where XX is the version number.
For example:
```
https://pal-test.adyen.com/pal/servlet/Payment/v68/authorise
```
## Going live
To authenticate to the live endpoints, you need an [API
credential](https://docs.adyen.com/development-resources/api-credentials)
from your live Customer Area.
The live endpoint URLs contain a prefix which is unique to your company
account:
```
https://{PREFIX}-pal-live.adyenpayments.com/pal/servlet/Payment/v68/authorise
```
Get your `{PREFIX}` from your live Customer Area under **Developers** >
**API URLs** > **Prefix**.
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
tags:
- name: adjustAuthorisation
- name: Authorise
- name: Authorise3d
- name: Authorise3ds2
- name: Cancel
- name: cancelOrRefund
- name: Capture
- name: Donate
- name: getAuthenticationResult
- name: Refund
- name: retrieve3ds2Result
- name: technicalCancel
- name: voidPendingRefund
paths:
/adjustAuthorisation:
post:
tags:
- adjustAuthorisation
summary: Adyen Change the Authorised Amount
description: >-
Allows you to increase or decrease the authorised amount after the
initial authorisation has taken place. This functionality enables for
example tipping, improving the chances your authorisation will be valid,
or charging the shopper when they have already left the merchant
premises.
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce).
> If you have a [newer
integration](https://docs.adyen.com/online-payments), and are doing:
> * [Asynchronous
adjustments](https://docs.adyen.com/online-payments/adjust-authorisation#asynchronous-or-synchronous-adjustment),
use the
[`/payments/{paymentPspReference}/amountUpdates`](https://docs.adyen.com/api-explorer/#/CheckoutService/v67/post/payments/{paymentPspReference}/amountUpdates)
endpoint on Checkout API.
> * [Synchronous
adjustments](https://docs.adyen.com/online-payments/adjust-authorisation#asynchronous-or-synchronous-adjustment),
use this endpoint.
x-addedInVersion: '30'
operationId: post-adjustAuthorisation
x-sortIndex: 6
x-methodName: adjustAuthorisation
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
adjustAuthorisation:
$ref: >-
#/components/examples/post-adjustAuthorisation-adjustAuthorisation
schema:
$ref: '#/components/schemas/AdjustAuthorisationRequest'
responses:
'200':
content:
application/json:
examples:
adjustAuthorisation:
$ref: >-
#/components/examples/post-adjustAuthorisation-adjustAuthorisation-200
schema:
$ref: '#/components/schemas/ModificationResult'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-adjustAuthorisation403Example:
summary: Default post-adjustAuthorisation 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-adjustAuthorisation422Example:
summary: Default post-adjustAuthorisation 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorise:
post:
tags:
- Authorise
summary: Adyen Create an Authorisation
description: >-
Creates a payment with a unique reference (`pspReference`) and attempts
to obtain an authorisation hold. For cards, this amount can be captured
or cancelled later. Non-card payment methods typically don't support
this and will automatically capture as part of the authorisation.
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments`](https://docs.adyen.com/api-explorer/#/CheckoutService/payments)
endpoint under Checkout API instead.
operationId: post-authorise
x-sortIndex: 1
x-methodName: authorise
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
authorise-3d-secure-2:
$ref: '#/components/examples/post-authorise-authorise-3d-secure-2'
authorise-3dsecure:
$ref: '#/components/examples/post-authorise-authorise-3dsecure'
authorise-card:
$ref: '#/components/examples/post-authorise-authorise-card'
authorise-recurringcontauth:
$ref: >-
#/components/examples/post-authorise-authorise-recurringcontauth
authorise-recurringoneclick:
$ref: >-
#/components/examples/post-authorise-authorise-recurringoneclick
authorise-recurringstore:
$ref: '#/components/examples/post-authorise-authorise-recurringstore'
authorise-split:
$ref: '#/components/examples/post-authorise-authorise-split'
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResult'
examples:
post-authorise200Example:
summary: Default post-authorise 200 response
x-microcks-default: true
value:
additionalData: {}
authCode: CODE123
dccAmount: 1000
dccSignature: example_value
fraudResult: example_value
issuerUrl: https://example.com/resource
md: example_value
paRequest: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: AuthenticationFinished
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise403Example:
summary: Default post-authorise 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise422Example:
summary: Default post-authorise 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorise3d:
post:
tags:
- Authorise3d
summary: Adyen Complete a 3DS Authorisation
description: >-
For an authenticated 3D Secure session, completes the payment
authorisation. This endpoint must receive the `md` and `paResponse`
parameters that you get from the card issuer after a shopper pays via 3D
Secure.
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce/3d-secure).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments/details`](https://docs.adyen.com/api-explorer/#/CheckoutService/payments/details)
endpoint under Checkout API instead.
operationId: post-authorise3d
x-sortIndex: 2
x-methodName: authorise3d
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
authorise3d:
$ref: '#/components/examples/post-authorise3d-authorise3d'
schema:
$ref: '#/components/schemas/PaymentRequest3d'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResult'
examples:
post-authorise3d200Example:
summary: Default post-authorise3d 200 response
x-microcks-default: true
value:
additionalData: {}
authCode: CODE123
dccAmount: 1000
dccSignature: example_value
fraudResult: example_value
issuerUrl: https://example.com/resource
md: example_value
paRequest: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: AuthenticationFinished
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise3d403Example:
summary: Default post-authorise3d 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise3d422Example:
summary: Default post-authorise3d 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/authorise3ds2:
post:
tags:
- Authorise3ds2
summary: Adyen Complete a 3DS2 Authorisation
description: >-
For an authenticated 3D Secure 2 session, completes the payment
authorisation. This endpoint must receive the `threeDS2Token` and
`threeDS2Result` parameters.
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce/3d-secure).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments/details`](https://docs.adyen.com/api-explorer/#/CheckoutService/payments/details)
endpoint under Checkout API instead.
x-addedInVersion: '37'
operationId: post-authorise3ds2
x-sortIndex: 3
x-methodName: authorise3ds2
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
authorise3ds2:
$ref: '#/components/examples/post-authorise3ds2-authorise3ds2'
schema:
$ref: '#/components/schemas/PaymentRequest3ds2'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResult'
examples:
post-authorise3ds2200Example:
summary: Default post-authorise3ds2 200 response
x-microcks-default: true
value:
additionalData: {}
authCode: CODE123
dccAmount: 1000
dccSignature: example_value
fraudResult: example_value
issuerUrl: https://example.com/resource
md: example_value
paRequest: example_value
pspReference: REF-001
refusalReason: REF-001
resultCode: AuthenticationFinished
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise3ds2403Example:
summary: Default post-authorise3ds2 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-authorise3ds2422Example:
summary: Default post-authorise3ds2 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/cancel:
post:
tags:
- Cancel
summary: Adyen Cancel an Authorisation
description: >-
Cancels the authorisation hold on a payment, returning a unique
reference for this request. You can cancel payments after authorisation
only for payment methods that support distinct authorisations and
captures.
For more information, refer to
[Cancel](https://docs.adyen.com/online-payments/classic-integrations/modify-payments/cancel).
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments/{paymentPspReference}/cancels`](https://docs.adyen.com/api-explorer/#/CheckoutService/payments/{paymentPspReference}/cancels)
endpoint under Checkout API instead.
operationId: post-cancel
x-sortIndex: 2
x-methodName: cancel
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
cancel:
$ref: '#/components/examples/post-cancel-cancel'
schema:
$ref: '#/components/schemas/CancelRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ModificationResult'
examples:
post-cancel200Example:
summary: Default post-cancel 200 response
x-microcks-default: true
value:
additionalData: {}
pspReference: REF-001
response: '[capture-received]'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-cancel403Example:
summary: Default post-cancel 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-cancel422Example:
summary: Default post-cancel 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/cancelOrRefund:
post:
tags:
- cancelOrRefund
summary: Adyen Cancel or Refund a Payment
description: >-
Cancels a payment if it has not been captured yet, or refunds it if it
has already been captured. This is useful when it is not certain if the
payment has been captured or not (for example, when using auto-capture).
Do not use this endpoint for payments that involve:
* [Multiple partial captures](https://docs.adyen.com/online-payments/capture).
* [Split data](https://docs.adyen.com/marketplaces-and-platforms/processing-payments#providing-split-information) either at time of payment or capture for Adyen for Platforms.
Instead, check if the payment has been captured and make a corresponding [`/refund`](https://docs.adyen.com/api-explorer/#/Payment/refund) or [`/cancel`](https://docs.adyen.com/api-explorer/#/Payment/cancel)
call.
For more information, refer to [Cancel or
refund](https://docs.adyen.com/online-payments/classic-integrations/modify-payments/cancel-or-refund).
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments/{paymentPspReference}/reversals`](https://docs.adyen.com/api-explorer/#/CheckoutService/payments/{paymentPspReference}/reversals)
endpoint under Checkout API instead.
operationId: post-cancelOrRefund
x-sortIndex: 4
x-methodName: cancelOrRefund
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
cancelOrRefund:
$ref: '#/components/examples/post-cancelOrRefund-cancelOrRefund'
schema:
$ref: '#/components/schemas/CancelOrRefundRequest'
responses:
'200':
content:
application/json:
examples:
cancelOrRefund:
$ref: '#/components/examples/post-cancelOrRefund-cancelOrRefund-200'
schema:
$ref: '#/components/schemas/ModificationResult'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-cancelOrRefund403Example:
summary: Default post-cancelOrRefund 403 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-cancelOrRefund422Example:
summary: Default post-cancelOrRefund 422 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/capture:
post:
tags:
- Capture
summary: Adyen Capture an Authorisation
description: >+
Captures the authorisation hold on a payment, returning a unique
reference for this request. Usually the full authorisation amount is
captured, however it's also possible to capture a smaller amount, which
results in cancelling the remaining authorisation balance.
Payment methods that are captured automatically after authorisation
don't need to be captured. However, submitting a capture request on
these transactions will not result in double charges. If immediate or
delayed auto-capture is enabled, calling the capture method is not
neccessary.
For more information refer to
[Capture](https://docs.adyen.com/online-payments/classic-integrations/modify-payments/capture).
> This endpoint is part of our [classic API
integration](https://docs.adyen.com/online-payments/classic-integrations/api-integration-ecommerce).
If using a [newer integration](https://docs.adyen.com/online-payments),
use the
[`/payments/{paymentPspReference}/captures`](https://docs.adyen.com/api-explorer/#/CheckoutService/v67/post/payments/{paymentPspReference}/captures)
endpoint on Checkout API instead.
operationId: post-capture
x-sortIndex: 1
x-methodName: capture
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
capture:
$ref: '#/components/examples/post-capture-capture'
schema:
$ref: '#/components/schemas/CaptureRequest'
responses:
'200':
content:
application/json:
examples:
capture:
$ref: '#/components/examples/post-capture-capture-200'
schema:
$ref: '#/components/schemas/ModificationResult'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/compon
# --- truncated at 32 KB (316 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/payments-openapi-original.yml