{ "openapi" : "3.0.0", "servers" : [ { "url" : "https://pal-test.adyen.com/pal/servlet/Recurring/v25" } ], "info" : { "version" : "25", "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)." }, "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.\n\nFor more information, refer to [Disable stored details](https://docs.adyen.com/developers/features/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." }, "422" : { "description" : "Unprocessable Entity - a request validation error." }, "401" : { "description" : "Unauthorized - authentication required." }, "500" : { "description" : "Internal Server Error - the server could not process the request." }, "403" : { "description" : "Forbidden - insufficient permissions to 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.\n\nFor more information, refer to [Retrieve stored details](https://docs.adyen.com/developers/features/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." }, "422" : { "description" : "Unprocessable Entity - a request validation error." }, "401" : { "description" : "Unauthorized - authentication required." }, "500" : { "description" : "Internal Server Error - the server could not process the request." }, "403" : { "description" : "Forbidden - insufficient permissions to process the request." } } } } }, "components" : { "schemas" : { "Address" : { "properties" : { "city" : { "description" : "The name of the city.\n>Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided.", "type" : "string" }, "country" : { "description" : "The two-character country code of the address\n>The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').", "type" : "string" }, "houseNumberOrName" : { "description" : "The number or name of the house.", "type" : "string" }, "postalCode" : { "description" : "The postal code.\n>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.\n>Required if either houseNumberOrName, street, city, or stateOrProvince are provided.", "type" : "string" }, "stateOrProvince" : { "description" : "The abbreviation of the state or province.\n>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.\n>Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided.", "type" : "string" }, "street" : { "description" : "The name of the street.\n>The house number should not be included in this field; it should be separately provided via `houseNumberOrName`.\n>Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided.", "type" : "string" } }, "required" : [ "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.\n\nA 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.\nIf 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:\n* χ12 is converted to ch12.\n* üA is converted to euA.\n* Peter Møller is converted to Peter Mller, because banks don't accept 'ø'.\nAfter 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:\n* John17 - allowed.\n* J17 - allowed.\n* 171 - not allowed.\n* John-7 - allowed.\n> 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/developers/payment-glossary#cardsecuritycodecvccvvcid) (1-20 characters). Depending on the card brand, it is known also as:\n* CVV2/CVC2 – length: 3 digits\n* CID – length: 4 digits\n> 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.\n> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/features/recurring-payments).\n> 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.\nFormat: 2 digits, zero-padded for single digits. For example:\n* 03 = March\n* 11 = November", "maxLength" : 2, "minLength" : 1, "type" : "string" }, "expiryYear" : { "description" : "The card expiry year.\nFormat: 4 digits. For example: 2018", "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.\nWhen 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.\n\nThis field can be set to one of the following values, or to their combination (comma-separated):\n* ONECLICK\n* RECURRING\n* PAYOUT", "type" : "string" }, "merchantAccount" : { "description" : "Your merchant account.", "type" : "string" }, "recurringDetailReference" : { "description" : "The ID that uniquely identifies the recurring detail reference.\n\nIf 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.\n\nThis `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.\n>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.\n>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.\nPossible values:\n* `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).\n* `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).\n* `ONECLICK,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not.\n* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/developers/features/third-party-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.\n\nThe 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).", "type" : "object" }, "alias" : { "description" : "The alias of the credit card number.\n\nApplies only to recurring contracts storing credit card details", "type" : "string" }, "aliasType" : { "description" : "The alias type of the credit card number.\n\nApplies 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/developers/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.\n\nThe contract value needs to match the contract value submitted in the payment transaction used to create a recurring contract.\nHowever, 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" } } } } } }