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 Payment v40 yaml

Browse Source
This commit is contained in:
Aleksei Akimov
2019-06-11 16:12:15 +02:00
committed by GitHub
parent 8fe6a3c2b8
commit 425e757e58
1 changed files with 166 additions and 108 deletions
Download Patch File Download Diff File Expand all files Collapse all files

274
specs/3.0/PaymentService-v40.yaml
View File

@@ -7,10 +7,10 @@ info:
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 [Classic integration](https://docs.adyen.com/developers/classic-integration).
To learn more about the API, visit [Classic integration](https://docs.adyen.com/classic-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:
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/user-management/how-to-get-the-web-service-ws-user-password). Then use its credentials to authenticate your request, for example:
```
curl
@@ -18,7 +18,7 @@ info:
-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/development-resources/live-endpoints).
Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/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.
@@ -42,7 +42,7 @@ paths:
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/adjust-authorisation).
For more information, refer to [Adjust Authorisation](https://docs.adyen.com/development-resources/payment-modifications/adjust-authorisation).
x-groupName: Modifications
x-sortIndex: 6
requestBody:
@@ -73,7 +73,7 @@ paths:
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.
For more information, refer to [Classic integration](https://docs.adyen.com/developers/classic-integration).
For more information, refer to [Classic integration](https://docs.adyen.com/classic-integration).
x-groupName: General
x-sortIndex: 1
requestBody:
@@ -104,7 +104,7 @@ paths:
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.
For more information, refer to [3D Secure](https://docs.adyen.com/developers/risk-management/3d-secure).
For more information, refer to [3D Secure](https://docs.adyen.com/classic-integration/3d-secure).
x-groupName: General
x-sortIndex: 2
requestBody:
@@ -135,7 +135,7 @@ paths:
description: |-
For an authenticated 3D Secure 2 session, completes the payment authorisation. This endpoint must receive the `threeDS2Token` and `threeDS2Result` parameters.
For more information, refer to [3D Secure 2](https://docs.adyen.com/developers/risk-management/3d-secure-2-0).
For more information, refer to [3D Secure 2](https://docs.adyen.com/checkout/3d-secure-2).
x-groupName: General
x-sortIndex: 3
requestBody:
@@ -166,7 +166,7 @@ paths:
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.
For more information, refer to [Cancel](https://docs.adyen.com/developers/payment-modifications/cancel).
For more information, refer to [Cancel](https://docs.adyen.com/development-resources/payment-modifications/cancel).
x-groupName: Modifications
x-sortIndex: 2
requestBody:
@@ -199,7 +199,7 @@ paths:
> Do not use this request for payments that involve (multiple) partial captures.
For more information, refer to [Cancel or refund](https://docs.adyen.com/developers/payment-modifications/cancel-or-refund).
For more information, refer to [Cancel or refund](https://docs.adyen.com/development-resources/payment-modifications/cancel-or-refund).
x-groupName: Modifications
x-sortIndex: 4
requestBody:
@@ -230,7 +230,7 @@ paths:
Payment methods, which automatically capture as part of authorisation, don't need to be captured, but submitting a capture request on these transactions will not result in double charges. If immediate or delayed auto-capture is enabled, calling the capture method is not neccessary.
For more information, refer to [Capture](https://docs.adyen.com/developers/payment-modifications/capture).
For more information, refer to [Capture](https://docs.adyen.com/development-resources/payment-modifications/capture).
x-groupName: Modifications
x-sortIndex: 1
requestBody:
@@ -264,7 +264,7 @@ paths:
> Some payment methods/gateways do not support partial/multiple refunds.
> A margin above the captured limit can be configured to cover shipping/handling costs.
For more information, refer to [Refund](https://docs.adyen.com/developers/payment-modifications/refund).
For more information, refer to [Refund](https://docs.adyen.com/development-resources/payment-modifications/refund).
x-groupName: Modifications
x-sortIndex: 3
requestBody:
@@ -317,11 +317,13 @@ paths:
description: Internal Server Error - the server could not process the request.
/technicalCancel:
post:
summary: Cancels an authorised payment using a custom reference.
summary: Cancels a payment using your 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.
This endpoint allows you to cancel a payment if you do not have the PSP reference of the original payment request available.
For more information, refer to [Technical Cancel](https://docs.adyen.com/developers/payment-modifications/technical-cancel).
In your call, refer to the original payment by using the `reference` that you specified in your payment request.
For more information, see [Technical cancel](https://docs.adyen.com/development-resources/payment-modifications/cancel#technical-cancel).
x-groupName: Modifications
x-sortIndex: 5
requestBody:
@@ -354,7 +356,7 @@ paths:
In your call, you can refer to the original refund request either by using the `tenderReference`, or the `pspReference`. We recommend implementing based on the `tenderReference`, as this is generated for both offline and online transactions.
For more information, refer to [Cancel a POS refund](https://docs.adyen.com/developers/development-resources/payment-modifications/cancel-a-pos-refund-request).
For more information, refer to [Cancel a refund](https://docs.adyen.com/point-of-sale/build-your-integration/cancel-a-pos-refund-request).
x-groupName: Modifications
x-sortIndex: 7
requestBody:
@@ -383,7 +385,7 @@ components:
properties:
accountAgeIndicator:
description: |-
Indicator of how long this shopper account exists in the merchant's environment.
Indicator for the length of time since this shopper account was created in the merchant's environment.
Allowed values:
* notApplicable
* thisTransaction
@@ -403,7 +405,7 @@ components:
type: string
accountChangeIndicator:
description: |-
Indicator when the shopper's account was last changed.
Indicator for the length of time since the shopper's account was last updated.
Allowed values:
* thisTransaction
* lessThan30Days
@@ -429,7 +431,7 @@ components:
type: string
deliveryAddressUsageIndicator:
description: |-
Indicator for when this delivery address was last used.
Indicator for the length of time since this delivery address was last used.
Allowed values:
* thisTransaction
* lessThan30Days
@@ -448,7 +450,7 @@ components:
description: Shopper's mobile phone number (including the country code).
type: string
passwordChangeDate:
description: Date when the shopper has changed their password.
description: Date when the shopper last changed their password.
format: date-time
type: string
passwordChangeIndicator:
@@ -468,11 +470,11 @@ components:
- moreThan60Days
type: string
pastTransactionsDay:
description: Number of transactions of this shopper in the past 24 hours.
description: Number of all transactions (successful and abandoned) from this shopper in the past 24 hours.
format: int32
type: integer
pastTransactionsYear:
description: Number of transactions of this shopper in the past year.
description: Number of all transactions (successful and abandoned) from this shopper in the past year.
format: int32
type: integer
paymentAccountAge:
@@ -481,7 +483,7 @@ components:
type: string
paymentAccountIndicator:
description: |-
Indicator for the amount of time this payment method was enrolled with this account.
Indicator for the length of time since this payment method was added to this shopper's account.
Allowed values:
* notApplicable
* thisTransaction
@@ -496,7 +498,7 @@ components:
- moreThan60Days
type: string
purchasesLast6Months:
description: Number of purchases in the last 6 months.
description: Number of successful purchases in the last six months.
format: int32
type: integer
suspiciousActivity:
@@ -524,7 +526,6 @@ components:
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: |-
@@ -543,7 +544,7 @@ components:
Amount:
properties:
currency:
description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).'
description: 'The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).'
maxLength: 3
minLength: 3
type: string
@@ -551,7 +552,7 @@ components:
description: |-
The payable amount that can be charged for the transaction.
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/development-resources/currency-codes).
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
@@ -608,14 +609,17 @@ components:
minLength: 10
type: string
colorDepth:
description: The color depth of the shopper's device in bits per pixel. Should be obtained by using the browser's screen.colorDepth property.
description: 'The color depth of the shopper''s browser in bits per pixel. This should be obtained by using the browser''s `screen.colorDepth` property. Accepted values: 1, 4, 8, 15, 16, 24, 32 or 48 bit color depth.'
format: int32
type: integer
javaEnabled:
description: Boolean value indicating if the shopper's browser is able to execute Java.
type: boolean
javaScriptEnabled:
description: Boolean value indicating if the shopper's browser is able to execute JavaScript. A default 'true' value is assumed if the field is not present.
type: boolean
language:
description: The navigator.language value of the shopper's browser (as defined in IETF BCP 47).
description: The `navigator.language` value of the shopper's browser (as defined in IETF BCP 47).
type: string
screenHeight:
description: The total height of the shopper's device screen in pixels.
@@ -647,11 +651,11 @@ components:
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:
The [card verification code](https://docs.adyen.com/payments-essentials/payment-glossary#card_security_code_cvc_cvv_cid_) (1-20 characters). Depending on the card brand, it is known also as:
* CVV2/CVC2 – length: 3 digits
* CID – length: 4 digits
> If you are using [Client-Side Encryption](https://docs.adyen.com/developers/features/client-side-encryption), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/classic-integration/recurring-payments).
> If you are using [Client-Side Encryption](https://docs.adyen.com/classic-integration/cse-integration-ecommerce), the CVC code is present in the encrypted data. You must never post the card details to the server.
> This field must be always present in a [one-click payment request](https://docs.adyen.com/classic-integration/recurring-payments).
> When this value is returned in a response, it is always empty because it is not stored.
maxLength: 20
minLength: 1
@@ -707,14 +711,26 @@ components:
DeviceRenderOptions:
properties:
sdkInterface:
description: Supported SDK interface types.
description: |-
Supported SDK interface types.
Allowed values:
* Native
* Html
* both
enum:
- Html
- Native
- both
type: string
sdkUiType:
description: UI types supported for displaying specific challenges.
description: |-
UI types supported for displaying specific challenges.
Allowed values:
* text
* singleSelect
* outOfBand
* otherHtml
* multiSelect
items:
enum:
- multiSelect
@@ -862,10 +878,10 @@ components:
format: date-time
type: string
preOrderPurchase:
description: Whether this transaction is for pre-ordering a product.
description: Indicator for whether this transaction is for pre-ordering a product.
type: boolean
reorderItems:
description: Whether the shopper has already purchased the same items in the past.
description: Indicator for whether the shopper has already purchased the same items in the past.
type: boolean
ModificationRequest:
properties:
@@ -873,7 +889,7 @@ components:
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.
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/api-reference/payments-api/modificationrequest/modificationrequest-additionaldata) section.
type: object
merchantAccount:
description: The merchant account that is used to process the payment.
@@ -902,10 +918,10 @@ components:
$ref: '#/components/schemas/Split'
type: array
tenderReference:
description: The transaction reference provided by the PED. For Point-of-sale integrations only.
description: The transaction reference provided by the PED. For point-of-sale integrations only.
type: string
uniqueTerminalId:
description: Unique terminal ID for the PED that originally processed the request. For Point-of-sale integrations only.
description: Unique terminal ID for the PED that originally processed the request. For point-of-sale integrations only.
type: string
required:
- merchantAccount
@@ -957,21 +973,23 @@ components:
PaymentRequest:
properties:
accountInfo:
description: Shopper account information for 3D Secure 2.
description: |-
Shopper account information for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/AccountInfo'
additionalAmount:
description: |-
If you want a [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
If you want a [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
$ref: '#/components/schemas/Amount'
additionalData:
description: |-
This field contains additional data, which may be required for a particular payment 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 [additionalData section](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata).
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 [additionalData section](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata).
type: object
amount:
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
$ref: '#/components/schemas/Amount'
bankAccount:
description: |-
@@ -979,10 +997,14 @@ components:
> Either `bankAccount` or `card` field must be provided in a payment request.
$ref: '#/components/schemas/BankAccount'
billingAddress:
description: The address where to send the invoice.
description: |-
The address where to send the invoice.
> For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object.
$ref: '#/components/schemas/Address'
browserInfo:
description: The shopper's browser information.
description: |-
The shopper's browser information.
> For 3D Secure 2 transactions, `browserInfo` is required for `channel` **web** (or `deviceChannel` **browser**).
$ref: '#/components/schemas/BrowserInfo'
captureDelayHours:
description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.'
@@ -1016,7 +1038,7 @@ components:
format: date-time
type: string
deviceFingerprint:
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/developers/risk-management/device-fingerprinting).'
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/risk-management/device-fingerprinting).'
type: string
entityType:
description: The type of the entity the payment is processed for.
@@ -1029,7 +1051,7 @@ components:
format: int32
type: integer
installments:
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).'
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).'
$ref: '#/components/schemas/Installments'
mcc:
description: 'The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.'
@@ -1039,11 +1061,14 @@ components:
type: string
merchantOrderReference:
description: |-
This reference allows linking multiple transactions to each other.
This reference allows linking multiple transactions to each other for reporting purposes (i.e. order auth-rate). The reference should be unique per billing cycle.
The same merchant order reference should never be reused after the first authorised attempt. If used, this field should be supplied for all incoming authorisations.
> We strongly recommend you send the `merchantOrderReference` value to benefit from linking payment requests when authorisation retries take place. In addition, we recommend you provide `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values in `PaymentRequest.additionalData`.
type: string
merchantRiskIndicator:
description: Additional risk fields for 3D Secure 2.
description: |-
Additional risk fields for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/MerchantRiskIndicator'
metadata:
description: |-
@@ -1061,7 +1086,7 @@ components:
description: 'When you are doing multiple partial (gift card) payments, this is the `pspReference` of the first payment. We use this to link the multiple payments to each other. As your own reference for linking multiple payments, use the `merchantOrderReference`instead.'
type: string
recurring:
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/developers/features/recurring-payments).'
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/classic-integration/recurring-payments).'
$ref: '#/components/schemas/Recurring'
recurringProcessingModel:
description: |
@@ -1096,7 +1121,9 @@ components:
description: A session ID used to identify a payment session.
type: string
shopperEmail:
description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.'
description: |-
The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks.
> For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**.
type: string
shopperIP:
description: |-
@@ -1167,27 +1194,33 @@ components:
PaymentRequest3d:
properties:
accountInfo:
description: Shopper account information for 3D Secure 2.
description: |-
Shopper account information for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/AccountInfo'
additionalAmount:
description: |-
If you want a [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
If you want a [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
$ref: '#/components/schemas/Amount'
additionalData:
description: |-
This field contains additional data, which may be required for a particular payment 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 [additionalData section](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata).
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 [additionalData section](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata).
type: object
amount:
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
$ref: '#/components/schemas/Amount'
billingAddress:
description: The address where to send the invoice.
description: |-
The address where to send the invoice.
> For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object.
$ref: '#/components/schemas/Address'
browserInfo:
description: The shopper's browser information.
description: |-
The shopper's browser information.
> For 3D Secure 2 transactions, `browserInfo` is required for `channel` **web** (or `deviceChannel` **browser**).
$ref: '#/components/schemas/BrowserInfo'
captureDelayHours:
description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.'
@@ -1216,14 +1249,14 @@ components:
format: date-time
type: string
deviceFingerprint:
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/developers/risk-management/device-fingerprinting).'
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/risk-management/device-fingerprinting).'
type: string
fraudOffset:
description: An integer value that is added to the normal fraud score. The value can be either positive or negative.
format: int32
type: integer
installments:
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).'
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).'
$ref: '#/components/schemas/Installments'
mcc:
description: 'The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.'
@@ -1236,11 +1269,14 @@ components:
type: string
merchantOrderReference:
description: |-
This reference allows linking multiple transactions to each other.
This reference allows linking multiple transactions to each other for reporting purposes (i.e. order auth-rate). The reference should be unique per billing cycle.
The same merchant order reference should never be reused after the first authorised attempt. If used, this field should be supplied for all incoming authorisations.
> We strongly recommend you send the `merchantOrderReference` value to benefit from linking payment requests when authorisation retries take place. In addition, we recommend you provide `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values in `PaymentRequest.additionalData`.
type: string
merchantRiskIndicator:
description: Additional risk fields for 3D Secure 2.
description: |-
Additional risk fields for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/MerchantRiskIndicator'
metadata:
description: |-
@@ -1254,7 +1290,7 @@ components:
description: Payment authorisation response returned by the card issuer. The `paResponse` field holds the PaRes value received from the card issuer.
type: string
recurring:
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/developers/features/recurring-payments).'
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/classic-integration/recurring-payments).'
$ref: '#/components/schemas/Recurring'
recurringProcessingModel:
description: |
@@ -1289,7 +1325,9 @@ components:
description: A session ID used to identify a payment session.
type: string
shopperEmail:
description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.'
description: |-
The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks.
> For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**.
type: string
shopperIP:
description: |-
@@ -1360,27 +1398,33 @@ components:
PaymentRequest3ds2:
properties:
accountInfo:
description: Shopper account information for 3D Secure 2.
description: |-
Shopper account information for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/AccountInfo'
additionalAmount:
description: |-
If you want a [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
If you want a [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) request to use a non-zero value, assign this value to `additionalAmount` (while the amount must be still set to 0 to trigger BIN or card verification).
Required to be in the same currency as the `amount`.
$ref: '#/components/schemas/Amount'
additionalData:
description: |-
This field contains additional data, which may be required for a particular payment 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 [additionalData section](https://docs.adyen.com/developers/api-reference/payments-api#paymentrequestadditionaldata).
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 [additionalData section](https://docs.adyen.com/api-reference/payments-api#paymentrequestadditionaldata).
type: object
amount:
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).'
$ref: '#/components/schemas/Amount'
billingAddress:
description: The address where to send the invoice.
description: |-
The address where to send the invoice.
> For 3D Secure 2 transactions, schemes require the `billingAddress` for both `deviceChannel` **browser** and **app**. Include all of the fields within this object.
$ref: '#/components/schemas/Address'
browserInfo:
description: The shopper's browser information.
description: |-
The shopper's browser information.
> For 3D Secure 2 transactions, `browserInfo` is required for `channel` **web** (or `deviceChannel` **browser**).
$ref: '#/components/schemas/BrowserInfo'
captureDelayHours:
description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.'
@@ -1409,14 +1453,14 @@ components:
format: date-time
type: string
deviceFingerprint:
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/developers/risk-management/device-fingerprinting).'
description: 'A string containing the shopper''s device fingerprint. For more information, refer to [Device fingerprinting](https://docs.adyen.com/risk-management/device-fingerprinting).'
type: string
fraudOffset:
description: An integer value that is added to the normal fraud score. The value can be either positive or negative.
format: int32
type: integer
installments:
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/payment-methods/installment-payments).'
description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/payment-methods/installment-payments).'
$ref: '#/components/schemas/Installments'
mcc:
description: 'The [merchant category code](https://en.wikipedia.org/wiki/Merchant_category_code) (MCC) is a four-digit number, which relates to a particular market segment. This code reflects the predominant activity that is conducted by the merchant.'
@@ -1426,11 +1470,14 @@ components:
type: string
merchantOrderReference:
description: |-
This reference allows linking multiple transactions to each other.
This reference allows linking multiple transactions to each other for reporting purposes (i.e. order auth-rate). The reference should be unique per billing cycle.
The same merchant order reference should never be reused after the first authorised attempt. If used, this field should be supplied for all incoming authorisations.
> We strongly recommend you send the `merchantOrderReference` value to benefit from linking payment requests when authorisation retries take place. In addition, we recommend you provide `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values in `PaymentRequest.additionalData`.
type: string
merchantRiskIndicator:
description: Additional risk fields for 3D Secure 2.
description: |-
Additional risk fields for 3D Secure 2.
> For 3D Secure 2 transactions, we recommend that you include this object to increase the chances of achieving a frictionless flow.
$ref: '#/components/schemas/MerchantRiskIndicator'
metadata:
description: |-
@@ -1441,7 +1488,7 @@ components:
description: 'When you are doing multiple partial (gift card) payments, this is the `pspReference` of the first payment. We use this to link the multiple payments to each other. As your own reference for linking multiple payments, use the `merchantOrderReference`instead.'
type: string
recurring:
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/developers/features/recurring-payments).'
description: 'The recurring settings for the payment. Use this property when you want to enable [recurring payments](https://docs.adyen.com/classic-integration/recurring-payments).'
$ref: '#/components/schemas/Recurring'
recurringProcessingModel:
description: |
@@ -1476,7 +1523,9 @@ components:
description: A session ID used to identify a payment session.
type: string
shopperEmail:
description: 'The shopper''s email address. We recommend that you provide this data, as it is used in velocity fraud checks.'
description: |-
The shopper's email address. We recommend that you provide this data, as it is used in velocity fraud checks.
> For 3D Secure 2 transactions, schemes require the `shopperEmail` for both `deviceChannel` **browser** and **app**.
type: string
shopperIP:
description: |-
@@ -1586,7 +1635,7 @@ components:
description: |-
The 3D request data for the issuer.
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).
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/classic-integration/3d-secure).
type: string
pspReference:
description: |-
@@ -1601,24 +1650,30 @@ components:
When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values.
type: string
resultCode:
description: |-
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.
* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.
* **AuthenticationFinished** – The payment has been successfully authenticated with 3D Secure 2. Returned for 3D Secure 2 authentication-only transactions.
* **Authorised** – The payment was successfully authorised. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state.
* **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.
* **ChallengeShopper** – The issuer requires further shopper interaction before the payment can be authenticated. Returned for 3D Secure 2 transactions.
* **Error** – There was an error when the payment was being processed. The reason is given in the `refusalReason` field. This is a final state.
* **IdentifyShopper** – The issuer requires the shopper's device fingerprint before the payment can be authenticated. Returned for 3D Secure 2 transactions.
* **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. 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/development-resources/payments-with-pending-status).
* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.
* **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation.
enum:
- AuthenticationFinished
- Authorised
- PartiallyAuthorised
- Refused
- Error
- Cancelled
- ChallengeShopper
- Error
- IdentifyShopper
- Pending
- Received
- RedirectShopper
- Refused
type: string
Recurring:
properties:
@@ -1626,10 +1681,10 @@ components:
description: |-
The type of recurring contract to be used.
Possible values:
* `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` – 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/payments-essentials/payment-glossary#card_security_code_cvc_cvv_cid_).
* `RECURRING` – Payment details can be used without the card security code to initiate [card-not-present transactions](https://docs.adyen.com/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).
* `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/features/third-party-payouts).
enum:
- ONECLICK
- RECURRING
@@ -1705,7 +1760,7 @@ components:
properties:
currency:
description: |-
The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).
The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
If this value is not provided, the currency in which the payment is made will be used.
maxLength: 3
@@ -1715,7 +1770,7 @@ components:
description: |-
The payable amount that can be charged for the transaction.
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/development-resources/currency-codes).
The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/development-resources/currency-codes).
format: int64
type: integer
required:
@@ -1723,7 +1778,7 @@ components:
ThreeDS2RequestData:
properties:
authenticationOnly:
description: 'If set to true, you will only do the 3D Secure 2 authentication, not the payment authorization.'
description: 'If set to true, you will only perform the [3D Secure 2 authentication](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration), and not the payment authorisation.'
type: boolean
challengeIndicator:
description: |
@@ -1745,30 +1800,30 @@ components:
* `browser`
type: string
deviceRenderOptions:
description: Display options for the 3D Secure 2 SDK. Only for `deviceChannel` set to **app**.
description: |-
Display options for the 3D Secure 2 SDK.
Required for `deviceChannel` **app**.
$ref: '#/components/schemas/DeviceRenderOptions'
messageVersion:
description: The `messageVersion` value indicating the 3D Secure 2 protocol version.
type: string
notificationURL:
description: |-
URL the `CRes` value will be sent.
Only for `deviceChannel` set to **browser**.
description: URL to where the issuer should send the `CRes`. Required if you are not using components for `channel` **Web** or if you are using classic integration `deviceChannel` **browser**.
type: string
sdkAppID:
description: |-
The `sdkAppID` value as received from the 3D Secure 2 SDK.
Only for `deviceChannel` set to **app**.
Required for `deviceChannel` set to **app**.
type: string
sdkEncData:
description: |-
The `sdkEncData` value as received from the 3D Secure 2 SDK.
Only for `deviceChannel` set to **app**.
Required for `deviceChannel` set to **app**.
type: string
sdkEphemPubKey:
description: |-
The `sdkEphemPubKey` value as received from the 3D Secure 2 SDK.
Only for `deviceChannel` set to **app**.
Required for `deviceChannel` set to **app**.
$ref: '#/components/schemas/SDKEphemPubKey'
sdkMaxTimeout:
description: |-
@@ -1786,11 +1841,14 @@ components:
The `sdkTransID` value as received from the 3D Secure 2 SDK.
Only for `deviceChannel` set to **app**.
type: string
threeDSCompInd:
description: Completion indicator for the device fingerprinting.
type: string
threeDSRequestorID:
description: Unique 3D Secure requestor identifier assigned by the Directory Server.
description: 'Required for [authentication-only integration](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration) for Visa. Unique 3D Secure requestor identifier assigned by the Directory Server when you enrol for 3D Secure 2.'
type: string
threeDSRequestorName:
description: Unique 3D Secure requestor name assigned by the Directory Server.
description: 'Required for [authentication-only integration](https://docs.adyen.com/checkout/3d-secure-2/3ds2-checkout-authentication-only-integration) for Visa. Unique 3D Secure requestor name assigned by the Directory Server when you enrol for 3D Secure 2.'
type: string
threeDSRequestorURL:
description: URL of the (customer service) website that will be shown to the shopper in case of technical errors during the 3D Secure 2 process.
@@ -1803,7 +1861,7 @@ components:
description: The `authenticationValue` value as defined in the 3D Secure 2 specification.
type: string
dsTransID:
description: The `dsTransID` value as defined in the 3D Secure 2 specification.
description: Supported for 3D Secure 2. The unique transaction identifier assigned by the Directory Server (DS) to identify a single transaction.
type: string
eci:
description: The `eci` value as defined in the 3D Secure 2 specification.
@@ -1868,6 +1926,9 @@ components:
- E
- C
type: string
dsTransID:
description: Supported for 3D Secure 2. The unique transaction identifier assigned by the DS to identify a single transaction.
type: string
eci:
description: The electronic commerce indicator.
type: string
@@ -1875,9 +1936,6 @@ components:
description: The version of the 3D Secure protocol.
type: string
xid:
description: |-
The transaction identifier (Base64-encoded, 20 bytes in a decoded form).
In 3D Secure 2, this is the `threeDSServerTransID`.
description: 'Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).'
format: byte
type: string