diff --git a/specs/2.0/PaymentService-V25.yaml b/specs/2.0/PaymentService-V25.yaml index 7450e0e..3884426 100644 --- a/specs/2.0/PaymentService-V25.yaml +++ b/specs/2.0/PaymentService-V25.yaml @@ -2,7 +2,34 @@ swagger: '2.0' info: version: '25' title: Adyen Payment Service - description: 'A set of API endpoints that allow you to initiate, settle, and modify payments on the Adyen payments platform. You can use the API to accept card payments (including One-Click and 3D Secure), bank transfers, ewallets, and many other payment methods. For more information, refer to [Ecommerce integration](https://docs.adyen.com/developers/ecommerce-integration).' + description: |- + A set of API endpoints that allow you to initiate, settle, and modify payments on the Adyen payments platform. You can use the API to accept card payments (including One-Click and 3D Secure), bank transfers, ewallets, and many other payment methods. + + To learn more about the API, visit [Ecommerce integration](https://docs.adyen.com/developers/ecommerce-integration). + + ## Authentication + To connect to the Payments 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: + + ``` + 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/developers/api-reference/live-endpoints). + + ## Versioning + Payments 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/Payment/v30/authorise + ``` + termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com host: pal-test.adyen.com basePath: /pal/servlet/Payment/v25 schemes: @@ -17,7 +44,7 @@ x-groups: paths: /authorise: post: - summary: Create a payment authorisation + summary: Creates a payment authorisation. description: |- Creates a payment with a unique reference (`pspReference`) and attempts to obtain an authorisation hold. For cards, this amount can be captured or cancelled later. Non-card payment methods typically don't support this and will automatically capture as part of the authorisation. @@ -46,7 +73,7 @@ paths: description: Internal Server Error - the server could not process the request. /authorise3d: post: - summary: Complete a 3D Secure payment authorisation + summary: Completes a 3D Secure payment authorisation. description: |- For an authenticated 3D Secure session, completes the payment authorisation. This endpoint must receive the `md` and `paResponse` parameters that you get from the card issuer after a shopper pays via 3D Secure. @@ -75,7 +102,7 @@ paths: description: Internal Server Error - the server could not process the request. /cancel: post: - summary: Cancel a payment authorisation + summary: Cancels an authorised payment. description: |- Cancels the authorisation hold on a payment, returning a unique reference for this request. You can cancel payments after authorisation only for payment methods that support distinct authorisations and captures. @@ -104,7 +131,7 @@ paths: description: Internal Server Error - the server could not process the request. /cancelOrRefund: post: - summary: Cancel or refund a payment + summary: Cancels or refunds a payment. description: |- Cancels a payment if it has not yet been captured yet, or refunds it if it has already been captured. This is useful when it is not certain if the payment has been captured or not (for example, when using auto-capture). @@ -131,7 +158,7 @@ paths: description: Internal Server Error - the server could not process the request. /capture: post: - summary: Capture a payment authorisation + summary: Captures an authorised payment. description: |- Captures the authorisation hold on a payment, returning a unique reference for this request. Usually the full authorisation amount is captured, however it's also possible to capture a smaller amount, which results in cancelling the remaining authorisation balance. @@ -162,7 +189,7 @@ paths: description: Internal Server Error - the server could not process the request. /refund: post: - summary: Refund a payment + summary: Refunds a captured payment. description: |- Refunds a payment that has previously been captured, returning a unique reference for this request. Refunding can be done on the full captured amount or a partial amount. Multiple (partial) refunds will be accepted as long as their sum doesn't exceed the captured amount. Payments which have been authorised, but not captured, cannot be refunded, use the /cancel method instead. @@ -190,34 +217,41 @@ paths: description: Unprocessable Entity - a request validation error. '500': description: Internal Server Error - the server could not process the request. - /voidPendingRefund: {} definitions: Address: properties: city: - description: The city name. + description: |- + The name of the city. + >Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided. type: string country: - description: A valid value is an ISO two-character country code (e.g. 'NL'). + description: |- + The two-character country code of the address + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). 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: |- + 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. 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: |- + 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. 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`. + >Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided. type: string required: - - street - - houseNumberOrName - - city - country Amount: properties: @@ -355,7 +389,6 @@ definitions: - expiryMonth - expiryYear - holderName - Collection: {} ForexQuote: properties: account: @@ -399,6 +432,23 @@ definitions: required: - validTill - basePoints + FraudCheckResult: + properties: + accountScore: + description: The fraud score generated by the risk check. + format: int32 + type: integer + checkId: + description: The ID of the risk check. + format: int32 + type: integer + name: + description: The name of the risk check. + type: string + required: + - checkId + - name + - accountScore FraudResult: properties: accountScore: @@ -407,7 +457,9 @@ definitions: type: integer results: description: The result of the individual risk checks. - type: object + items: + $ref: '#/definitions/FraudCheckResult' + type: array required: - accountScore Installments: @@ -426,7 +478,10 @@ definitions: additionalData: additionalProperties: type: string - description: 'This field contains additional data, which may be required for a particular payment request.' + description: |- + This field contains additional data, which may be required for a particular modification 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 [ModificationRequest.additionalData](https://docs.adyen.com/developers/api-reference/payments-api/modificationrequest/modificationrequest-additionaldata) section. type: object merchantAccount: description: The merchant account that is used to process the payment. @@ -476,10 +531,12 @@ definitions: 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 @@ -488,10 +545,12 @@ definitions: 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 @@ -630,7 +689,7 @@ definitions: 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. Contact Adyen Support for more information. + > 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). type: string shopperInteraction: description: |- @@ -798,7 +857,7 @@ definitions: 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. Contact Adyen Support for more information. + > 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). type: string shopperInteraction: description: |- @@ -868,12 +927,12 @@ definitions: dccAmount: description: |- Includes the currency of the conversion and the value of the transaction. - > This value only applies if you have implemented Dynamic Currency Conversion. For more information, contact Support. + > This value only applies if you have implemented Dynamic Currency Conversion. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new). $ref: '#/definitions/Amount' dccSignature: description: |- Cryptographic signature used to verify `dccQuote`. - > This value only applies if you have implemented Dynamic Currency Conversion. For more information, contact Support. + > This value only applies if you have implemented Dynamic Currency Conversion. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new). type: string fraudResult: description: The fraud result properties of the payment. @@ -893,7 +952,10 @@ definitions: 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). type: string pspReference: - description: Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request. + description: |- + Adyen's 16-digit unique reference associated with the transaction/the request. This value is globally unique; quote it when communicating with us about this request. + + > `pspReference` is returned only for non-redirect payment methods. type: string refusalReason: description: |- @@ -902,7 +964,16 @@ definitions: When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values. type: string resultCode: - description: The result of the payment. + 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. For more information on handling a redirect, refer to [Handling a redirect](https://docs.adyen.com/developers/checkout/api-integration/payments#handlingaredirect). + * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **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. enum: - Authorised - PartiallyAuthorised @@ -918,9 +989,10 @@ definitions: 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/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,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). enum: - ONECLICK - RECURRING @@ -933,6 +1005,7 @@ definitions: description: The name of the token service. enum: - VISATOKENSERVICE + - MCTOKENSERVICE type: string ThreeDSecureData: properties: