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
Files
62bb23ba23e77b82740577253dd34de85b70d345
adyen-openapi/yaml/RecurringService-v25.yaml
aleksei 62bb23ba23 Updated API definitions for other services
2020-08-05 16:28:16 +02:00

509 lines
21 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
openapi: 3.0.3
servers:
- url: 'https://pal-test.adyen.com/pal/servlet/Recurring/v25'
info:
version: '25'
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/v25/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/).
operationId: post-disable
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/).
operationId: post-listRecurringDetails
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.
operationId: post-scheduleAccountUpdater
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, **CA** in the US or **ON** in 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:
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
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/development-resources/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:
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'
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
securitySchemes:
ApiKeyAuth:
in: header
name: X-API-Key
type: apiKey
BasicAuth:
scheme: basic
type: http
Reference in New Issue View Git Blame Copy Permalink