diff --git a/specs/2.0/PaymentService-V30.yaml b/specs/2.0/PaymentService-V30.yaml index de6de7d..e62014e 100644 --- a/specs/2.0/PaymentService-V30.yaml +++ b/specs/2.0/PaymentService-V30.yaml @@ -2,7 +2,29 @@ swagger: '2.0' info: version: '30' 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 a new API Key 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 + ``` host: pal-test.adyen.com basePath: /pal/servlet/Payment/v30 schemes: @@ -17,13 +39,13 @@ x-groups: paths: /adjustAuthorisation: post: - summary: Adjust the authorised amount + summary: Increases or decreases the authorised amount. description: |- Allows you to increase or decrease the authorised amount after the initial authorisation has taken place. This functionality enables tipping, improving the chances your authorisation will be valid, charging the shopper when they have already left the merchant premises, etc. For more information, refer to [Adjust Authorisation](https://docs.adyen.com/developers/payment-modifications#adjustauthorisation). x-groupName: Modifications - x-sortIndex: 5 + x-sortIndex: 6 parameters: - name: modificationRequest in: body @@ -46,7 +68,7 @@ paths: description: Internal Server Error - the server could not process the request. /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. @@ -75,7 +97,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. @@ -104,7 +126,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. @@ -133,7 +155,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). @@ -160,7 +182,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. @@ -191,7 +213,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. @@ -219,33 +241,70 @@ paths: description: Unprocessable Entity - a request validation error. '500': description: Internal Server Error - the server could not process the request. + /technicalCancel: + post: + summary: Cancels an authorised payment using a custom reference. + description: |- + Cancels a previously authorised payment using a custom reference value, that you submitted as a `reference` parameter in the original `/authorise` request. + + For more information, refer to [Technical Cancel](https://docs.adyen.com/developers/payment-modifications#technicalcancel). + x-groupName: Modifications + x-sortIndex: 5 + parameters: + - name: modificationRequest + in: body + schema: + $ref: '#/definitions/ModificationRequest' + responses: + '200': + description: OK - the request has succeeded. + schema: + $ref: '#/definitions/ModificationResult' + '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. 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: @@ -383,7 +442,6 @@ definitions: - expiryMonth - expiryYear - holderName - Collection: {} ForexQuote: properties: account: @@ -427,6 +485,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: @@ -435,7 +510,9 @@ definitions: type: integer results: description: The result of the individual risk checks. - type: object + items: + $ref: '#/definitions/FraudCheckResult' + type: array required: - accountScore Installments: @@ -454,7 +531,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. @@ -507,10 +587,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 @@ -519,10 +601,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 @@ -671,7 +755,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: |- @@ -849,7 +933,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: |- @@ -919,12 +1003,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. @@ -969,9 +1053,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 @@ -984,6 +1069,7 @@ definitions: description: The name of the token service. enum: - VISATOKENSERVICE + - MCTOKENSERVICE type: string ThreeDSecureData: properties: