Adyen Recurring API
The Recurring APIs allow you to manage and remove your tokens or saved payment details. Tokens should be created with validation during a payment request.
OpenAPI Specification
openapi: 3.1.0
servers:
- url: https://pal-test.adyen.com/pal/servlet/Recurring/v68
info:
version: '68'
x-publicVersion: true
title: Adyen Recurring API
description: >-
The Recurring APIs allow you to manage and remove your tokens or saved
payment details. Tokens should be created with validation during a payment
request.
For more information, refer to our [Tokenization
documentation](https://docs.adyen.com/online-payments/tokenization).
## 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
Recurring 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/Recurring/v68/disable
```
## 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/Recurring/v68/disable
```
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: createPermit
- name: Disable
- name: disablePermit
- name: listRecurringDetails
- name: notifyShopper
- name: scheduleAccountUpdater
paths:
/createPermit:
post:
tags:
- createPermit
summary: Adyen Create New Permits Linked to a Recurring Contract.
description: >-
Create permits for a recurring contract, including support for defining
restrictions.
x-addedInVersion: '40'
operationId: post-createPermit
x-sortIndex: 0
x-methodName: createPermit
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePermitRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePermitResult'
examples:
post-createPermit200Example:
summary: Default post-createPermit 200 response
x-microcks-default: true
value:
permitResultList:
- example_value
pspReference: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-createPermit400Example:
summary: Default post-createPermit 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-createPermit401Example:
summary: Default post-createPermit 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-createPermit403Example:
summary: Default post-createPermit 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-createPermit422Example:
summary: Default post-createPermit 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-createPermit500Example:
summary: Default post-createPermit 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/disable:
post:
tags:
- Disable
summary: Adyen Disable Stored Payment Details
description: >-
Disables stored payment details to stop charging a shopper with this
particular recurring detail ID.
For more information, refer to [Disable stored
details](https://docs.adyen.com/classic-integration/recurring-payments/disable-stored-details/).
operationId: post-disable
x-sortIndex: 2
x-methodName: disable
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
disableARecurringContract:
$ref: '#/components/examples/post-disable-disableARecurringContract'
schema:
$ref: '#/components/schemas/DisableRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DisableResult'
examples:
post-disable200Example:
summary: Default post-disable 200 response
x-microcks-default: true
value:
response: example_value
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disable400Example:
summary: Default post-disable 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disable401Example:
summary: Default post-disable 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disable403Example:
summary: Default post-disable 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-disable422Example:
summary: Default post-disable 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disable500Example:
summary: Default post-disable 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/disablePermit:
post:
tags:
- disablePermit
summary: Adyen Disable an Existing Permit.
description: >-
Disable a permit that was previously linked to a
recurringDetailReference.
x-addedInVersion: '61'
operationId: post-disablePermit
x-sortIndex: 0
x-methodName: disablePermit
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DisablePermitRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DisablePermitResult'
examples:
post-disablePermit200Example:
summary: Default post-disablePermit 200 response
x-microcks-default: true
value:
pspReference: REF-001
status: active
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disablePermit400Example:
summary: Default post-disablePermit 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disablePermit401Example:
summary: Default post-disablePermit 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disablePermit403Example:
summary: Default post-disablePermit 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-disablePermit422Example:
summary: Default post-disablePermit 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-disablePermit500Example:
summary: Default post-disablePermit 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/listRecurringDetails:
post:
tags:
- listRecurringDetails
summary: Adyen Get Stored Payment Details
description: >-
Lists the stored payment details for a shopper, if there are any
available. The recurring detail ID can be used with a regular
authorisation request to charge the shopper. A summary of the payment
detail is returned for presentation to the shopper.
For more information, refer to [Retrieve stored
details](https://docs.adyen.com/classic-integration/recurring-payments/retrieve-stored-details/).
operationId: post-listRecurringDetails
x-sortIndex: 1
x-methodName: listRecurringDetails
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
listAllRecurringDetails:
$ref: >-
#/components/examples/post-listRecurringDetails-listAllRecurringDetails
schema:
$ref: '#/components/schemas/RecurringDetailsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsResult'
examples:
post-listRecurringDetails200Example:
summary: Default post-listRecurringDetails 200 response
x-microcks-default: true
value:
creationDate: '2025-03-15T14:30:00Z'
details:
- example_value
lastKnownShopperEmail: [email protected]
shopperReference: REF-001
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-listRecurringDetails400Example:
summary: Default post-listRecurringDetails 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-listRecurringDetails401Example:
summary: Default post-listRecurringDetails 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-listRecurringDetails403Example:
summary: Default post-listRecurringDetails 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-listRecurringDetails422Example:
summary: Default post-listRecurringDetails 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-listRecurringDetails500Example:
summary: Default post-listRecurringDetails 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/notifyShopper:
post:
tags:
- notifyShopper
summary: Adyen Ask Issuer to Notify the Shopper
description: >-
Sends a request to the issuer so they can inform the shopper about the
upcoming recurring payment. This endpoint is used only for local
acquiring in India. For more information, refer to [Recurring card
payments in
India](https://docs.adyen.com/payment-methods/cards/cards-recurring-india).
operationId: post-notifyShopper
x-sortIndex: 4
x-methodName: notifyShopper
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
notifyShopperOfUpcomingRecurringPayment:
$ref: >-
#/components/examples/post-notifyShopper-notifyShopperOfUpcomingRecurringPayment
schema:
$ref: '#/components/schemas/NotifyShopperRequest'
responses:
'200':
content:
application/json:
examples:
notifyShopperOfUpcomingRecurringPayment:
$ref: >-
#/components/examples/post-notifyShopper-notifyShopperOfUpcomingRecurringPayment-200
schema:
$ref: '#/components/schemas/NotifyShopperResult'
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-notifyShopper400Example:
summary: Default post-notifyShopper 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-notifyShopper401Example:
summary: Default post-notifyShopper 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-notifyShopper403Example:
summary: Default post-notifyShopper 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-notifyShopper422Example:
summary: Default post-notifyShopper 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-notifyShopper500Example:
summary: Default post-notifyShopper 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/scheduleAccountUpdater:
post:
tags:
- scheduleAccountUpdater
summary: Adyen Schedule Running the Account Updater
description: >-
When making the API call, you can submit either the credit card
information, or the recurring detail reference and the shopper
reference:
* If the card information is provided, all the sub-fields for `card` are
mandatory.
* If the recurring detail reference is provided, the fields for
`shopperReference` and `selectedRecurringDetailReference` are mandatory.
x-addedInVersion: '4'
operationId: post-scheduleAccountUpdater
x-sortIndex: 3
x-methodName: scheduleAccountUpdater
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
scheduleAccountUpdaterWithCardData:
$ref: >-
#/components/examples/post-scheduleAccountUpdater-scheduleAccountUpdaterWithCardData
scheduleAccountUpdaterWithTokenData:
$ref: >-
#/components/examples/post-scheduleAccountUpdater-scheduleAccountUpdaterWithTokenData
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
examples:
post-scheduleAccountUpdater200Example:
summary: Default post-scheduleAccountUpdater 200 response
x-microcks-default: true
value:
pspReference: REF-001
result: example_value
description: OK - the request has succeeded.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-scheduleAccountUpdater400Example:
summary: Default post-scheduleAccountUpdater 400 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-scheduleAccountUpdater401Example:
summary: Default post-scheduleAccountUpdater 401 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Unauthorized - authentication required.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-scheduleAccountUpdater403Example:
summary: Default post-scheduleAccountUpdater 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-scheduleAccountUpdater422Example:
summary: Default post-scheduleAccountUpdater 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:
schema:
$ref: '#/components/schemas/ServiceError'
examples:
post-scheduleAccountUpdater500Example:
summary: Default post-scheduleAccountUpdater 500 response
x-microcks-default: true
value:
additionalData: {}
errorCode: CODE123
errorType: standard
message: example_value
pspReference: REF-001
status: 500
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
Address:
properties:
city:
description: 'The name of the city. Maximum length: 3000 characters.'
maxLength: 3000
type: string
country:
description: >-
The two-character ISO-3166-1 alpha-2 country code. For example,
**US**.
> If you don't know the country or are not collecting the country
from the shopper, provide `country` as `ZZ`.
type: string
houseNumberOrName:
description: 'The number or name of the house. Maximum length: 3000 characters.'
maxLength: 3000
type: string
postalCode:
description: >-
A maximum of five digits for an address in the US, or a maximum of
ten characters for an address in all other countries.
type: string
stateOrProvince:
description: >-
The two-character ISO 3166-2 state or province code. For example,
**CA** in the US or **ON** in Canada.
> Required for the US and Canada.
type: string
street:
description: >-
The name of the street. Maximum length: 3000 characters.
> The house number should not be included in this field; it should
be separately provided via `houseNumberOrName`.
maxLength: 3000
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
type: obje
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/recurring-openapi-original.yml