adyen/adyen-openapi

OpenAPI specification for the Adyen APIs

Adyen OpenAPI / Swagger definitions

Adyen provides various APIs to help you accept payments on your website or mobile application, implement subscription billing, make payouts, and much more.

This repository contains Adyen API definition files, represented in the OpenAPI Specification standard (formerly known as Swagger Specification).

Folder structure

API definitions in this repository are organized into two sub-folders:

   /json – Definition files in the json format.
   /yaml – Definition files in the yaml format.

We support the OpenAPI version 3.1.0.

Usage

There are multiple ways you can use the OpenAPI definition to explore the Adyen API:

• If you want to see the API definitions in action, visit the Adyen API Explorer portal.
• If you prefer to use the classic Swagger toolset, upload these definitions to the Swagger Editor or SwaggerHub.
• Also, we recommend you use Postman to import the API definition and create your personal collection of requests.

Vendor extensions

Adyen's API definitions contain some custom extensions, as allowed by the OpenAPI standard. These are extensions that provide metadata, such as the grouping and sort order of API objects, when they are displayed in the Adyen API Explorer.

x-groups

This extension provides a list of all endpoint groups for the selected API.

For example:

x-groups:
  - General
  - Modifications

x-groupName and x-sortIndex

These extensions specify how to group endpoints and sort them within a group.

For example:

paths:
    ...
    post:
      ...
      x-groupName: Modifications
      x-sortIndex: 5
   ...

x-publicVersion

This is an auxiliary extension that helps us verify that the current API version is publicly available.

x-addedInVersion, x-deprecatedInVersion and x-deprecatedMessage

These extensions help us add information when a certain endpoint or field has been added, and later when they are deprecated.

In addition, the x-deprecatedMessage can contain a human-readable message explaining what to use instead of a deprecated API, which provides much better developer experience:

        recurringDetailReference:
          deprecated: true
          x-deprecatedInVersion: 49
          x-deprecatedMessage: Use `storedPaymentMethodId` instead.
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string
        storedPaymentMethodId:
          x-addedInVersion: 49
          description: This is the `recurringDetailReference` returned in the response when you created the token.
          type: string

x-oneOf, x-anyOf, x-not and x-allOf

These extensions are equivalent to those from the JSON Schema but don't enforce strict validation.

We use them in some rare cases when we need to avoid validation issues with open-source tooling, while still being able to display this information in our API Explorer.

Support

If you have a feature request, or spotted a bug or a technical problem, create a GitHub issue. For other questions, contact our Team.

License

This repository is open source and available under the MIT license. For more information, see the LICENSE file.

adyen-openapi's Issues

rename classes which names starting with authorization in webhook json

Describe the bug
In webhook json there are classes which names starting with authorization, however they are eligible to be used for other requests too. I suggest we should rename it or clarify which classes are used for which requests.

To Reproduce
Irrelevant

Expected behavior
Renamed classes.

Screenshots
None

Desktop (please complete the following information):
Irrelevant

Smartphone (please complete the following information):
Irrelevant

Additional context
None

Nullability lost when generating client using NSwag generator

Describe the bug
When using vs2022 and connected service for the checkoutservice v71 openapi spec NSwag generator doesn't work correctly with nullability if not 'nullable: true' is present on the property.
I have had to manually change properties after my requirements to handle this. For instance in the /sessions endpoint (CreateCheckoutSessionRequest) I had to add 'nullable: true' to storePaymentMethod, enableRecurring, enableOneClick, expiresAt to be able to use the client without having a session causing error with payment.

To Reproduce
Steps to reproduce the behavior:

1. Download checkoutservice v71 yaml add add to folder in assembly
2. Add connectedservice using the yaml (with option GenerateNullableReferenceTypes:true present)
3. The generated client have bool instead of bool? for instance

Expected behavior
Expecting nullable properties to be reflected correctly in the generated client

Screenshots
Need to add this to all properties if possible

The 'servers' for each spec only lists test servers, not production URLs

Describe the bug

The servers field of each spec only lists a single test URL for each API, instead of actually specifying the pattern of URLs used.

This is inconvenient, as some tools (such as HTTP Toolkit - I'm the maintainer) use the servers listed in the spec to recognise traffic to an API, and provide appropriate tooling for the API in that case.

For Adyen right now that isn't possible - nobody can use these spec for anything relating to traffic to Adyen production APIs, only to your test APIs (still useful, but very limiting).

To Reproduce

Look at any spec's servers, e.g. for the checkout API:

adyen-openapi/json/CheckoutService-v70.json

Lines 3 to 7 in 40452c3

	"servers" : [
	{
	"url" : "https://checkout-test.adyen.com/v70"
	}
	],

This just lists the test endpoint, where the actual production URLs according to https://docs.adyen.com/development-resources/live-endpoints can include https://[prefix]-checkout-live.adyenpayments.com/checkout/v70/.

Expected behavior

The specs should also include the pattern of the production base URL, using variables for the potentially variable component, for example something like:

"servers": [
  {
    "url" : "https://checkout-test.adyen.com/v70",
    "description": "The test API"
  },
  {
    "url": "https://{prefix}-checkout-live.adyenpayments.com/checkout/v70",
    "description": "The production API",
    "variables": {
      "prefix": {
        "description": "A string composed of a hex-encoded random part and your company name. Get the prefix from your live Customer Area under Developers > API URLs > Prefix"
      }
    }
  }
]

This makes it possible to use these specs for requests to Adyen production APIs, and for tooling to recognize traffic to these APIs.

Issues with using the specs for code generation or validation

We're trying to using these specs to validate requests/responses or generating code from them and we're bumping onto some issues.

The following issues come from Checkout v51 and Payment v51 as of e2dd2fc.

1. Inline items with itemNr cursor

There are a number of items on the spec (under additional data) that seem to be defined as key-value items but as a user I assume you are expected to replace the itemNr with the item's location in the array.

Some examples:

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 828 to 831 in e2dd2fc

	"openinvoicedata.line[itemNr].currencyCode": {
	"description" : "The three-character ISO currency code.",
	"type" : "string"
	},

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 708 to 711 in e2dd2fc

	"enhancedSchemeData.itemDetailLine[itemNr].commodityCode": {
	"description" : "Item commodity code.\nEncoding: ASCII.\nMax length: 12 characters.",
	"type" : "string"
	},

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 1004 to 1007 in e2dd2fc

	"riskdata.basket.item[itemNr].itemID": {
	"description" : "ID of the item.",
	"type" : "string"
	},

2. Additional data contains object with duplicate attributes

anyOf – validates the value against any (one or more) of the subschemas

The anyOf used for the additionalData attributes contains a number of references that contain duplicate attributes.

For example enhancedSchemeData.customerReference appears in both AdditionalDataLevel23 and AdditionalDataTemporaryServices.

I understand that this might be technically valid OpenAPI but seems to result in issues when generating code and complicates the logic of matching the various options for the attribute.

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 2206 to 2222 in e2dd2fc

	"additionalData" : {
	"description" : "This field contains additional data, which may be required for a particular payment request.\n\nThe `additionalData` object consists of entries, each of which includes the key and value.",
	"anyOf": [
	{ "$ref" : "#/components/schemas/AdditionalDataCommon" },
	{ "$ref" : "#/components/schemas/AdditionalData3DSecure" },
	{ "$ref" : "#/components/schemas/AdditionalDataAirline" },
	{ "$ref" : "#/components/schemas/AdditionalDataCarRental" },
	{ "$ref" : "#/components/schemas/AdditionalDataLevel23" },
	{ "$ref" : "#/components/schemas/AdditionalDataLodging" },
	{ "$ref" : "#/components/schemas/AdditionalDataOpenInvoice" },
	{ "$ref" : "#/components/schemas/AdditionalDataRatepay" },
	{ "$ref" : "#/components/schemas/AdditionalDataRetry" },
	{ "$ref" : "#/components/schemas/AdditionalDataRisk" },
	{ "$ref" : "#/components/schemas/AdditionalDataRiskStandalone" },
	{ "$ref" : "#/components/schemas/AdditionalDataTemporaryServices" }
	]
	},

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 1142 to 1147 in e2dd2fc

	"AdditionalDataTemporaryServices" : {
	"properties": {
	"enhancedSchemeData.customerReference": {
	"description" : "Customer code, if supplied by a customer.\n* Encoding: ASCII\n* maxLength: 25",
	"type" : "string"
	},

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 670 to 675 in e2dd2fc

	"AdditionalDataLevel23" : {
	"properties": {
	"enhancedSchemeData.customerReference": {
	"description" : "Customer code, if supplied by a customer.\nEncoding: ASCII.\nMax length: 25 characters.\n> Required for Level 2 and Level 3 data.",
	"type" : "string"
	},

3. Missing securitySchemes

The X-Api-Key header that is required for authentication is only mentioned in a description and the securitySchemes is not being used so the header is not enforced in any of the paths.

4. Missing Idempotency-Key header

The Idempotency-Key header is not defined for any of the paths.

5. Amounts have the wrong type

All amounts have their types marked as number where according to their description they should be integers, which OpenAPI supports.

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 680 to 687 in e2dd2fc

	"enhancedSchemeData.freightAmount": {
	"description" : "Shipping amount, in minor units.\n\nFor example, 2000 means USD 20.00.\nMax length: 12 characters.",
	"type" : "number"
	},
	"enhancedSchemeData.dutyAmount": {
	"description" : "Duty amount, in minor units.\n\nFor example, 2000 means USD 20.00.\nMax length: 12 characters.",
	"type" : "number"
	},

6. Attributes have no validation

The main interest would be string/number/array limits for this.
Docs for each attribute mention the min/max length of the attribute but the spec doesn't enforce it.

7. Missing enums

A number of attributes seem to be enums, but don't appear as such. The attribute description will mention something like Values can be x, y, z.

adyen-openapi/specs/json/CheckoutService-v51.json

Lines 780 to 783 in e2dd2fc

	"travelEntertainmentAuthData.market": {
	"description": "Indicates what market-specific dataset will be submitted or is being submitted. Value should be \"H\" for Hotel. This should be included in the auth message.\n* Format: Alphanumeric\n* maxLength: 1",
	"type": "string"
	},

Enums have duplicate entries in BalancePlatformService-v1.json

Hi,
I'm trying to use an OpenAPI Java generator on BalancePlatformService-v1.json and it says that some enums have duplicate entries:
AccountHolder.status: [ "Active", "Closed", "Inactive", "Suspended", "active", "closed", "inactive", "suspended" ]

Phone.type: [ "Landline", "Mobile", "landline", "mobile" ]

PaymentInstrument.status: [ "Active", "Closed", "Inactive", "Lost", "Requested", "Stolen", "Suspended", "active", "blocked", "discarded", "inactive" ]

PaymentInstrumentUpdateRequest.status: [ "Active", "Closed", "Inactive", "Lost", "Requested", "Stolen", "Suspended", "active", "blocked", "discarded", "inactive" ]

PaymentInstrumentInfo.status: [ "Active", "Closed", "Inactive", "Lost", "Requested", "Stolen", "Suspended", "active", "blocked", "discarded", "inactive" ]

I'm an OpenAPI newbie so I'm not sure if these are actually allowed and the generator has to handle them somehow...

CheckoutService-v64.json: KlarnaDetails > type contains default value that is not in enum

Describe the bug
When generating code for CheckoutService-v64.json I run in to an issue on code compilation:

KlarnaDetails contains a property called type that has a default value of openinvoice. The list of allowed values is klarna,klarnapayments,klarnapayments_account,klarnapayments_b2b,klarna_paynow,klarna_account,klarna_b2b.

Because the default value is not a member of the enum, code generation wil fail for languages with strict types.

To Reproduce
Generate code for a typed language (in our case Scala) based on CheckoutService-v64.json. Compiling that code should fail. Alternately look into the generated spec and verify that the default value is a member of the enum.

Expected behavior
The default value of this type is a member of the enum.

FundService 400 status code responses do not map to a model

In specs for AccountService, CheckoutService and probably others as well the Response for status code 400 does not map to a model or even to a string. This makes debugging an integration with these services frustrating.

As a workaround we patch some of the specs to use #/components/schemas/GenericResponse as a model for the 400 status code. In specs that don't contain that model we add the model to the spec or we map it to string.

Cvc Required Error for Payments with CardOnFile

Describe the bug
When I try to make a card payment with a token in the API explorer (Checkout v70) for a CardOnFile it fails, saying "Required field 'cvc' is not provided".

To Reproduce
Steps to reproduce the behavior:

1. Go to Adyen API Explorer for Checkout v70 -> Payments -> POST /payments (https://docs.adyen.com/api-explorer/Checkout/70/post/payments)
2. Under Request select Make a card payment with a token but change recurringProcessingModel value to CardOnFile
3. Hit Run
4. Check the response:

{
  "status": 422,
  "errorCode": "14_029",
  "message": "Required field 'cvc' is not provided.",
  "errorType": "validation",
  "pspReference": "KXFFJH66FJHKGK82"
}

Expected behavior
I expect the payment to be successful, as it is in Checkout API v69

Screenshots
Checkout API v69:

CheckoutAPI v70:

Desktop (please complete the following information):

• OS: Windows 10
• Browser: chrome
• Version: 114

Additional context
I didn't see anything about cvc being required for CardOnFile payments in the migration guide or release notes so I'm assuming this is a bug. If I'm wrong please let me know and close this issue. Thanks!

add new fields in webhook json

Describe the bug
In webhooks there are missed properties in such classes:

• AuthorisationNotificationAdditionalData: scaExemptionRequested, checkout.cardAddedBrand, bookingDate, recurring.shopperReference, paymentMethod
• AuthorisationNotificationRequestItem: originalReference

To Reproduce
Look at the API to see recurring.shopperReference there.
Look at the screenshots section.

Expected behavior
All fields introduced in webhook json.

Screenshots
During live testing such objects appear:

Desktop (please complete the following information):
Irrelevent

Smartphone (please complete the following information):
Irrelevent

Additional context
None

Last version specification

Hi team,

When are you planning to publish spec files for the latest API version? I see that the current version in API explorer is 50, but the latest spec here is still 46. Is the latest spec available from other places?

Best regards

Provide validation information for fields values

Document things like minLength, maxLength, etc. for all fields, where appropriate.

FundService v52 /transferFunds response code 202 not in spec

Describe the bug
When calling /transferFunds the HTTP response code is 202 while the list of valid response codes in the spec does not contain 202 as an option. As a result no code is generated for that path and we can not handle the response without patching the spec first.

Document the Idempotency-Key header

Our APIs support idempotency via the Idempotency-Key HTTP header:
https://docs.adyen.com/development-resources/api-idempotency#page-introduction

We need to add this info to our specifications, where appropriate.

Notification examples do not adhere to defined schema

Describe the bug
There are several notification examples that do not adhere to their defined schema.

For example: REPORT_AVAILABLE example notification does not comply with the declared schema for a ReportAvailableNotificationRequestItem. paymentMethod is stated to be required but the example is missing it. It is unclear what schema I should expect the NotificationRequestItem to be.

There are other errors in the schema definitions, for example for success values, though i have reported it as a separate issue: #26

To Reproduce
Look at the openAPI specification for a ReportAvailableNotificationRequestItem and see that paymentMethod is required.
Look at the openAPI specification example response for REPORT_AVAILABLE and see the paymentMethod is not included in the example.

Expected behavior
Both the actual notification, and the example notification should adhere to the declared schema for REPORT_AVAILABLE.

Screenshots
None

Desktop (please complete the following information):
irrelevant

Smartphone (please complete the following information):
irrelevant

Additional context
Using your example responses to create a mock server causes errors in our test system. We are now unsure of the actual expected schema for notifications.

api-explorer question

Dear,

You have a really great and user-friendly api-explorer.
Since it is based on the OpenApi specification, I wonder what tool you are using to generate the API explorer?

Regards,
Tim

BalancePlatformService -> Card -> number is not required

Describe the bug
Card number is optional in reality but not in the spec.

Additional context
We use the spec to validate responses from the API and noticed this bug as it fails the validation.

Terminal API

Do you have open API specs for Terminal API?

V40 Payment Specification is Incomplete

The OpenAPI 3.0 JSON v40 payment specification does not match the v40 documentation. Specifically the set of members in the resultCode enum is incomplete, it is missing all of the 3D Secure V2 codes.

Line 1775 of the specification has the entire set of resultCode members as:

• Authorised
• PartiallyAuthorised
• Refused
• Error
• Cancelled
• Received
• RedirectShopper

whereas the set in the v40 documentation (here: https://docs.adyen.com/api-explorer/#/Payment/v40/authorise__resParam_resultCode) is:

• AuthenticationFinished
• Authorised
• Cancelled
• ChallengeShopper
• Error
• IdentifyShopper
• Refused
• Pending
• Received
• RedirectShopper

The V40 3DS V2 authorize call returns IdentifyShopper for the appropriate test card and parameters so the documentation is correct and the specification - as laid out here - is incomplete.

Could the specification be brought into line with the documentation please?

CheckoutService v51 yaml PaymentResponse have incorrect required property

Hi,

The yaml file for CheckoutService v51 has specified required on PaymentResponse for property merchantReference. This is incorrect because it's not always part of the response depending of resultCode.

If the resultCode of the response is "IdentifyShopper" or "RedirectShopper", the json returned from the api does not contain the merchantReference attribute.

PaymentResponse:
      properties:
        merchantReference:
          description: |-
            The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement.
            If you need to provide multiple references for a transaction, separate them with hyphens ("-").
            Maximum length: 80 characters.
          type: string
      required:
        - merchantReference

test

AccountService v5 requires fullPhoneNumber but only returns phoneNumber

Using models generated from the AccountService v5 spec causes issues for me because the response to the AccountHolderDetails requires the fullPhoneNumber field but this field is not returned in the response to /createAccountHolder. Instead only the phoneNumber field is returned. For ShareholderContact both phoneNumber and fullPhoneNumber are present and none of them seem to be required. Would it be possible to return fullPhoneNumber as well as it is marked as required in AccountHolderDetails?

Useless Idempotency-Key header causes wrong result from API

Describe the bug
In Checkout API the call POST /paymentMethods uses the header Idempotency-Key, causing the API to respond with a 901 Invalid Merchant Account. Disabling that header, and leaving every other parameter unchanged, give a valid response.

To Reproduce
Steps to reproduce the behavior:

1. Import JSON for Checkout API v67 in Postman
2. Edit payment methods/Returns available payment methods. to use some test account
3. Make the request, should be an error 901
4. Disable the header Idempotency-Key
5. Make the request, should be a valid response

Expected behavior
The header shouldn't be set in the openapi docs, or it should be completely ignored in the API

Desktop:

• OS: ubuntu linux
• Browser Postman
• Version 67

V46 Payment Specification is missing

The current version of the payment API is V46 (as per the API Explorer here: https://docs.adyen.com/api-explorer/#/Payment/v46/overview).

There is no V46 Payment spec in the repository.

Could it be added please?

Generated models from AccountService v5 provide 'required' states conflicting with API responses

When generating models from AccountService v5 there are a few instances where a component (for example: AccountPayoutState) will have some fields marked as required (in this case: "allowPayout", "disabled", "tierNumber", "disableReason", "payoutLimit", "notAllowedReason"). In the response the disableReason is missing. Because these components are used in AccountHolderStatus which is referenced from CreateAccountHolderResponse and CreateAccountHolderRequest the required fields enforce a valid request, but the response does not comply with these requirements.

Would it be possible to either return all the fields that are marked as required in the responses instead of omitting them?

POST checkout/payments doesn't document paypal

Describe the bug
Adyen clearly supports paypal yet the specs are not provided regarding integrating it via the checkout API

To Reproduce
Steps to reproduce the behavior:

1. Go to https://docs.adyen.com/api-explorer/Checkout/69/post/payments
2. Click on https://docs.adyen.com/api-explorer/Checkout/69/post/payments#examples-request-applepay
3. Scroll down as much as you like
4. no Paypal!

Expected behavior
What kind of data does Adyen expect for us to call this API, we're trying to tokenize / authorize paypal to a user account and we're getting validation error PaymentDetail not found

Screenshots

environment doesn't matter this is a REST API call

V40 specification for Checkout client

The v40 checkout documentation is live, however the openapi spec has not be updated.

https://docs.adyen.com/api-explorer/#/PaymentSetupAndVerificationService/v40/overview

Do you have any plans to provide this?

Some OpenAPI files have webhooks but no paths and declare version 3.0.x not 3.1.x

Describe the bug

Commit ac74290 updated the MarketPayNotificationService APIs to remove the paths top level object and replace it with webhooks, but the openapi property was not updated. The webhooks object (and the optionality of paths) are only valid in OpenAPI 3.1.0+.

adyen-openapi/yaml/MarketPayNotificationService-v6.yaml

Line 1 in ac74290

openapi: 3.0.3

success is declared as a boolean when it is a string in production and test environments.

Describe the bug
success has been declared as a boolean when it is actually a string. Here is one example of many:

adyen-openapi/json/Webhooks-v1.json

Line 2065 in 4d59745

"success" : {

To Reproduce
Look at other definitions of success in the openAPI documentation and see that success is a string.
Look at the example notifications in the openAPI documentation; success is a string.
Look at a production notification and see that success is a string.
Look at a testing environment notification and see that success is a string.

Expected behavior
success should be a string. It would have been great if success was actually a boolean, but at this point it has to be a string to break integrations.

Screenshots
None

Desktop (please complete the following information):
irrelevent

Smartphone (please complete the following information):
irrelevent

Additional context
This has caused issues in the past. We have getters for success that coax the value to a boolean if it is a string or a bool because it is unclear in your openAPI spec if success will always be a string, or sometimes may possibly be a bool.