From e4415dd65d4fd55b196ac7ebcbadb1f898709f4e Mon Sep 17 00:00:00 2001 From: Aleksei Akimov Date: Thu, 4 Apr 2019 13:44:46 +0200 Subject: [PATCH] Updated Payout specs --- specs/3.0/PayoutService-v30.json | 60 +++++++------------------------- specs/3.0/PayoutService-v30.yaml | 54 ++++++++-------------------- 2 files changed, 27 insertions(+), 87 deletions(-) diff --git a/specs/3.0/PayoutService-v30.json b/specs/3.0/PayoutService-v30.json index 25caae7..2bde34a 100644 --- a/specs/3.0/PayoutService-v30.json +++ b/specs/3.0/PayoutService-v30.json @@ -9,7 +9,7 @@ "version" : "30", "title" : "Adyen Payout Service", "description" : "A set of API endpoints that allow you to store payout details, confirm, or decline a payout.\n\nFor more information, refer to [Third-party payouts](https://docs.adyen.com/developers/features/third-party-payouts).", - "termsOfService" : "https://docs.adyen.com/legal/terms-conditions", + "termsOfService" : "https://www.adyen.com/legal/terms-and-conditions", "contact" : { "name" : "Adyen Support", "url" : "https://support.adyen.com/", @@ -323,13 +323,13 @@ "Amount" : { "properties" : { "currency" : { - "description" : "The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).", + "description" : "The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).", "maxLength" : 3, "minLength" : 3, "type" : "string" }, "value" : { - "description" : "The payable amount that can be charged for the transaction.\n\nThe transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/currency-codes).", + "description" : "The payable amount that can be charged for the transaction.\n\nThe transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/development-resources/currency-codes).", "format" : "int64", "type" : "integer" } @@ -402,7 +402,7 @@ "Card" : { "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:\n* CVV2/CVC2 – length: 3 digits\n* CID – length: 4 digits\n> If you are using [Client-Side Encryption](https://docs.adyen.com/developers/ecommerce-integration), the CVC code is present in the encrypted data. You must never post the card details to the server.\n> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/features/recurring-payments).\n> When this value is returned in a response, it is always empty because it is not stored.", + "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:\n* CVV2/CVC2 – length: 3 digits\n* CID – length: 4 digits\n> 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.\n> This field must be always present in a [one-click payment request](https://docs.adyen.com/developers/classic-integration/recurring-payments).\n> When this value is returned in a response, it is always empty because it is not stored.", "maxLength" : 20, "minLength" : 1, "type" : "string" @@ -414,7 +414,7 @@ "type" : "string" }, "expiryYear" : { - "description" : "The card expiry year.\nFormat: 4 digits. For example: 2018", + "description" : "The card expiry year.\nFormat: 4 digits. For example: 2020", "maxLength" : 4, "minLength" : 4, "type" : "string" @@ -560,9 +560,6 @@ "FundSource" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "a map of name/value pairs for passing in additional/industry-specific data", "type" : "object" }, @@ -603,9 +600,6 @@ "ModifyRequest" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be required for a particular payout request.", "type" : "object" }, @@ -626,14 +620,11 @@ "ModifyResponse" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be returned in a particular response.", "type" : "object" }, "pspReference" : { - "description" : "Adyen's 16-digit unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request.", + "description" : "Adyen's 16-character string reference associated with the transaction. This value is globally unique; quote it when communicating with us about this response.", "type" : "string" }, "response" : { @@ -681,18 +672,15 @@ "PayoutRequest" : { "properties" : { "additionalAmount" : { - "description" : "If you want a [BIN or card verification](https://docs.adyen.com/developers/ecommerce-integration/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).\nRequired to be in the same currency as the `amount`. ", + "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).\nRequired to be in the same currency as the `amount`. ", "$ref" : "#/components/schemas/Amount" }, "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be required for a particular payment request.\n\nThe `additionalData` object consists of entries, each of which includes the key and value. For more information on possible key-value pairs, refer to the [additionalData section](https://docs.adyen.com/developers/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/ecommerce-integration/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/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).", "$ref" : "#/components/schemas/Amount" }, "bankAccount" : { @@ -768,13 +756,10 @@ "type" : "string" }, "merchantOrderReference" : { - "description" : "This reference allows linking multiple transactions to each other.\n> When providing the `merchantOrderReference` value, we also recommend you submit `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values. ", + "description" : "This reference allows linking multiple transactions to each other.\n> 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" }, "metadata" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "Metadata consists of entries, each of which includes a key and a value.\nLimitations: Error \"177\", \"Metadata size exceeds limit\"", "type" : "object" }, @@ -883,10 +868,7 @@ "PayoutResponse" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, - "description" : "This field contains additional data, which may be required to return in a particular payment response. To choose data fields to be returned, go to **Customer Area** > **Settings** > **API and Response**.", + "description" : "This field contains additional data, which may be required to return in a particular payment response. To choose data fields to be returned, go to **Customer Area** > **Account** > **API URLs**.", "type" : "object" }, "authCode" : { @@ -918,7 +900,7 @@ "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.\n\n> `pspReference` is returned only for non-redirect payment methods.", + "description" : "Adyen's 16-character string reference associated with the transaction/request. This value is globally unique; quote it when communicating with us about this request.\n\n> `pspReference` is returned only for non-redirect payment methods.", "type" : "string" }, "refusalReason" : { @@ -926,7 +908,7 @@ "type" : "string" }, "resultCode" : { - "description" : "The result of the payment. Possible values:\n\n* **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.\n* **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state.\n* **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/make-a-payment#idealpayments).\n* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.\n* **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state.\n* **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).\n* **Error** – Indicates an error occurred during processing of the payment. The reason is given in the `refusalReason` field. This is a final state.", + "description" : "The result of the payment. Possible values:\n\n* **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.\n* **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state.\n* **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation.\n* **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments.\n* **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state.\n* **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).\n* **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", @@ -968,9 +950,6 @@ "StoreDetailAndSubmitRequest" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be required for a particular request.", "type" : "object" }, @@ -1065,9 +1044,6 @@ "StoreDetailAndSubmitResponse" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be returned in a particular response.", "type" : "object" }, @@ -1092,9 +1068,6 @@ "StoreDetailRequest" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be required for a particular request.", "type" : "object" }, @@ -1175,9 +1148,6 @@ "StoreDetailResponse" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be returned in a particular response.", "type" : "object" }, @@ -1203,9 +1173,6 @@ "SubmitRequest" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be required for a particular request.", "type" : "object" }, @@ -1285,9 +1252,6 @@ "SubmitResponse" : { "properties" : { "additionalData" : { - "additionalProperties" : { - "type" : "string" - }, "description" : "This field contains additional data, which may be returned in a particular response.", "type" : "object" }, diff --git a/specs/3.0/PayoutService-v30.yaml b/specs/3.0/PayoutService-v30.yaml index b8611bf..ad5d60b 100644 --- a/specs/3.0/PayoutService-v30.yaml +++ b/specs/3.0/PayoutService-v30.yaml @@ -8,7 +8,7 @@ info: A set of API endpoints that allow you to store payout details, confirm, or decline a payout. For more information, refer to [Third-party payouts](https://docs.adyen.com/developers/features/third-party-payouts). - termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + termsOfService: 'https://www.adyen.com/legal/terms-and-conditions' contact: name: Adyen Support url: 'https://support.adyen.com/' @@ -238,7 +238,7 @@ components: Amount: properties: currency: - description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).' + description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/development-resources/currency-codes).' maxLength: 3 minLength: 3 type: string @@ -246,7 +246,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/currency-codes). + The transaction amount needs to be represented in minor units according to the [following table](https://docs.adyen.com/developers/development-resources/currency-codes). format: int64 type: integer required: @@ -317,8 +317,8 @@ components: 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: * CVV2/CVC2 – length: 3 digits * CID – length: 4 digits - > If you are using [Client-Side Encryption](https://docs.adyen.com/developers/ecommerce-integration), 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/features/recurring-payments). + > 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). > When this value is returned in a response, it is always empty because it is not stored. maxLength: 20 minLength: 1 @@ -335,7 +335,7 @@ components: expiryYear: description: |- The card expiry year. - Format: 4 digits. For example: 2018 + Format: 4 digits. For example: 2020 maxLength: 4 minLength: 4 type: string @@ -447,8 +447,6 @@ components: FundSource: properties: additionalData: - additionalProperties: - type: string description: a map of name/value pairs for passing in additional/industry-specific data type: object billingAddress: @@ -480,8 +478,6 @@ components: ModifyRequest: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be required for a particular payout request.' type: object merchantAccount: @@ -496,12 +492,10 @@ components: ModifyResponse: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be returned in a particular response.' type: object pspReference: - description: Adyen's 16-digit unique reference associated with the transaction. This value is globally unique; quote it when communicating with us about this request. + description: Adyen's 16-character string reference associated with the transaction. This value is globally unique; quote it when communicating with us about this response. type: string response: description: |- @@ -544,19 +538,17 @@ components: properties: additionalAmount: description: |- - If you want a [BIN or card verification](https://docs.adyen.com/developers/ecommerce-integration/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/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`. $ref: '#/components/schemas/Amount' additionalData: - additionalProperties: - type: string 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). type: object amount: - description: 'The amount information for the transaction. For [BIN or card verification](https://docs.adyen.com/developers/ecommerce-integration/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/developers/payment-methods/cards/bin-data-and-card-verification) requests, set amount to 0 (zero).' $ref: '#/components/schemas/Amount' bankAccount: description: |- @@ -628,11 +620,9 @@ components: merchantOrderReference: description: |- This reference allows linking multiple transactions to each other. - > When providing the `merchantOrderReference` value, we also recommend you submit `retry.orderAttemptNumber`, `retry.chainAttemptNumber`, and `retry.skipRetry` values. + > 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 metadata: - additionalProperties: - type: string description: |- Metadata consists of entries, each of which includes a key and a value. Limitations: Error "177", "Metadata size exceeds limit" @@ -741,9 +731,7 @@ components: PayoutResponse: properties: additionalData: - additionalProperties: - type: string - description: 'This field contains additional data, which may be required to return in a particular payment response. To choose data fields to be returned, go to **Customer Area** > **Settings** > **API and Response**.' + description: 'This field contains additional data, which may be required to return in a particular payment response. To choose data fields to be returned, go to **Customer Area** > **Account** > **API URLs**.' type: object authCode: description: |- @@ -780,7 +768,7 @@ components: 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. + Adyen's 16-character string reference associated with the transaction/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 @@ -796,7 +784,7 @@ components: * **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/make-a-payment#idealpayments). + * **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. * **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). @@ -837,8 +825,6 @@ components: StoreDetailAndSubmitRequest: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be required for a particular request.' type: object amount: @@ -931,8 +917,6 @@ components: StoreDetailAndSubmitResponse: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be returned in a particular response.' type: object pspReference: @@ -954,8 +938,6 @@ components: StoreDetailRequest: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be required for a particular request.' type: object bank: @@ -1037,8 +1019,6 @@ components: StoreDetailResponse: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be returned in a particular response.' type: object pspReference: @@ -1057,8 +1037,6 @@ components: SubmitRequest: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be required for a particular request.' type: object amount: @@ -1071,7 +1049,7 @@ components: For Paysafecard it must be the same as used when registering the Paysafecard account. - > This field is mandatory for natural persons. + > This field is mandatory for natural persons. > This field is required to update the existing `dateOfBirth` that is associated with this recurring contract. format: date-time type: string @@ -1148,8 +1126,6 @@ components: SubmitResponse: properties: additionalData: - additionalProperties: - type: string description: 'This field contains additional data, which may be returned in a particular response.' type: object pspReference: