jlengrand/adyen-openapi
1
0
Fork 0
mirror of https://github.com/gcatanese/adyen-openapi.git synced 2026-03-10 08:01:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

yaml files

Browse Source
This commit is contained in:
aleksei
2019-11-20 09:58:35 +01:00
parent a9d3821366
commit e2dd2fc086
12 changed files with 10614 additions and 166 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
specs/yaml/PayoutService-v30.yaml
View File

@@ -3,11 +3,11 @@ servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Payout/v30'
info:
version: '30'
title: Adyen Payout Service
title: Adyen Payout API
description: |-
A set of API endpoints that allow you to store payout details, confirm, or decline a payout.
For more information, refer to [Third-party payouts](https://docs.adyen.com/developers/features/third-party-payouts).
For more information, refer to [Online payouts](https://docs.adyen.com/checkout/online-payouts).
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
@@ -203,42 +203,39 @@ components:
Address:
properties:
city:
description: |-
The name of the city.
>Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided.
description: The name of the city.
type: string
country:
description: |-
The two-character country code of the address
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').
The two-character country code as defined in ISO-3166-1 alpha-2. 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.
type: string
postalCode:
description: |-
The postal code.
>A maximum of five (5) digits for an address in the USA, or a maximum of ten (10) characters for an address in all other countries.
>Required if either houseNumberOrName, street, city, or stateOrProvince are provided.
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 abbreviation of the state or province.
>Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries.
>Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided.
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |-
The name of the street.
>The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
>Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
Amount:
properties:
currency:
description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).'
description: 'The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).'
maxLength: 3
minLength: 3
type: string
@@ -246,7 +243,7 @@ components:
description: |-
The payable amount that can be charged for the transaction.
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/development-resources/currency-codes).
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
@@ -314,11 +311,11 @@ components:
properties:
cvc:
description: |-
The [card verification code](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid) (1-20 characters). Depending on the card brand, it is known also as:
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/developers/features/client-side-encryption), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/classic-integration/recurring-payments).
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
@@ -538,17 +535,17 @@ components:
properties:
additionalAmount:
description: |-
If you want a [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
If you want a [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
$ref: '#/components/schemas/Amount'
additionalData:
description: |-
This field contains additional data, which may be required for a particular payment request.
The `additionalData` object consists of entries, each of which includes the key and value. For more information on possible key-value pairs, refer to the [additionalData section](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata).
The `additionalData` object consists of entries, each of which includes the key and value. For more information on possible key-value pairs, refer to the [additionalData section](https://docs.adyen.com/api-reference/payments-api/paymentrequest/paymentrequest-additionaldata).
type: object
amount:
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
$ref: '#/components/schemas/Amount'
bankAccount:
description: |-
@@ -556,10 +553,14 @@ components:
> Either `bankAccount` or `card` field must be provided in a payment request.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The address where to send the invoice.
description: |-
The address where to send the invoice.
> For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object.
$ref: '#/components/schemas/Address'
browserInfo:
description: The shopper's browser information.
description: |-
The shopper's browser information.
> For 3D Secure 2 transactions, `browserInfo` is required for `channel` **web** (or `deviceChannel` **browser**).
$ref: '#/components/schemas/BrowserInfo'
captureDelayHours:
description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.'
@@ -593,7 +594,7 @@ components:
format: date-time
type: string
deviceFingerprint:
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/developers/risk-management/device-fingerprinting).'
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/risk-management/device-fingerprinting).'
type: string
entityType:
description: The type of the entity the payment is processed for.
@@ -609,7 +610,7 @@ components:
description: The person or entity funding the money.
$ref: '#/components/schemas/FundSource'
installments:
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).'
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).'
$ref: '#/components/schemas/Installments'
mcc:
description: 'The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.'
@@ -619,13 +620,14 @@ components:
type: string
merchantOrderReference:
description: |-
This reference allows linking multiple transactions to each other.
This reference allows linking multiple transactions to each other for reporting purposes (i.e. order auth-rate). The reference should be unique per billing cycle.
The same merchant order reference should never be reused after the first authorised attempt. If used, this field should be supplied for all incoming authorisations.
> We strongly recommend you send the `merchantOrderReference` value to benefit from linking payment requests when authorisation retries take place. In addition, we recommend you provide `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values in `PaymentRequest.additionalData`.
type: string
metadata:
description: |-
Metadata consists of entries, each of which includes a key and a value.
Limitations: Error "177", "Metadata size exceeds limit"
Limitations: Maximum 20 key-value pairs per request. When exceeding, the "177" error occurs: "Metadata size exceeds limit".
type: object
mpiData:
description: Authentication data produced by an MPI (Mastercard SecureCode or Verified By Visa).
@@ -635,20 +637,22 @@ components:
maxLength: 2
type: string
orderReference:
description: The order reference to link multiple partial payments.
description: 'When you are doing multiple partial (gift card) payments, this is the `pspReference` of the first payment. We use this to link the multiple payments to each other. As your own reference for linking multiple payments, use the `merchantOrderReference`instead.'
type: string
recurring:
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/developers/features/recurring-payments).'
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/classic-integration/recurring-payments).'
$ref: '#/components/schemas/Recurring'
recurringProcessingModel:
description: |-
description: |
Defines a recurring payment type.
Allowed values:
* `Subscription` – A transaction for a fixed or variable amount, which follows a fixed schedule.
* `CardOnFile` – Card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction.
* `UnscheduledCardOnFile` – A transaction that occurs on a non-fixed schedule and/or have variable amounts. For example, automatic top-ups when a cardholder's balance drops below a certain amount.
enum:
- CardOnFile
- Subscription
- UnscheduledCardOnFile
type: string
reference:
description: |-
@@ -671,12 +675,14 @@ components:
description: A session ID used to identify a payment session.
type: string
shopperEmail:
description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.'
description: |-
The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks.
> For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**.
type: string
shopperIP:
description: |-
The shopper's IP address. We recommend that you provide this data, as it is used in a number of risk checks (for instance, number of payment attempts or location-based checks).
> This field is mandatory for some merchants depending on your business model. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new).
The shopper's IP address. In general, we recommend that you provide this data, as it is used in a number of risk checks (for instance, number of payment attempts or location-based checks).
> Required for 3D Secure 2 transactions. This field is also mandatory for some merchants depending on your business model. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new).
type: string
shopperInteraction:
description: |-
@@ -764,7 +770,7 @@ components:
description: |-
The 3D request data for the issuer.
If the value is **CUPSecurePlus-CollectSMSVerificationCode**, collect an SMS code from the shopper and pass it in the `/authorise3D` request. For more information, see [3D Secure](https://docs.adyen.com/developers/risk-management/3d-secure).
If the value is **CUPSecurePlus-CollectSMSVerificationCode**, collect an SMS code from the shopper and pass it in the `/authorise3D` request. For more information, see [3D Secure](https://docs.adyen.com/classic-integration/3d-secure).
type: string
pspReference:
description: |-
@@ -782,21 +788,29 @@ components:
description: |-
The result of the payment. Possible values:
* **Authorised** – Indicates the payment authorisation was successfully completed. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state.
* **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state.
* **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation.
* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.
* **AuthenticationFinished** – The payment has been successfully authenticated with 3D Secure 2. Returned for 3D Secure 2 authentication-only transactions.
* **Authorised** – The payment was successfully authorised. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state.
* **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state.
* **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/developers/development-resources/payments-with-pending-status).
* **Error** – Indicates an error occurred during processing of the payment. The reason is given in the `refusalReason` field. This is a final state.
* **ChallengeShopper** – The issuer requires further shopper interaction before the payment can be authenticated. Returned for 3D Secure 2 transactions.
* **Error** – There was an error when the payment was being processed. The reason is given in the `refusalReason` field. This is a final state.
* **IdentifyShopper** – The issuer requires the shopper's device fingerprint before the payment can be authenticated. Returned for 3D Secure 2 transactions.
* **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/development-resources/payments-with-pending-status).
* **PresentToShopper** – Indicates that the response contains additional information that you need to present to a shopper, so that they can use it to complete a payment.
* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.
* **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation.
* **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state.
enum:
- AuthenticationFinished
- Authorised
- PartiallyAuthorised
- Refused
- Error
- Cancelled
- ChallengeShopper
- Error
- IdentifyShopper
- Pending
- PresentToShopper
- Received
- RedirectShopper
- Refused
type: string
Recurring:
properties:
@@ -804,10 +818,10 @@ components:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/developers/payment-glossary#cardnotpresentcnp).
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/developers/features/third-party-payouts).
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
@@ -1146,7 +1160,10 @@ components:
ThreeDSecureData:
properties:
authenticationResponse:
description: The authentication response if the shopper was redirected.
description: |-
In 3D Secure 1, the authentication response if the shopper was redirected.
In 3D Secure 2, this is the `transStatus` from the challenge result. If the transaction was frictionless, set this value to **Y**.
enum:
- 'Y'
- 'N'
@@ -1158,20 +1175,27 @@ components:
format: byte
type: string
cavvAlgorithm:
description: The CAVV algorithm used.
description: The CAVV algorithm used. Include this only for 3D Secure 1.
type: string
directoryResponse:
description: The enrollment response from the 3D directory server.
description: |-
In 3D Secure 1, this is the enrollment response from the 3D directory server.
In 3D Secure 2, this is the `transStatus` from the `ARes`. The possible values are **A** or **Y** for a frictionless flow, or **C** for a challenge flow.
enum:
- 'Y'
- A
- C
- D
- I
- 'N'
- R
- U
- E
- 'Y'
type: string
eci:
description: The electronic commerce indicator.
type: string
xid:
description: 'The transaction identifier (base64 encoded, 20 bytes in a decoded form).'
description: 'Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).'
format: byte
type: string

1695
specs/yaml/PayoutService-v40.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

1698
specs/yaml/PayoutService-v46.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

1715
specs/yaml/PayoutService-v49.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

1739
specs/yaml/PayoutService-v50.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

1743
specs/yaml/PayoutService-v51.yaml Normal file
View File

File diff suppressed because it is too large Load Diff

216
specs/yaml/RecurringService-v18.yaml
View File

@@ -3,8 +3,34 @@ servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v18'
info:
version: '18'
title: Adyen Recurring Service
description: 'Additional methods that allow you to manage payment details stored for recurring payments. For more information, refer to [Recurring payments](https://docs.adyen.com/developers/features/recurring-payments).'
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/checkout/tokenization).
## Authentication
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
-U "ws@Company.YourCompany":"YourWsPassword" \
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
Recurring API supports versioning of its endpoints through 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/v18/disable
```
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
url: 'https://support.adyen.com/'
email: support@adyen.com
x-groups:
- General
paths:
@@ -14,7 +40,7 @@ paths:
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/developers/features/recurring-payments/disable-stored-details).
For more information, refer to [Disable stored details](https://docs.adyen.com/classic-integration/recurring-payments/disable-stored-details/).
x-groupName: General
x-sortIndex: 2
requestBody:
@@ -45,7 +71,7 @@ paths:
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/developers/features/recurring-payments/retrieve-stored-details).
For more information, refer to [Retrieve stored details](https://docs.adyen.com/classic-integration/recurring-payments/retrieve-stored-details/).
x-groupName: General
x-sortIndex: 1
requestBody:
@@ -70,34 +96,70 @@ paths:
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/scheduleAccountUpdater:
post:
summary: Schedules running of 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-groupName: General
x-sortIndex: 3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
Address:
properties:
city:
description: The city name.
description: The name of the city.
type: string
country:
description: A valid value is an ISO two-character country code (e.g. 'NL').
description: |-
The two-character country code as defined in ISO-3166-1 alpha-2. 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 house number or name.
description: The number or name of the house.
type: string
postalCode:
description: The postal code with a maximum of 5 characters for USA and maximum of 10 characters for any other country.
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: 'For USA or Canada, a valid 2-character abbreviation for the state or province respectively. For other countries any abbreviation with maximum 3 characters for the state or province.'
description: |-
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |
The street name.
> Don't append the house number to this field. Instead, pass the house number separately as `houseNumberOrName`.
description: |-
The name of the street.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
BankAccount:
properties:
@@ -148,11 +210,11 @@ components:
$ref: '#/components/schemas/Address'
cvc:
description: |-
The [card verification code](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid) (1-20 characters). Depending on the card brand, it is known also as:
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/developers/ecommerce-integration), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/features/recurring-payments).
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
@@ -217,7 +279,7 @@ components:
* PAYOUT
type: string
merchantAccount:
description: Your merchant account.
description: The merchant account identifier with which you want to process the transaction.
type: string
recurringDetailReference:
description: |-
@@ -236,33 +298,18 @@ components:
- shopperReference
DisableResult:
properties:
details:
description: A list of one or more recurring payment details that were disabled.
items:
$ref: '#/components/schemas/RecurringDetail'
type: array
response:
description: 'Depending on whether a specific recurring detail was in the request, result is either [detail-successfully-disabled] or [all-details-successfully-disabled].'
type: string
ELV:
properties:
accountHolderName:
type: string
bankAccountNumber:
type: string
bankLocation:
type: string
bankLocationId:
type: string
bankName:
type: string
Name:
properties:
firstName:
description: A person's first name.
description: The first name.
type: string
gender:
description: A person's gender (can be unknown).
description: |-
The gender.
>The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`.
enum:
- MALE
- FEMALE
@@ -271,10 +318,12 @@ components:
minLength: 1
type: string
infix:
description: 'A person name''s infix, if applicable. Maximum length: 20 characters.'
description: |-
The name's infix, if applicable.
>A maximum length of twenty (20) characters is imposed.
type: string
lastName:
description: A person's last name.
description: The last name.
type: string
required:
- firstName
@@ -286,9 +335,10 @@ components:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – The shopper opts to store their card details for future use. The shopper is present for the subsequent transaction, for cards the security code (CVC/CVV) is required.
* `RECURRING` – Payment details are stored for future use. For cards, the security code (CVC/CVV) is not required for subsequent payments. This is used for shopper not present transactions.
* `ONECLICK,RECURRING` – Payment details are stored for future use. This allows the use of the stored payment details regardless of whether the shopper is on your site or not.
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
@@ -299,51 +349,66 @@ components:
type: string
RecurringDetail:
properties:
acquirer:
type: string
acquirerAccount:
type: string
additionalData:
additionalProperties:
type: string
description: |-
This field contains additional data, which may be returned in a particular response.
The additionalData object consists of entries, each of which includes the key and value.
type: object
alias:
description: |-
The alias of the credit card number.
Applies only to recurring contracts storing credit card details
type: string
aliasType:
description: |-
The alias type of the credit card number.
Applies only to recurring contracts storing credit card details.
type: string
bank:
description: A container for bank account data.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The billing address.
$ref: '#/components/schemas/Address'
card:
description: A container for card data.
$ref: '#/components/schemas/Card'
contractTypes:
description: Types of recurring contracts.
items:
type: string
type: array
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
elv:
$ref: '#/components/schemas/ELV'
firstPspReference:
description: The `pspReference` of the first recurring payment that created the recurring detail.
type: string
name:
description: An optional descriptive name for this recurring detail
description: An optional descriptive name for this recurring detail.
type: string
paymentMethodVariant:
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/api-reference/common-api/paymentmethodvariant).'
type: string
recurringDetailReference:
description: The reference that uniquely identifies the recurring detail
description: The reference that uniquely identifies the recurring detail.
type: string
shopperName:
description: The name of the shopper.
$ref: '#/components/schemas/Name'
socialSecurityNumber:
description: A shopper's social security number (only in countries where it is legal to collect).
type: string
tokenDetails:
$ref: '#/components/schemas/TokenDetails'
variant:
description: 'The payment method, such as “mc", "visa", "ideal", "paypal".'
type: string
required:
- recurringDetailReference
- variant
RecurringDetailsRequest:
properties:
merchantAccount:
@@ -369,7 +434,7 @@ components:
format: date-time
type: string
details:
description: A list of one or more recurring payment details.
description: Payment details stored for recurring payments.
items:
$ref: '#/components/schemas/RecurringDetail'
type: array
@@ -379,11 +444,46 @@ components:
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
TokenDetails:
ScheduleAccountUpdaterRequest:
properties:
tokenData:
additionalProperties:
type: string
additionalData:
description: 'This field contains additional data, which may be required for a particular request.'
type: object
tokenDataType:
card:
description: |-
A container for credit card data.
Optional if `shopperReference` and `selectedRecurringDetailReference` are provided.
$ref: '#/components/schemas/Card'
merchantAccount:
description: Account of the merchant.
type: string
reference:
description: A reference that merchants can apply for the call.
type: string
selectedRecurringDetailReference:
description: |-
The selected detail recurring reference.
Optional if `card` is provided.
type: string
shopperReference:
description: |-
The reference of the shopper that owns the recurring contract.
Optional if `card` is provided.
type: string
required:
- merchantAccount
- reference
ScheduleAccountUpdaterResult:
properties:
pspReference:
description: Adyen's 16-character unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.
type: string
result:
description: 'The result of scheduling an Account Updater. If scheduling was successful, this field returns **Success**; otherwise it contains the error message.'
type: string
required:
- pspReference
- result

130
specs/yaml/RecurringService-v25.yaml
View File

@@ -3,13 +3,13 @@ servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v25'
info:
version: '25'
title: Adyen Recurring Service
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/developers/features/tokenization).
For more information, refer to our [Tokenization documentation](https://docs.adyen.com/checkout/tokenization).
## Authentication
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/developers/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
@@ -17,7 +17,7 @@ info:
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/developers/development-resources/live-endpoints).
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
Recurring API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number.
@@ -40,7 +40,7 @@ paths:
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/developers/features/recurring-payments/disable-stored-details).
For more information, refer to [Disable stored details](https://docs.adyen.com/classic-integration/recurring-payments/disable-stored-details/).
x-groupName: General
x-sortIndex: 2
requestBody:
@@ -71,7 +71,7 @@ paths:
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/developers/features/recurring-payments/retrieve-stored-details).
For more information, refer to [Retrieve stored details](https://docs.adyen.com/classic-integration/recurring-payments/retrieve-stored-details/).
x-groupName: General
x-sortIndex: 1
requestBody:
@@ -96,42 +96,70 @@ paths:
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/scheduleAccountUpdater:
post:
summary: Schedules running of 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-groupName: General
x-sortIndex: 3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
Address:
properties:
city:
description: |-
The name of the city.
>Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided.
description: The name of the city.
type: string
country:
description: |-
The two-character country code of the address
>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').
The two-character country code as defined in ISO-3166-1 alpha-2. 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.
type: string
postalCode:
description: |-
The postal code.
>A maximum of five (5) digits for an address in the USA, or a maximum of ten (10) characters for an address in all other countries.
>Required if either houseNumberOrName, street, city, or stateOrProvince are provided.
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 abbreviation of the state or province.
>Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries.
>Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided.
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |-
The name of the street.
>The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
>Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
BankAccount:
properties:
@@ -180,11 +208,11 @@ components:
properties:
cvc:
description: |-
The [card verification code](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid) (1-20 characters). Depending on the card brand, it is known also as:
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/developers/features/client-side-encryption), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/classic-integration/recurring-payments).
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
@@ -305,10 +333,10 @@ components:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/developers/payment-glossary#cardsecuritycodecvccvvcid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/developers/payment-glossary#cardnotpresentcnp).
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/developers/features/third-party-payouts).
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
@@ -329,7 +357,7 @@ components:
description: |-
This field contains additional data, which may be returned in a particular response.
The additionalData object consists of entries, each of which includes the key and value. For more information on possible key-value pairs, refer to [RecurringDetail.additionalData](https://docs.adyen.com/developers/api-reference/recurring-api#recurringdetailadditionaldata).
The additionalData object consists of entries, each of which includes the key and value.
type: object
alias:
description: |-
@@ -368,7 +396,7 @@ components:
description: An optional descriptive name for this recurring detail.
type: string
paymentMethodVariant:
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/developers/api-reference/common-api/paymentmethodvariant).'
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/api-reference/common-api/paymentmethodvariant).'
type: string
recurringDetailReference:
description: The reference that uniquely identifies the recurring detail.
@@ -423,47 +451,43 @@ components:
ScheduleAccountUpdaterRequest:
properties:
additionalData:
additionalProperties:
type: string
description: 'This field contains additional data, which may be required for a particular request.'
type: object
card:
description: |-
A container for credit card data.
Optional if `shopperReference` and `selectedRecurringDetailReference` are provided.
$ref: '#/components/schemas/Card'
genericBlockId:
format: int64
type: integer
genericFileId:
format: int64
type: integer
genericLineId:
format: int64
type: integer
merchantAccount:
description: Account of the merchant.
type: string
reference:
description: A reference that merchants can apply for the call.
type: string
selectedRecurringDetailReference:
description: |-
The selected detail recurring reference.
Optional if `card` is provided.
type: string
shopperReference:
type: string
updateAfter:
format: date-time
description: |-
The reference of the shopper that owns the recurring contract.
Optional if `card` is provided.
type: string
required:
- merchantAccount
- reference
ScheduleAccountUpdaterResult:
properties:
accountUpdaterAction:
type: string
newAlias:
type: string
newExpiryMonth:
type: string
newExpiryYear:
type: string
processedDate:
format: date-time
type: string
pspReference:
description: Adyen's 16-character unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.
type: string
result:
description: 'The result of scheduling an Account Updater. If scheduling was successful, this field returns **Success**; otherwise it contains the error message.'
type: string
required:
- pspReference
- result

493
specs/yaml/RecurringService-v30.yaml Normal file
View File

@@ -0,0 +1,493 @@
openapi: 3.0.0
servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v30'
info:
version: '30'
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/checkout/tokenization).
## Authentication
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
-U "ws@Company.YourCompany":"YourWsPassword" \
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
Recurring API supports versioning of its endpoints through 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/v30/disable
```
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
url: 'https://support.adyen.com/'
email: support@adyen.com
x-groups:
- General
paths:
/disable:
post:
summary: Disables 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/).
x-groupName: General
x-sortIndex: 2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DisableRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DisableResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/listRecurringDetails:
post:
summary: Retrieves stored payment details for a shopper.
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/).
x-groupName: General
x-sortIndex: 1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/scheduleAccountUpdater:
post:
summary: Schedules running of 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-groupName: General
x-sortIndex: 3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
Address:
properties:
city:
description: The name of the city.
type: string
country:
description: |-
The two-character country code as defined in ISO-3166-1 alpha-2. 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.
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: |-
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |-
The name of the street.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
BankAccount:
properties:
bankAccountNumber:
description: The bank account number (without separators).
type: string
bankCity:
description: The bank city.
type: string
bankLocationId:
description: The location id of the bank. The field value is `nil` in most cases.
type: string
bankName:
description: The name of the bank.
type: string
bic:
description: 'The [Business Identifier Code](https://en.wikipedia.org/wiki/ISO_9362) (BIC) is the SWIFT address assigned to a bank. The field value is `nil` in most cases.'
type: string
countryCode:
description: |-
Country code where the bank is located.
A valid value is an ISO two-character country code (e.g. 'NL').
type: string
iban:
description: 'The [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) (IBAN).'
type: string
ownerName:
description: |-
The name of the bank account holder.
If you submit a name with non-Latin characters, we automatically replace some of them with corresponding Latin characters to meet the FATF recommendations. For example:
* χ12 is converted to ch12.
* üA is converted to euA.
* Peter Møller is converted to Peter Mller, because banks don't accept 'ø'.
After replacement, the ownerName must have at least three alphanumeric characters (A-Z, a-z, 0-9), and at least one of them must be a valid Latin character (A-Z, a-z). For example:
* John17 - allowed.
* J17 - allowed.
* 171 - not allowed.
* John-7 - allowed.
> If provided details don't match the required format, the response returns the error message: 203 'Invalid bank account holder name'.
type: string
taxId:
description: The bank account holder's tax ID.
type: string
Card:
properties:
cvc:
description: |-
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
type: string
expiryMonth:
description: |-
The card expiry month.
Format: 2 digits, zero-padded for single digits. For example:
* 03 = March
* 11 = November
maxLength: 2
minLength: 1
type: string
expiryYear:
description: |-
The card expiry year.
Format: 4 digits. For example: 2020
maxLength: 4
minLength: 4
type: string
holderName:
description: 'The name of the cardholder, as printed on the card.'
maxLength: 50
minLength: 1
type: string
issueNumber:
description: The issue number of the card (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
number:
description: |-
The card number (4-19 characters). Do not use any separators.
When this value is returned in a response, only the last 4 digits of the card number are returned.
maxLength: 19
minLength: 4
type: string
startMonth:
description: The month component of the start date (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
startYear:
description: The year component of the start date (for some UK debit cards only).
maxLength: 4
minLength: 4
type: string
required:
- number
- expiryMonth
- expiryYear
- holderName
DisableRequest:
properties:
contract:
description: |-
Specify the contract if you only want to disable a specific use.
This field can be set to one of the following values, or to their combination (comma-separated):
* ONECLICK
* RECURRING
* PAYOUT
type: string
merchantAccount:
description: The merchant account identifier with which you want to process the transaction.
type: string
recurringDetailReference:
description: |-
The ID that uniquely identifies the recurring detail reference.
If it is not provided, the whole recurring contract of the `shopperReference` will be disabled, which includes all recurring details.
type: string
shopperReference:
description: |-
The ID that uniquely identifies the shopper.
This `shopperReference` must be the same as the `shopperReference` used in the initial payment.
type: string
required:
- merchantAccount
- shopperReference
DisableResult:
properties:
response:
description: 'Depending on whether a specific recurring detail was in the request, result is either [detail-successfully-disabled] or [all-details-successfully-disabled].'
type: string
Name:
properties:
firstName:
description: The first name.
type: string
gender:
description: |-
The gender.
>The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`.
enum:
- MALE
- FEMALE
- UNKNOWN
maxLength: 1
minLength: 1
type: string
infix:
description: |-
The name's infix, if applicable.
>A maximum length of twenty (20) characters is imposed.
type: string
lastName:
description: The last name.
type: string
required:
- firstName
- lastName
- gender
Recurring:
properties:
contract:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
- PAYOUT
type: string
recurringDetailName:
description: A descriptive name for this detail.
type: string
tokenService:
description: The name of the token service.
enum:
- VISATOKENSERVICE
- MCTOKENSERVICE
type: string
RecurringDetail:
properties:
additionalData:
description: |-
This field contains additional data, which may be returned in a particular response.
The additionalData object consists of entries, each of which includes the key and value.
type: object
alias:
description: |-
The alias of the credit card number.
Applies only to recurring contracts storing credit card details
type: string
aliasType:
description: |-
The alias type of the credit card number.
Applies only to recurring contracts storing credit card details.
type: string
bank:
description: A container for bank account data.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The billing address.
$ref: '#/components/schemas/Address'
card:
description: A container for card data.
$ref: '#/components/schemas/Card'
contractTypes:
description: Types of recurring contracts.
items:
type: string
type: array
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
firstPspReference:
description: The `pspReference` of the first recurring payment that created the recurring detail.
type: string
name:
description: An optional descriptive name for this recurring detail.
type: string
paymentMethodVariant:
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/api-reference/common-api/paymentmethodvariant).'
type: string
recurringDetailReference:
description: The reference that uniquely identifies the recurring detail.
type: string
shopperName:
description: The name of the shopper.
$ref: '#/components/schemas/Name'
socialSecurityNumber:
description: A shopper's social security number (only in countries where it is legal to collect).
type: string
variant:
description: 'The payment method, such as “mc", "visa", "ideal", "paypal".'
type: string
required:
- recurringDetailReference
- variant
RecurringDetailsRequest:
properties:
merchantAccount:
description: The merchant account identifier you want to process the (transaction) request with.
type: string
recurring:
description: |-
A container for the type of a recurring contract to be retrieved.
The contract value needs to match the contract value submitted in the payment transaction used to create a recurring contract.
However, if `ONECLICK,RECURRING` is the original contract definition in the initial payment, then `contract` should take either `ONECLICK` or `RECURRING`, depending on whether or not you want the shopper to enter their card's security code when they finalize their purchase.
$ref: '#/components/schemas/Recurring'
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
required:
- merchantAccount
- shopperReference
RecurringDetailsResult:
properties:
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
details:
description: Payment details stored for recurring payments.
items:
$ref: '#/components/schemas/RecurringDetail'
type: array
lastKnownShopperEmail:
description: The most recent email for this shopper (if available).
type: string
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
ScheduleAccountUpdaterRequest:
properties:
additionalData:
description: 'This field contains additional data, which may be required for a particular request.'
type: object
card:
description: |-
A container for credit card data.
Optional if `shopperReference` and `selectedRecurringDetailReference` are provided.
$ref: '#/components/schemas/Card'
merchantAccount:
description: Account of the merchant.
type: string
reference:
description: A reference that merchants can apply for the call.
type: string
selectedRecurringDetailReference:
description: |-
The selected detail recurring reference.
Optional if `card` is provided.
type: string
shopperReference:
description: |-
The reference of the shopper that owns the recurring contract.
Optional if `card` is provided.
type: string
required:
- merchantAccount
- reference
ScheduleAccountUpdaterResult:
properties:
pspReference:
description: Adyen's 16-character unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.
type: string
result:
description: 'The result of scheduling an Account Updater. If scheduling was successful, this field returns **Success**; otherwise it contains the error message.'
type: string
required:
- pspReference
- result

500
specs/yaml/RecurringService-v40.yaml Normal file
View File

@@ -0,0 +1,500 @@
openapi: 3.0.0
servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v40'
info:
version: '40'
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/checkout/tokenization).
## Authentication
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
-U "ws@Company.YourCompany":"YourWsPassword" \
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
Recurring API supports versioning of its endpoints through 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/v40/disable
```
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
url: 'https://support.adyen.com/'
email: support@adyen.com
x-groups:
- General
paths:
/disable:
post:
summary: Disables 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/).
x-groupName: General
x-sortIndex: 2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DisableRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DisableResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/listRecurringDetails:
post:
summary: Retrieves stored payment details for a shopper.
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/).
x-groupName: General
x-sortIndex: 1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/scheduleAccountUpdater:
post:
summary: Schedules running of 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-groupName: General
x-sortIndex: 3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
Address:
properties:
city:
description: The name of the city.
type: string
country:
description: |-
The two-character country code as defined in ISO-3166-1 alpha-2. 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.
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: |-
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |-
The name of the street.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
BankAccount:
properties:
bankAccountNumber:
description: The bank account number (without separators).
type: string
bankCity:
description: The bank city.
type: string
bankLocationId:
description: The location id of the bank. The field value is `nil` in most cases.
type: string
bankName:
description: The name of the bank.
type: string
bic:
description: 'The [Business Identifier Code](https://en.wikipedia.org/wiki/ISO_9362) (BIC) is the SWIFT address assigned to a bank. The field value is `nil` in most cases.'
type: string
countryCode:
description: |-
Country code where the bank is located.
A valid value is an ISO two-character country code (e.g. 'NL').
type: string
iban:
description: 'The [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) (IBAN).'
type: string
ownerName:
description: |-
The name of the bank account holder.
If you submit a name with non-Latin characters, we automatically replace some of them with corresponding Latin characters to meet the FATF recommendations. For example:
* χ12 is converted to ch12.
* üA is converted to euA.
* Peter Møller is converted to Peter Mller, because banks don't accept 'ø'.
After replacement, the ownerName must have at least three alphanumeric characters (A-Z, a-z, 0-9), and at least one of them must be a valid Latin character (A-Z, a-z). For example:
* John17 - allowed.
* J17 - allowed.
* 171 - not allowed.
* John-7 - allowed.
> If provided details don't match the required format, the response returns the error message: 203 'Invalid bank account holder name'.
type: string
taxId:
description: The bank account holder's tax ID.
type: string
Card:
properties:
cvc:
description: |-
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
type: string
expiryMonth:
description: |-
The card expiry month.
Format: 2 digits, zero-padded for single digits. For example:
* 03 = March
* 11 = November
maxLength: 2
minLength: 1
type: string
expiryYear:
description: |-
The card expiry year.
Format: 4 digits. For example: 2020
maxLength: 4
minLength: 4
type: string
holderName:
description: 'The name of the cardholder, as printed on the card.'
maxLength: 50
minLength: 1
type: string
issueNumber:
description: The issue number of the card (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
number:
description: |-
The card number (4-19 characters). Do not use any separators.
When this value is returned in a response, only the last 4 digits of the card number are returned.
maxLength: 19
minLength: 4
type: string
startMonth:
description: The month component of the start date (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
startYear:
description: The year component of the start date (for some UK debit cards only).
maxLength: 4
minLength: 4
type: string
required:
- number
- expiryMonth
- expiryYear
- holderName
DisableRequest:
properties:
contract:
description: |-
Specify the contract if you only want to disable a specific use.
This field can be set to one of the following values, or to their combination (comma-separated):
* ONECLICK
* RECURRING
* PAYOUT
type: string
merchantAccount:
description: The merchant account identifier with which you want to process the transaction.
type: string
recurringDetailReference:
description: |-
The ID that uniquely identifies the recurring detail reference.
If it is not provided, the whole recurring contract of the `shopperReference` will be disabled, which includes all recurring details.
type: string
shopperReference:
description: |-
The ID that uniquely identifies the shopper.
This `shopperReference` must be the same as the `shopperReference` used in the initial payment.
type: string
required:
- merchantAccount
- shopperReference
DisableResult:
properties:
response:
description: 'Depending on whether a specific recurring detail was in the request, result is either [detail-successfully-disabled] or [all-details-successfully-disabled].'
type: string
Name:
properties:
firstName:
description: The first name.
type: string
gender:
description: |-
The gender.
>The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`.
enum:
- MALE
- FEMALE
- UNKNOWN
maxLength: 1
minLength: 1
type: string
infix:
description: |-
The name's infix, if applicable.
>A maximum length of twenty (20) characters is imposed.
type: string
lastName:
description: The last name.
type: string
required:
- firstName
- lastName
- gender
Recurring:
properties:
contract:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
- PAYOUT
type: string
recurringDetailName:
description: A descriptive name for this detail.
type: string
recurringExpiry:
description: Date after which no further authorisations shall be performed. Only for 3D Secure 2.
format: date-time
type: string
recurringFrequency:
description: Minimum number of days between authorisations. Only for 3D Secure 2.
type: string
tokenService:
description: The name of the token service.
enum:
- VISATOKENSERVICE
- MCTOKENSERVICE
type: string
RecurringDetail:
properties:
additionalData:
description: |-
This field contains additional data, which may be returned in a particular response.
The additionalData object consists of entries, each of which includes the key and value.
type: object
alias:
description: |-
The alias of the credit card number.
Applies only to recurring contracts storing credit card details
type: string
aliasType:
description: |-
The alias type of the credit card number.
Applies only to recurring contracts storing credit card details.
type: string
bank:
description: A container for bank account data.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The billing address.
$ref: '#/components/schemas/Address'
card:
description: A container for card data.
$ref: '#/components/schemas/Card'
contractTypes:
description: Types of recurring contracts.
items:
type: string
type: array
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
firstPspReference:
description: The `pspReference` of the first recurring payment that created the recurring detail.
type: string
name:
description: An optional descriptive name for this recurring detail.
type: string
paymentMethodVariant:
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/api-reference/common-api/paymentmethodvariant).'
type: string
recurringDetailReference:
description: The reference that uniquely identifies the recurring detail.
type: string
shopperName:
description: The name of the shopper.
$ref: '#/components/schemas/Name'
socialSecurityNumber:
description: A shopper's social security number (only in countries where it is legal to collect).
type: string
variant:
description: 'The payment method, such as “mc", "visa", "ideal", "paypal".'
type: string
required:
- recurringDetailReference
- variant
RecurringDetailsRequest:
properties:
merchantAccount:
description: The merchant account identifier you want to process the (transaction) request with.
type: string
recurring:
description: |-
A container for the type of a recurring contract to be retrieved.
The contract value needs to match the contract value submitted in the payment transaction used to create a recurring contract.
However, if `ONECLICK,RECURRING` is the original contract definition in the initial payment, then `contract` should take either `ONECLICK` or `RECURRING`, depending on whether or not you want the shopper to enter their card's security code when they finalize their purchase.
$ref: '#/components/schemas/Recurring'
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
required:
- merchantAccount
- shopperReference
RecurringDetailsResult:
properties:
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
details:
description: Payment details stored for recurring payments.
items:
$ref: '#/components/schemas/RecurringDetail'
type: array
lastKnownShopperEmail:
description: The most recent email for this shopper (if available).
type: string
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
ScheduleAccountUpdaterRequest:
properties:
additionalData:
description: 'This field contains additional data, which may be required for a particular request.'
type: object
card:
description: |-
A container for credit card data.
Optional if `shopperReference` and `selectedRecurringDetailReference` are provided.
$ref: '#/components/schemas/Card'
merchantAccount:
description: Account of the merchant.
type: string
reference:
description: A reference that merchants can apply for the call.
type: string
selectedRecurringDetailReference:
description: |-
The selected detail recurring reference.
Optional if `card` is provided.
type: string
shopperReference:
description: |-
The reference of the shopper that owns the recurring contract.
Optional if `card` is provided.
type: string
required:
- merchantAccount
- reference
ScheduleAccountUpdaterResult:
properties:
pspReference:
description: Adyen's 16-character unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.
type: string
result:
description: 'The result of scheduling an Account Updater. If scheduling was successful, this field returns **Success**; otherwise it contains the error message.'
type: string
required:
- pspReference
- result

500
specs/yaml/RecurringService-v49.yaml Normal file
View File

@@ -0,0 +1,500 @@
openapi: 3.0.0
servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v49'
info:
version: '49'
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/checkout/tokenization).
## Authentication
To connect to the Recurring API, you must use your basic authentication credentials. For this, create your web service user, as described in [How to get the WS user password](https://docs.adyen.com/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
-U "ws@Company.YourCompany":"YourWsPassword" \
-H "Content-Type: application/json" \
...
```
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).
## Versioning
Recurring API supports versioning of its endpoints through 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/v49/disable
```
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
url: 'https://support.adyen.com/'
email: support@adyen.com
x-groups:
- General
paths:
/disable:
post:
summary: Disables 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/).
x-groupName: General
x-sortIndex: 2
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DisableRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DisableResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/listRecurringDetails:
post:
summary: Retrieves stored payment details for a shopper.
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/).
x-groupName: General
x-sortIndex: 1
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RecurringDetailsResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
/scheduleAccountUpdater:
post:
summary: Schedules running of 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-groupName: General
x-sortIndex: 3
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduleAccountUpdaterResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
Address:
properties:
city:
description: The name of the city.
type: string
country:
description: |-
The two-character country code as defined in ISO-3166-1 alpha-2. 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.
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: |-
State or province codes as defined in ISO 3166-2. For example, **SF** in US or **ON** for Canada.
> Required for the US and Canada.
type: string
street:
description: |-
The name of the street.
> The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.
type: string
required:
- street
- houseNumberOrName
- city
- postalCode
- country
BankAccount:
properties:
bankAccountNumber:
description: The bank account number (without separators).
type: string
bankCity:
description: The bank city.
type: string
bankLocationId:
description: The location id of the bank. The field value is `nil` in most cases.
type: string
bankName:
description: The name of the bank.
type: string
bic:
description: 'The [Business Identifier Code](https://en.wikipedia.org/wiki/ISO_9362) (BIC) is the SWIFT address assigned to a bank. The field value is `nil` in most cases.'
type: string
countryCode:
description: |-
Country code where the bank is located.
A valid value is an ISO two-character country code (e.g. 'NL').
type: string
iban:
description: 'The [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) (IBAN).'
type: string
ownerName:
description: |-
The name of the bank account holder.
If you submit a name with non-Latin characters, we automatically replace some of them with corresponding Latin characters to meet the FATF recommendations. For example:
* χ12 is converted to ch12.
* üA is converted to euA.
* Peter Møller is converted to Peter Mller, because banks don't accept 'ø'.
After replacement, the ownerName must have at least three alphanumeric characters (A-Z, a-z, 0-9), and at least one of them must be a valid Latin character (A-Z, a-z). For example:
* John17 - allowed.
* J17 - allowed.
* 171 - not allowed.
* John-7 - allowed.
> If provided details don't match the required format, the response returns the error message: 203 'Invalid bank account holder name'.
type: string
taxId:
description: The bank account holder's tax ID.
type: string
Card:
properties:
cvc:
description: |-
The [card verification code](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
type: string
expiryMonth:
description: |-
The card expiry month.
Format: 2 digits, zero-padded for single digits. For example:
* 03 = March
* 11 = November
maxLength: 2
minLength: 1
type: string
expiryYear:
description: |-
The card expiry year.
Format: 4 digits. For example: 2020
maxLength: 4
minLength: 4
type: string
holderName:
description: 'The name of the cardholder, as printed on the card.'
maxLength: 50
minLength: 1
type: string
issueNumber:
description: The issue number of the card (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
number:
description: |-
The card number (4-19 characters). Do not use any separators.
When this value is returned in a response, only the last 4 digits of the card number are returned.
maxLength: 19
minLength: 4
type: string
startMonth:
description: The month component of the start date (for some UK debit cards only).
maxLength: 2
minLength: 1
type: string
startYear:
description: The year component of the start date (for some UK debit cards only).
maxLength: 4
minLength: 4
type: string
required:
- number
- expiryMonth
- expiryYear
- holderName
DisableRequest:
properties:
contract:
description: |-
Specify the contract if you only want to disable a specific use.
This field can be set to one of the following values, or to their combination (comma-separated):
* ONECLICK
* RECURRING
* PAYOUT
type: string
merchantAccount:
description: The merchant account identifier with which you want to process the transaction.
type: string
recurringDetailReference:
description: |-
The ID that uniquely identifies the recurring detail reference.
If it is not provided, the whole recurring contract of the `shopperReference` will be disabled, which includes all recurring details.
type: string
shopperReference:
description: |-
The ID that uniquely identifies the shopper.
This `shopperReference` must be the same as the `shopperReference` used in the initial payment.
type: string
required:
- merchantAccount
- shopperReference
DisableResult:
properties:
response:
description: 'Depending on whether a specific recurring detail was in the request, result is either [detail-successfully-disabled] or [all-details-successfully-disabled].'
type: string
Name:
properties:
firstName:
description: The first name.
type: string
gender:
description: |-
The gender.
>The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`.
enum:
- MALE
- FEMALE
- UNKNOWN
maxLength: 1
minLength: 1
type: string
infix:
description: |-
The name's infix, if applicable.
>A maximum length of twenty (20) characters is imposed.
type: string
lastName:
description: The last name.
type: string
required:
- firstName
- lastName
- gender
Recurring:
properties:
contract:
description: |-
The type of recurring contract to be used.
Possible values:
* `ONECLICK` – Payment details can be used to initiate a one-click payment, where the shopper enters the [card security code (CVC/CVV)](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-security-code-cvc-cvv-cid).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/payments-fundamentals/payment-glossary#card-not-present-cnp).
* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/checkout/online-payouts).
enum:
- ONECLICK
- RECURRING
- PAYOUT
type: string
recurringDetailName:
description: A descriptive name for this detail.
type: string
recurringExpiry:
description: Date after which no further authorisations shall be performed. Only for 3D Secure 2.
format: date-time
type: string
recurringFrequency:
description: Minimum number of days between authorisations. Only for 3D Secure 2.
type: string
tokenService:
description: The name of the token service.
enum:
- VISATOKENSERVICE
- MCTOKENSERVICE
type: string
RecurringDetail:
properties:
additionalData:
description: |-
This field contains additional data, which may be returned in a particular response.
The additionalData object consists of entries, each of which includes the key and value.
type: object
alias:
description: |-
The alias of the credit card number.
Applies only to recurring contracts storing credit card details
type: string
aliasType:
description: |-
The alias type of the credit card number.
Applies only to recurring contracts storing credit card details.
type: string
bank:
description: A container for bank account data.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The billing address.
$ref: '#/components/schemas/Address'
card:
description: A container for card data.
$ref: '#/components/schemas/Card'
contractTypes:
description: Types of recurring contracts.
items:
type: string
type: array
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
firstPspReference:
description: The `pspReference` of the first recurring payment that created the recurring detail.
type: string
name:
description: An optional descriptive name for this recurring detail.
type: string
paymentMethodVariant:
description: 'The type or sub-brand of a payment method used, e.g. Visa Debit, Visa Corporate, etc. For more information, refer to [PaymentMethodVariant](https://docs.adyen.com/api-reference/common-api/paymentmethodvariant).'
type: string
recurringDetailReference:
description: The reference that uniquely identifies the recurring detail.
type: string
shopperName:
description: The name of the shopper.
$ref: '#/components/schemas/Name'
socialSecurityNumber:
description: A shopper's social security number (only in countries where it is legal to collect).
type: string
variant:
description: 'The payment method, such as “mc", "visa", "ideal", "paypal".'
type: string
required:
- recurringDetailReference
- variant
RecurringDetailsRequest:
properties:
merchantAccount:
description: The merchant account identifier you want to process the (transaction) request with.
type: string
recurring:
description: |-
A container for the type of a recurring contract to be retrieved.
The contract value needs to match the contract value submitted in the payment transaction used to create a recurring contract.
However, if `ONECLICK,RECURRING` is the original contract definition in the initial payment, then `contract` should take either `ONECLICK` or `RECURRING`, depending on whether or not you want the shopper to enter their card's security code when they finalize their purchase.
$ref: '#/components/schemas/Recurring'
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
required:
- merchantAccount
- shopperReference
RecurringDetailsResult:
properties:
creationDate:
description: The date when the recurring details were created.
format: date-time
type: string
details:
description: Payment details stored for recurring payments.
items:
$ref: '#/components/schemas/RecurringDetail'
type: array
lastKnownShopperEmail:
description: The most recent email for this shopper (if available).
type: string
shopperReference:
description: The reference you use to uniquely identify the shopper (e.g. user ID or account ID).
type: string
ScheduleAccountUpdaterRequest:
properties:
additionalData:
description: 'This field contains additional data, which may be required for a particular request.'
type: object
card:
description: |-
A container for credit card data.
Optional if `shopperReference` and `selectedRecurringDetailReference` are provided.
$ref: '#/components/schemas/Card'
merchantAccount:
description: Account of the merchant.
type: string
reference:
description: A reference that merchants can apply for the call.
type: string
selectedRecurringDetailReference:
description: |-
The selected detail recurring reference.
Optional if `card` is provided.
type: string
shopperReference:
description: |-
The reference of the shopper that owns the recurring contract.
Optional if `card` is provided.
type: string
required:
- merchantAccount
- reference
ScheduleAccountUpdaterResult:
properties:
pspReference:
description: Adyen's 16-character unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.
type: string
result:
description: 'The result of scheduling an Account Updater. If scheduling was successful, this field returns **Success**; otherwise it contains the error message.'
type: string
required:
- pspReference
- result

217
specs/yaml/TestCardService-v1.yaml Normal file
View File

@@ -0,0 +1,217 @@
openapi: 3.0.0
servers:
- url: 'https://pal-test.adyen.com/pal/services/TestCard/v1'
info:
version: '1'
title: Adyen Test Cards API
description: 'The Test Cards API provides endpoints for generating custom test card numbers. For more information, refer to [Custom test cards](https://docs.adyen.com/development-resources/test-cards/create-test-cards) documentation.'
termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
contact:
name: Adyen Support
url: 'https://support.adyen.com/'
email: support@adyen.com
x-groups:
- General
paths:
/createTestCardRanges:
post:
summary: Creates one or more test card ranges.
description: Creates one or more test card ranges.
x-groupName: General
x-sortIndex: 0
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTestCardRangesRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CreateTestCardRangesResult'
description: OK - the request has succeeded.
'400':
description: Bad Request - a problem reading or understanding the request.
'401':
description: Unauthorized - authentication required.
'403':
description: Forbidden - insufficient permissions to process the request.
'422':
description: Unprocessable Entity - a request validation error.
'500':
description: Internal Server Error - the server could not process the request.
components:
schemas:
AvsAddress:
properties:
streetAddress:
description: |-
The street and house number of the address.
Example: 1 Infinite Loop, Cupertino.
type: string
zip:
description: |-
The zip or post code of the address.
Example: CA 95014
type: string
required:
- streetAddress
CreateTestCardRangesRequest:
properties:
accountCode:
description: 'The code of the account, for which the test card ranges should be created.'
type: string
accountTypeCode:
description: |-
The type of the account, for which the test card ranges should be created.
Permitted values:
* Company
* MerchantAccount
> These values are case-sensitive.
type: string
testCardRanges:
description: A list of test card ranges to create.
items:
$ref: '#/components/schemas/TestCardRange'
type: array
required:
- accountTypeCode
- accountCode
- testCardRanges
CreateTestCardRangesResult:
properties:
rangeCreationResults:
description: The results of the test card creation.
items:
$ref: '#/components/schemas/TestCardRangeCreationResult'
type: array
required:
- rangeCreationResults
TestCardRange:
properties:
address:
description: 'Contains the billing address of the card holder. The address details need to be AVS-compliant, which means that you need to provide at least street address.'
$ref: '#/components/schemas/AvsAddress'
cardHolderName:
description: 'The name of the card holder, as it appears on the card, for the test card range.'
type: string
cvc:
description: |-
The test card range security code.
Example: 123
type: string
expiryMonth:
description: |-
Expiry month for the test card range.
Allowed values:
* JANUARY
* FEBRUARY
* MARCH
* APRIL
* MAY
* JUNE
* JULY
* AUGUST
* SEPTEMBER
* OCTOBER
* NOVEMBER
* DECEMBER
enum:
- APRIL
- AUGUST
- DECEMBER
- FEBRUARY
- JANUARY
- JULY
- JUNE
- MARCH
- MAY
- NOVEMBER
- OCTOBER
- SEPTEMBER
type: string
expiryYear:
description: |-
Expiry year for the test card range.
Example: 2020
format: int32
type: integer
rangeEnd:
description: |-
The last test card number in the test card range (inclusive):
* Min 6, max 19 digits
* BIN compliant
Example: 5432 1234 1234 4321
type: string
rangeStart:
description: |-
The first test card number in the test card range (inclusive):
* Min 6, max 19 digits
* BIN compliant
Example: 5432 1234 1234 1234
type: string
threeDDirectoryServerResponse:
description: |-
3D Secure server response. It notifies whether the specified card holder is enrolled in a 3D Secure service. Possible values:
* Y (Authentication available)
* N (Card holder not enrolled/not participating)
* U (Unable to authenticate)
enum:
- 'N'
- U
- 'Y'
type: string
threeDPassword:
description: The password used for 3D Secure authentication.
type: string
threeDUsername:
description: The username used for 3D Secure authentication.
type: string
required:
- rangeStart
- rangeEnd
- expiryMonth
- expiryYear
- cardHolderName
TestCardRangeCreationResult:
properties:
cardNumberRangeEnd:
description: |-
The last test card number in the generated test card range.
Example: 5432 1234 1234 4321
type: string
cardNumberRangeStart:
description: |-
The first test card number in the generated test card range.
Example: 5432 1234 1234 1234
type: string
creationResultCode:
description: |-
Notification message. It informs about the outcome of the operation. Possible values:
* CREATED
* ALREADY_EXISTS
* ERROR
enum:
- ALREADY_EXISTS
- CREATED
- ERROR
type: string
message:
description: An optional information message about the result.
type: string
required:
- cardNumberRangeStart
- cardNumberRangeEnd
- creationResultCode