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

Updated specs

Browse Source
This commit is contained in:
Aleksei Akimov
2018-07-12 11:37:38 +02:00
committed by GitHub
parent 5a5a48fda8
commit d7f4243635
1 changed files with 108 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
specs/2.0/PaymentService-V25.yaml
View File

@@ -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: