openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute Donations API
description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
x-timestamp: '2023-05-30T15:27:20Z'
termsOfService: https://www.adyen.com/legal/terms-and-conditions
contact:
name: Adyen Developer Experience team
url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: Donations
paths:
/donations:
post:
tags:
- Donations
summary: Adyen Start a Transaction for Donations
description: 'Takes in the donation token generated by the `/payments` request and uses it to make the donation for the donation account specified in the request.
For more information, see [Donations](https://docs.adyen.com/online-payments/donations).'
operationId: post-donations
x-sortIndex: 2
x-methodName: donations
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
examples:
donations:
$ref: '#/components/examples/post-donations-donations'
donations-with-token:
$ref: '#/components/examples/post-donations-donations-with-token'
schema:
$ref: '#/components/schemas/DonationPaymentRequest'
parameters:
- $ref: '#/components/parameters/Idempotency-Key'
responses:
'200':
content:
application/json:
examples:
donations:
$ref: '#/components/examples/post-donations-donations-200'
schema:
$ref: '#/components/schemas/DonationPaymentResponse'
description: OK - the request has succeeded.
headers:
Idempotency-Key:
$ref: '#/components/headers/Idempotency-Key'
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/ServiceError'
description: Bad Request - a problem reading or understanding the request.
'401':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-401'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/ServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/ServiceError'
description: Unprocessable Entity - a request validation error.
headers:
Idempotency-Key:
$ref: '#/components/headers/Idempotency-Key'
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/ServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
LineItem:
properties:
amountExcludingTax:
description: Item amount excluding the tax, in minor units.
format: int64
type: integer
amountIncludingTax:
description: Item amount including the tax, in minor units.
format: int64
type: integer
brand:
x-addedInVersion: '70'
description: Brand of the item.
type: string
color:
x-addedInVersion: '70'
description: Color of the item.
type: string
description:
description: Description of the line item.
type: string
id:
description: ID of the line item.
type: string
imageUrl:
description: Link to the picture of the purchased item.
type: string
itemCategory:
description: Item category, used by the payment methods PayPal and Ratepay.
type: string
manufacturer:
x-addedInVersion: '70'
description: Manufacturer of the item.
type: string
productUrl:
description: Link to the purchased item.
type: string
quantity:
description: Number of items.
format: int64
type: integer
receiverEmail:
x-addedInVersion: '70'
description: Email associated with the given product in the basket (usually in electronic gift cards).
type: string
size:
x-addedInVersion: '70'
description: Size of the item.
type: string
sku:
x-addedInVersion: '70'
description: Stock keeping unit.
type: string
taxAmount:
description: Tax amount, in minor units.
format: int64
type: integer
taxPercentage:
description: Tax percentage, in minor units.
format: int64
type: integer
upc:
x-addedInVersion: '70'
description: Universal Product Code.
type: string
type: object
ThreeDSRequestorPriorAuthenticationInfo:
properties:
threeDSReqPriorAuthData:
description: 'Data that documents and supports a specific authentication process. Maximum length: 2048 bytes.'
type: string
threeDSReqPriorAuthMethod:
description: 'Mechanism used by the Cardholder to previously authenticate to the 3DS Requestor. Allowed values:
* **01** Frictionless authentication occurred by ACS.
* **02** Cardholder challenge occurred by ACS.
* **03** AVS verified.
* **04** Other issuer methods.'
enum:
- '01'
- '02'
- '03'
- '04'
maxLength: 2
minLength: 2
type: string
threeDSReqPriorAuthTimestamp:
description: 'Date and time in UTC of the prior cardholder authentication. Format: YYYYMMDDHHMM'
maxLength: 12
minLength: 12
type: string
threeDSReqPriorRef:
description: 'This data element provides additional information to the ACS to determine the best approach for handing a request. This data element contains an ACS Transaction ID for a prior authenticated transaction. For example, the first recurring transaction that was authenticated with the cardholder. Length: 30 characters.'
maxLength: 36
minLength: 36
type: string
type: object
GooglePayDonations:
additionalProperties: false
properties:
checkoutAttemptId:
x-addedInVersion: '68'
description: The checkout attempt identifier.
type: string
fundingSource:
description: The funding source that should be used when multiple sources are available. For Brazilian combo cards, by default the funding source is credit. To use debit, set this value to **debit**.
enum:
- credit
- debit
type: string
googlePayCardNetwork:
description: 'The selected payment card network. '
type: string
googlePayToken:
description: The `token` that you obtained from the [Google Pay API](https://developers.google.com/pay/api/web/reference/response-objects#PaymentData) `PaymentData` response.
type: string
recurringDetailReference:
deprecated: true
x-deprecatedInVersion: '49'
x-deprecatedMessage: Use `storedPaymentMethodId` instead.
description: This is the `recurringDetailReference` returned in the response when you created the token.
type: string
storedPaymentMethodId:
x-addedInVersion: '49'
description: This is the `recurringDetailReference` returned in the response when you created the token.
maxLength: 64
type: string
type:
default: googlepay
description: '**googlepay**, **paywithgoogle**'
enum:
- googlepay
type: string
required:
- googlePayToken
title: Google Pay
type: object
AdditionalDataRiskStandalone:
properties:
PayPal.CountryCode:
description: Shopper's country of residence in the form of ISO standard 3166 2-character country codes.
type: string
PayPal.EmailId:
description: Shopper's email.
type: string
PayPal.FirstName:
description: Shopper's first name.
type: string
PayPal.LastName:
description: Shopper's last name.
type: string
PayPal.PayerId:
description: 'Unique PayPal Customer Account identification number. Character length and limitations: 13 single-byte alphanumeric characters.'
type: string
PayPal.Phone:
description: Shopper's phone number.
type: string
PayPal.ProtectionEligibility:
description: 'Allowed values:
* **Eligible** Merchant is protected by PayPal''s Seller Protection Policy for Unauthorized Payments and Item Not Received.
* **PartiallyEligible** Merchant is protected by PayPal''s Seller Protection Policy for Item Not Received.
* **Ineligible** Merchant is not protected under the Seller Protection Policy.'
type: string
PayPal.TransactionId:
description: Unique transaction ID of the payment.
type: string
avsResultRaw:
description: 'Raw AVS result received from the acquirer, where available. Example: D'
type: string
bin:
description: The Bank Identification Number of a credit card, which is the first six digits of a card number. Required for [tokenized card request](https://docs.adyen.com/risk-management/standalone-risk#tokenised-pan-request).
type: string
cvcResultRaw:
description: 'Raw CVC result received from the acquirer, where available. Example: 1'
type: string
riskToken:
description: Unique identifier or token for the shopper's card details.
type: string
threeDAuthenticated:
description: 'A Boolean value indicating whether 3DS authentication was completed on this payment. Example: true'
type: string
threeDOffered:
description: 'A Boolean value indicating whether 3DS was offered for this payment. Example: true'
type: string
tokenDataType:
description: 'Required for PayPal payments only. The only supported value is: **paypal**.'
type: string
type: object
ResponseAdditionalDataNetworkTokens:
properties:
networkToken.available:
description: Indicates whether a network token is available for the specified card.
type: string
networkToken.bin:
description: The Bank Identification Number of a tokenized card, which is the first six digits of a card number.
type: string
networkToken.tokenSummary:
description: The last four digits of a network token.
type: string
type: object
AdditionalDataWallets:
properties:
androidpay.token:
description: The Android Pay token retrieved from the SDK.
type: string
masterpass.transactionId:
description: The Mastercard Masterpass Transaction ID retrieved from the SDK.
type: string
payment.token:
description: The Apple Pay token retrieved from the SDK.
type: string
paywithgoogle.token:
description: The Google Pay token retrieved from the SDK.
type: string
samsungpay.token:
description: The Samsung Pay token retrieved from the SDK.
type: string
visacheckout.callId:
description: The Visa Checkout Call ID retrieved from the SDK.
type: string
type: object
AdditionalDataRatepay:
properties:
ratepay.installmentAmount:
description: Amount the customer has to pay each month.
type: string
ratepay.interestRate:
description: Interest rate of this installment.
type: string
ratepay.lastInstallmentAmount:
description: Amount of the last installment.
type: string
ratepay.paymentFirstday:
description: Calendar day of the first payment.
type: string
ratepaydata.deliveryDate:
description: Date the merchant delivered the goods to the customer.
type: string
ratepaydata.dueDate:
description: Date by which the customer must settle the payment.
type: string
ratepaydata.invoiceDate:
description: Invoice date, defined by the merchant. If not included, the invoice date is set to the delivery date.
type: string
ratepaydata.invoiceId:
description: Identification name or number for the invoice, defined by the merchant.
type: string
type: object
AdditionalData3DSecure:
properties:
allow3DS2:
deprecated: true
x-deprecatedInVersion: '69'
x-deprecatedMessage: Use `authenticationData.threeDSRequestData.nativeThreeDS` instead.
description: "Indicates if you are able to process 3D Secure 2 transactions natively on your payment page. Send this parameter when you are using `/payments` endpoint with any of our [native 3D Secure 2 solutions](https://docs.adyen.com/online-payments/3d-secure/native-3ds2).\n\n > This parameter only indicates readiness to support native 3D Secure 2 authentication. To specify if you _want_ to perform 3D Secure, use [Dynamic 3D Secure](/risk-management/dynamic-3d-secure)\nor send the `executeThreeD` parameter.\nPossible values:\n* **true** - Ready to support native 3D Secure 2 authentication. Setting this to true does not mean always applying 3D Secure 2. Adyen still selects the version of 3D Secure based on configuration to optimize authorisation rates and improve the shopper's experience.\n* **false** Not ready to support native 3D Secure 2 authentication. Adyen will not offer 3D Secure 2 to your shopper regardless of your configuration.\n"
type: string
challengeWindowSize:
description: "Dimensions of the 3DS2 challenge window to be displayed to the cardholder.\n\nPossible values:\n\n* **01** - size of 250x400 \n* **02** - size of 390x400\n* **03** - size of 500x600\n* **04** - size of 600x400\n* **05** - Fullscreen"
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
type: string
executeThreeD:
deprecated: true
x-deprecatedInVersion: '69'
x-deprecatedMessage: Use [`authenticationData.attemptAuthentication`](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments?target=_blank#request-authenticationData-attemptAuthentication) instead
description: "Indicates if you want to perform 3D Secure authentication on a transaction.\n\n > Alternatively, you can use [Dynamic 3D Secure](/risk-management/dynamic-3d-secure) to configure rules for applying 3D Secure.\n\nPossible values:\n* **true** Perform 3D Secure authentication.\n* **false** Don't perform 3D Secure authentication. Note that this setting results in refusals if the issuer mandates 3D Secure because of the PSD2 directive or other, national regulations. \n"
type: string
mpiImplementationType:
description: In case of Secure+, this field must be set to **CUPSecurePlus**.
type: string
scaExemption:
description: "Indicates the [exemption type](https://docs.adyen.com/payments-fundamentals/psd2-sca-compliance-and-implementation-guide#specifypreferenceinyourapirequest) that you want to request for the transaction.\n\n Possible values:\n* **lowValue** \n* **secureCorporate** \n* **trustedBeneficiary** \n* **transactionRiskAnalysis** "
type: string
threeDSVersion:
description: "Indicates your preference for the 3D Secure version. \n> If you use this parameter, you override the checks from Adyen's Authentication Engine. We recommend to use this field only if you have an extensive knowledge of 3D Secure.\n\nPossible values:\n* **1.0.2**: Apply 3D Secure version 1.0.2. \n* **2.1.0**: Apply 3D Secure version 2.1.0. \n* **2.2.0**: Apply 3D Secure version 2.2.0. If the issuer does not support version 2.2.0, we will fall back to 2.1.0.\n\nThe following rules apply:\n* If you prefer 2.1.0 or 2.2.0 but we receive a negative `transStatus` in the `ARes`, we will apply the fallback policy configured in your account. For example, if the configuration is to fall back to 3D Secure 1, we will apply version 1.0.2.\n* If you prefer 2.1.0 or 2.2.0 but the BIN is not enrolled, you will receive an error.\n\n"
type: string
type: object
AdditionalDataSubMerchant:
properties:
subMerchant.numberOfSubSellers:
description: Required for transactions performed by registered payment facilitators. Indicates the number of sub-merchants contained in the request. For example, **3**.
type: string
subMerchant.subSeller[subSellerNr].city:
description: 'Required for transactions performed by registered payment facilitators. The city of the sub-merchant''s address.
* Format: Alphanumeric
* Maximum length: 13 characters'
type: string
subMerchant.subSeller[subSellerNr].country:
description: "Required for transactions performed by registered payment facilitators. The three-letter country code of the sub-merchant's address. For example, **BRA** for Brazil. \n* Format: [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3)\n* Fixed length: 3 characters"
type: string
subMerchant.subSeller[subSellerNr].id:
description: "Required for transactions performed by registered payment facilitators. A unique identifier that you create for the sub-merchant, used by schemes to identify the sub-merchant. \n* Format: Alphanumeric\n* Maximum length: 15 characters"
type: string
subMerchant.subSeller[subSellerNr].mcc:
description: "Required for transactions performed by registered payment facilitators. The sub-merchant's 4-digit Merchant Category Code (MCC). \n* Format: Numeric\n* Fixed length: 4 digits"
type: string
subMerchant.subSeller[subSellerNr].name:
description: 'Required for transactions performed by registered payment facilitators. The name of the sub-merchant. Based on scheme specifications, this value will overwrite the shopper statement that will appear in the card statement.
* Format: Alphanumeric
* Maximum length: 22 characters'
type: string
subMerchant.subSeller[subSellerNr].postalCode:
description: 'Required for transactions performed by registered payment facilitators. The postal code of the sub-merchant''s address, without dashes.
* Format: Numeric
* Fixed length: 8 digits'
type: string
subMerchant.subSeller[subSellerNr].state:
description: 'Required for transactions performed by registered payment facilitators. The state code of the sub-merchant''s address, if applicable to the country.
* Format: Alphanumeric
* Maximum length: 2 characters'
type: string
subMerchant.subSeller[subSellerNr].street:
description: 'Required for transactions performed by registered payment facilitators. The street name and house number of the sub-merchant''s address.
* Format: Alphanumeric
* Maximum length: 60 characters'
type: string
subMerchant.subSeller[subSellerNr].taxId:
description: 'Required for transactions performed by registered payment facilitators. The tax ID of the sub-merchant.
* Format: Numeric
* Fixed length: 11 digits for the CPF or 14 digits for the CNPJ'
type: string
type: object
CheckoutSDKAction:
additionalProperties: false
properties:
paymentData:
description: Encoded payment data.
type: string
paymentMethodType:
description: Specifies the payment method.
type: string
sdkData:
additionalProperties:
type: string
description: The data to pass to the SDK.
type: object
type:
description: The type of the action.
enum:
- sdk
- wechatpaySDK
type: string
url:
description: Specifies the URL to redirect to.
type: string
required:
- type
type: object
ResponseAdditionalDataDomesticError:
properties:
domesticRefusalReasonRaw:
description: "The reason the transaction was declined, given by the local issuer. \nCurrently available for merchants in Japan."
type: string
domesticShopperAdvice:
description: "The action the shopper should take, in a local language. \nCurrently available in Japanese, for merchants in Japan."
type: string
type: object
ExternalPlatform:
properties:
integrator:
description: External platform integrator.
type: string
name:
description: Name of the field. For example, Name of External Platform.
type: string
version:
description: Version of the field. For example, Version of External Platform.
type: string
type: object
ThreeDSecureData:
properties:
authenticationResponse:
description: 'In 3D Secure 1, the authentication response if the shopper was redirected.
In 3D Secure 2, this is the `transStatus` from the challenge result. If the transaction was frictionless, omit this parameter.'
enum:
- Y
- N
- U
- A
type: string
cavv:
description: The cardholder authentication value (base64 encoded, 20 bytes in a decoded form).
format: byte
type: string
cavvAlgorithm:
description: The CAVV algorithm used. Include this only for 3D Secure 1.
type: string
challengeCancel:
x-addedInVersion: '67'
description: Indicator informing the Access Control Server (ACS) and the Directory Server (DS) that the authentication has been cancelled. For possible values, refer to [3D Secure API reference](https://docs.adyen.com/online-payments/3d-secure/api-reference#mpidata).
enum:
- '01'
- '02'
- '03'
- '04'
- '05'
- '06'
- '07'
type: string
directoryResponse:
description: 'In 3D Secure 1, this is the enrollment response from the 3D directory server.
In 3D Secure 2, this is the `transStatus` from the `ARes`.'
enum:
- A
- C
- D
- I
- N
- R
- U
- Y
type: string
dsTransID:
x-addedInVersion: '40'
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 electronic commerce indicator.
type: string
riskScore:
x-addedInVersion: '67'
description: Risk score calculated by Directory Server (DS). Required for Cartes Bancaires integrations.
type: string
threeDSVersion:
x-addedInVersion: '40'
description: The version of the 3D Secure protocol.
type: string
tokenAuthenticationVerificationValue:
x-addedInVersion: '68'
description: Network token authentication verification value (TAVV). The network token cryptogram.
format: byte
type: string
transStatusReason:
x-addedInVersion: '67'
description: Provides information on why the `transStatus` field has the specified value. For possible values, refer to [our docs](https://docs.adyen.com/online-payments/3d-secure/api-reference#possible-transstatusreason-values).
type: string
xid:
description: Supported for 3D Secure 1. The transaction identifier (Base64-encoded, 20 bytes in a decoded form).
format: byte
type: string
type: object
AdditionalDataOpenInvoice:
properties:
openinvoicedata.merchantData:
description: 'Holds different merchant data points like product, purchase, customer, and so on. It takes data in a Base64 encoded string.
The `merchantData` parameter needs to be added to the `openinvoicedata` signature at the end.
Since the field is optional, if it''s not included it does not impact computing the merchant signature.
Applies only to Klarna.
You can contact Klarna for the format and structure of the string.'
type: string
openinvoicedata.numberOfLines:
description: 'The number of invoice lines included in `openinvoicedata`.
There needs to be at least one line, so `numberOfLines` needs to be at least 1.'
type: string
openinvoicedata.recipientFirstName:
description: First name of the recipient. If the delivery address and the billing address are different, specify the `recipientFirstName` and `recipientLastName` to share the delivery address with Klarna. Otherwise, only the billing address is shared with Klarna.
type: string
openinvoicedata.recipientLastName:
description: Last name of the recipient. If the delivery address and the billing address are different, specify the `recipientFirstName` and `recipientLastName` to share the delivery address with Klarna. Otherwise, only the billing address is shared with Klarna.
type: string
openinvoicedataLine[itemNr].currencyCode:
description: The three-character ISO currency code.
type: string
openinvoicedataLine[itemNr].description:
description: A text description of the product the invoice line refers to.
type: string
openinvoicedataLine[itemNr].itemAmount:
description: 'The price for one item in the invoice line, represented in minor units.
The due amount for the item, VAT excluded.'
type: string
openinvoicedataLine[itemNr].itemId:
description: A unique id for this item. Required for RatePay if the description of each item is not unique.
type: string
openinvoicedataLine[itemNr].itemVatAmount:
description: The VAT due for one item in the invoice line, represented in minor units.
type: string
openinvoicedataLine[itemNr].itemVatPercentage:
description: 'The VAT percentage for one item in the invoice line, represented in minor units.
For example, 19% VAT is specified as 1900.'
type: string
openinvoicedataLine[itemNr].numberOfItems:
description: The number of units purchased of a specific product.
type: string
openinvoicedataLine[itemNr].returnShippingCompany:
description: Name of the shipping company handling the the return shipment.
type: string
openinvoicedataLine[itemNr].returnTrackingNumber:
description: The tracking number for the return of the shipment.
type: string
openinvoicedataLine[itemNr].returnTrackingUri:
description: URI where the customer can track the return of their shipment.
type: string
openinvoicedataLine[itemNr].shippingCompany:
description: Name of the shipping company handling the delivery.
type: string
openinvoicedataLine[itemNr].shippingMethod:
description: Shipping method.
type: string
openinvoicedataLine[itemNr].trackingNumber:
description: The tracking number for the shipment.
type: string
openinvoicedataLine[itemNr].trackingUri:
description: URI where the customer can track their shipment.
type: string
type: object
AdditionalDataRetry:
properties:
retry.chainAttemptNumber:
description: 'The number of times the transaction (not order) has been retried between different payment service providers. For instance, the `chainAttemptNumber` set to 2 means that this transaction has been recently tried on another provider before being sent to Adyen.
> If you submit `retry.chainAttemptNumber`, `retry.orderAttemptNumber`, and `retry.skipRetry` values, we also recommend you provide the `merchantOrderReference` to facilitate linking payment attempts together.'
type: string
retry.orderAttemptNumber:
description: 'The index of the attempt to bill a particular order, which is identified by the `merchantOrderReference` field. For example, if a recurring transaction fails and is retried one day later, then the order number for these attempts would be 1 and 2, respectively.
> If you submit `retry.chainAttemptNumber`, `retry.orderAttemptNumber`, and `retry.skipRetry` values, we also recommend you provide the `merchantOrderReference` to facilitate linking payment attempts together.'
type: string
retry.skipRetry:
description: 'The Boolean value indicating whether Adyen should skip or retry this transaction, if possible.
> If you submit `retry.chainAttemptNumber`, `retry.orderAttemptNumber`, and `retry.skipRetry` values, we also recommend you provide the `merchantOrderReference` to facilitate linking payment attempts together.'
type: string
type: object
ShopperInteractionDevice:
properties:
locale:
description: Locale on the shopper interaction
# --- truncated at 32 KB (177 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-donations-api-openapi.yml