openapi: 3.1.0
info:
version: '6'
x-publicVersion: true
title: Adyen Account acceptDispute Payment 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: Payment
paths:
/balanceAccounts/{id}/paymentInstruments:
get:
tags:
- Payment
summary: Adyen Get Payment Instruments Linked to a Balance Account
description: "Returns a paginated list of the payment instruments associated with a balance account. \n\nTo fetch multiple pages, use the query parameters.For example, to limit the page to 3 payment instruments which are in active status and to skip the first 6, use `/balanceAccounts/{id}/paymentInstruments?limit=3&offset=6&status=active`."
x-addedInVersion: '1'
operationId: get-balanceAccounts-id-paymentInstruments
x-sortIndex: 4
x-methodName: getPaymentInstrumentsLinkedToBalanceAccount
security:
- clientKey: []
- BasicAuth: []
- ApiKeyAuth: []
parameters:
- description: The unique identifier of the balance account.
name: id
in: path
required: true
schema:
type: string
- description: The number of items that you want to skip.
name: offset
in: query
required: false
schema:
format: int32
type: integer
- description: The number of items returned per page, maximum 100 items. By default, the response returns 10 items per page.
name: limit
in: query
required: false
schema:
format: int32
type: integer
- description: The status of the payment instruments that you want to get. By default, the response includes payment instruments with any status.
name: status
in: query
required: false
schema:
type: string
responses:
'200':
content:
application/json:
examples:
success:
$ref: '#/components/examples/get-balanceAccounts-id-paymentInstruments-success-200'
schema:
$ref: '#/components/schemas/PaginatedPaymentInstrumentsResponse'
description: OK - the request has succeeded.
'400':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-400'
schema:
$ref: '#/components/schemas/RestServiceError'
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/RestServiceError'
description: Unauthorized - authentication required.
'403':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-403'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Forbidden - insufficient permissions to process the request.
'422':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-422'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Unprocessable Entity - a request validation error.
'500':
content:
application/json:
examples:
generic:
$ref: '#/components/examples/generic-500'
schema:
$ref: '#/components/schemas/RestServiceError'
description: Internal Server Error - the server could not process the request.
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/payment:
post:
description: Request sent to terminal to initiate payment. It conveys Information related to the Payment transaction to process. Content of the Payment Request message.
summary: Adyen Payment Request
security:
- BasicAuth: []
- ApiKeyAuth: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentResponse'
examples:
operation200Example:
summary: Default operation 200 response
x-microcks-default: true
value:
Response: example_value
SaleData: example_value
POIData: example_value
PaymentResult: example_value
LoyaltyResult:
- example_value
PaymentReceipt:
- example_value
CustomerOrder:
- example_value
description: It conveys Information related to the Payment transaction processed by the POI System. Content of the Payment Response message.
tags:
- Payment
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
schemas:
TransactionConditions:
type: object
description: Conditions on which the transaction must be processed.
properties:
AllowedPaymentBrand:
type: array
items:
type: string
pattern: ^.+$
description: Restrict brand if data sent.
AcquirerID:
type: array
items:
type: integer
description: Restrict to these Acquirer if present.
DebitPreferredFlag:
type: boolean
description: The preferred type of payment is a debit transaction rather a credit transaction.
AllowedLoyaltyBrand:
type: array
items:
type: string
pattern: ^.+$
description: Restrict brand if data sent.
LoyaltyHandling:
$ref: '#/components/schemas/LoyaltyHandling'
CustomerLanguage:
type: string
pattern: ^[a-z]{2,2}$
description: If the language is selected by the Sale System before the request to the POI.
ForceOnlineFlag:
type: boolean
default: false
description: Go online if data sent.
ForceEntryMode:
$ref: '#/components/schemas/ForceEntryMode'
MerchantCategoryCode:
type: string
pattern: ^.{3,4}$
description: The payment implies a specific MCC.
CardData:
type: object
description: Allows acquisition of the card data by the Sale System before the Payment, CardAcquisition or BalanceInquiry request to the POI. It could also be sent in the CardAcquisition response, to be processed by the Sale System. Information related to the payment card used for the transaction.
properties:
PaymentBrand:
type: string
pattern: ^.+$
description: If card PAN is readable .
MaskedPan:
type: string
pattern: ^.+$
PaymentAccountRef:
type: string
pattern: ^.+$
EntryMode:
$ref: '#/components/schemas/EntryMode'
CardCountryCode:
type: integer
minimum: 3
maximum: 3
description: If available in the card.
ProtectedCardData:
type: string
description: SensitiveCardData protected by CMS EnvelopedData.
SensitiveCardData:
$ref: '#/components/schemas/SensitiveCardData'
AllowedProductCode:
type: array
items:
type: integer
minimum: 1
maximum: 20
AllowedProduct:
type: array
items:
$ref: '#/components/schemas/AllowedProduct'
PaymentToken:
$ref: '#/components/schemas/PaymentToken'
CustomerOrder:
type: array
items:
$ref: '#/components/schemas/CustomerOrder'
UTMCoordinates:
type: object
properties:
UTMZone:
type: string
pattern: ^.+$
UTMEastward:
type: string
pattern: ^.+$
UTMNorthward:
type: string
pattern: ^.+$
required:
- UTMZone
- UTMEastward
- UTMNorthward
StoredValueAccountID:
type: object
description: It contains the identifications of the stored value account or the stored value card, and the associated product sold by the Sale System for stored value requests. Identification of the stored value account or the stored value card.
properties:
StoredValueAccountType:
$ref: '#/components/schemas/StoredValueAccountType'
StoredValueProvider:
type: string
pattern: ^.+$
OwnerName:
type: string
pattern: ^.+$
ExpiryDate:
type: integer
minimum: 4
maximum: 4
EntryMode:
$ref: '#/components/schemas/EntryMode'
IdentificationType:
$ref: '#/components/schemas/IdentificationType'
StoredValueID:
type: string
pattern: ^.+$
required:
- StoredValueAccountType
- EntryMode
- IdentificationType
- StoredValueID
PaymentInstrument:
properties:
balanceAccountId:
description: The unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/post/balanceAccounts__resParam_id) associated with the payment instrument.
type: string
bankAccount:
description: Contains the business account details. Returned when you create a payment instrument with `type` **bankAccount**.
oneOf:
- $ref: '#/components/schemas/IbanAccountIdentification'
- $ref: '#/components/schemas/USLocalAccountIdentification'
card:
description: Contains information about the card payment instrument. Returned when you create a payment instrument with `type` **card**.
$ref: '#/components/schemas/Card'
description:
description: Your description for the payment instrument, maximum 300 characters.
maxLength: 300
type: string
id:
description: The unique identifier of the payment instrument.
type: string
issuingCountryCode:
description: The two-character [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code where the payment instrument is issued. For example, **NL** or **US**.
type: string
paymentInstrumentGroupId:
description: The unique identifier of the [payment instrument group](https://docs.adyen.com/api-explorer/#/balanceplatform/v1/post/paymentInstrumentGroups__resParam_id) to which the payment instrument belongs.
type: string
reference:
description: Your reference for the payment instrument, maximum 150 characters.
maxLength: 150
type: string
status:
description: "The status of the payment instrument. If a status is not specified when creating a payment instrument, it is set to **active** by default. However, there can be exceptions for cards based on the `card.formFactor` and the `issuingCountryCode`. For example, when issuing physical cards in the US, the default status is **inactive**.\n\nPossible values: \n\n * **active**: The payment instrument is active and can be used to make payments. \n\n * **inactive**: The payment instrument is inactive and cannot be used to make payments. \n\n * **suspended**: The payment instrument is suspended, either because it was stolen or lost. \n\n * **closed**: The payment instrument is permanently closed. This action cannot be undone. \n\n"
enum:
- active
- closed
- inactive
- suspended
type: string
statusReason:
x-addedInVersion: '2'
description: 'The reason for the status of the payment instrument.
Possible values: **accountClosure**, **damaged**, **endOfLife**, **expired**, **lost**, **stolen**, **suspectedFraud**, **transactionRule**, **other**.
If the reason is **other**, you must also send the `statusComment` parameter describing the status change.'
enum:
- accountClosure
- damaged
- endOfLife
- expired
- lost
- other
- stolen
- suspectedFraud
- transactionRule
type: string
type:
description: 'Type of payment instrument.
Possible value: **card**, **bankAccount**. '
enum:
- bankAccount
- card
type: string
required:
- balanceAccountId
- issuingCountryCode
- type
- id
type: object
DeliveryContact:
properties:
address:
description: The address of the contact.
$ref: '#/components/schemas/DeliveryAddress'
email:
description: The email address of the contact.
type: string
fullPhoneNumber:
description: 'The full phone number of the contact provided as a single string. It will be handled as a landline phone.
**Examples:** "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"'
type: string
name:
description: The name of the contact.
$ref: '#/components/schemas/Name'
phoneNumber:
description: The phone number of the contact.
$ref: '#/components/schemas/PhoneNumber'
webAddress:
description: The URL of the contact's website.
type: string
required:
- name
- address
type: object
PeriodUnit:
type: string
enum:
- Annual
- Daily
- Monthly
- Weekly
CardConfiguration:
properties:
activation:
description: Overrides the activation label design ID defined in the `configurationProfileId`. The activation label is attached to the card and contains the activation instructions.
type: string
activationUrl:
description: "Your app's URL, if you want to activate cards through your app. For example, **my-app://ref1236a7d**. A QR code is created based on this URL, and is included in the carrier. Before you use this field, reach out to your Adyen contact to set up the QR code process. \n\nMaximum length: 255 characters."
maxLength: 255
type: string
bulkAddress:
description: Overrides the shipment bulk address defined in the `configurationProfileId`.
$ref: '#/components/schemas/BulkAddress'
cardImageId:
description: The ID of the card image. This is the image that will be printed on the full front of the card.
type: string
carrier:
description: Overrides the carrier design ID defined in the `configurationProfileId`. The carrier is the letter or packaging to which the card is attached.
type: string
carrierImageId:
description: The ID of the carrier image. This is the image that will printed on the letter to which the card is attached.
type: string
configurationProfileId:
description: 'The ID of the card configuration profile that contains the settings of the card. For example, the envelope and PIN mailer designs or the logistics company handling the shipment. All the settings in the profile are applied to the card, unless you provide other fields to override them.
For example, send the `shipmentMethod` to override the logistics company defined in the card configuration profile.'
type: string
currency:
description: The three-letter [ISO-4217](https://en.wikipedia.org/wiki/ISO_4217) currency code of the card. For example, **EUR**.
type: string
envelope:
description: 'Overrides the envelope design ID defined in the `configurationProfileId`. '
type: string
insert:
description: Overrides the insert design ID defined in the `configurationProfileId`. An insert is any additional material, such as marketing materials, that are shipped together with the card.
type: string
language:
description: The two-letter [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code of the card. For example, **en**.
type: string
logoImageId:
description: The ID of the logo image. This is the image that will be printed on the partial front of the card, such as a logo on the upper right corner.
type: string
pinMailer:
description: Overrides the PIN mailer design ID defined in the `configurationProfileId`. The PIN mailer is the letter on which the PIN is printed.
type: string
shipmentMethod:
description: Overrides the logistics company defined in the `configurationProfileId`.
type: string
required:
- configurationProfileId
type: object
PaginatedPaymentInstrumentsResponse:
properties:
hasNext:
description: Indicates whether there are more items on the next page.
type: boolean
hasPrevious:
description: Indicates whether there are more items on the previous page.
type: boolean
paymentInstruments:
description: List of payment instruments associated with the balance account.
items:
$ref: '#/components/schemas/PaymentInstrument'
type: array
required:
- paymentInstruments
- hasPrevious
- hasNext
type: object
CustomerOrder:
type: object
description: Customer order attached to a customer, recorded in the POI system. Allows the management of customer orders by the POI, for instance in a multi-channel or a click and collect sale transaction.
properties:
CustomerOrderID:
type: string
pattern: ^.+$
description: Additional and optional identification of a customer order.
SaleReferenceID:
type: string
pattern: ^.+$
OpenOrderState:
type: boolean
default: true
StartDate:
type: string
format: date-time
description: Date time of the beginning of an operation.
EndDate:
type: string
format: date-time
description: Date time of the end of an operation.
ForecastedAmount:
type: number
maximum: 99999999.999999
minimum: 0
CurrentAmount:
type: number
maximum: 99999999.999999
minimum: 0
description: Total amount of all completed transactions of a customer order.
Currency:
type: string
pattern: ^[A-Z]{3,3}$
description: Currency of a monetary amount.
AccessedBy:
type: string
pattern: ^.+$
AdditionalInformation:
type: string
pattern: ^.+$
description: Unqualified information.
required:
- SaleReferenceID
- StartDate
- ForecastedAmount
- CurrentAmount
ForceEntryMode:
type: array
items:
type: string
enum:
- CheckReader
- Contactless
- File
- ICC
- Keyed
- MagStripe
- Manual
- RFID
- Scanned
- SynchronousICC
- Tapped
TrackData:
type: object
description: ISO 7813 - ISO 4909. Generic data structure for a card track, used when the magstripe card reader is located on the Sale Terminal, or for magstripe Card Reader device request. The data structure is also used to store the line at the bottom of a bank check. Magnetic track or magnetic ink characters line.
properties:
TrackNumb:
type: integer
minimum: 1
maximum: 3
default: 2
TrackFormat:
$ref: '#/components/schemas/TrackFormat'
TrackValue:
type: string
pattern: ^.{1,104}$
required:
- TrackValue
OutputText:
type: object
description: It conveys Information related to the content of the text message and its format. All the data elements related to the format of the text to display or print are parameters valid for the whole Text content. Content of text message to display or print.
properties:
Text:
type: string
CharacterSet:
type: integer
Font:
type: string
pattern: ^.+$
StartRow:
type: integer
minimum: 1
maximum: 500
StartColumn:
type: integer
minimum: 1
maximum: 500
Color:
$ref: '#/components/schemas/Color'
CharacterWidth:
$ref: '#/components/schemas/CharacterWidth'
CharacterHeight:
$ref: '#/components/schemas/CharacterHeight'
CharacterStyle:
$ref: '#/components/schemas/CharacterStyle'
Alignment:
$ref: '#/components/schemas/Alignment'
EndOfLineFlag:
type: boolean
default: true
required:
- Text
PaymentInstrumentType:
type: string
enum:
- Card
- Cash
- Check
- Mobile
- StoredValue
TokenRequestedType:
type: string
enum:
- Customer
- Transaction
InstalmentType:
type: string
enum:
- DeferredInstalments
- EqualInstalments
- InequalInstalments
AuthenticationMethod:
type: array
items:
type: string
enum:
- Bypass
- ManualVerification
- MerchantAuthentication
- OfflinePIN
- OnlinePIN
- PaperSignature
- SecureCertificate
- SecureNoCertificate
- SecuredChannel
- SignatureCapture
- UnknownMethod
Card:
properties:
authentication:
description: Contains the card user's password and mobile phone number. This is required when you issue cards that can be used to make online payments within the EEA and the UK, or can be added to digital wallets. Refer to [3D Secure and digital wallets](https://docs.adyen.com/issuing/3d-secure-and-wallets) for more information.
$ref: '#/components/schemas/Authentication'
bin:
description: The bank identification number (BIN) of the card number.
type: string
brand:
description: 'The brand of the physical or the virtual card.
Possible values: **visa**, **mc**.'
type: string
brandVariant:
description: 'The brand variant of the physical or the virtual card. For example, **visadebit** or **mcprepaid**.
>Reach out to your Adyen contact to get the values relevant for your integration.'
type: string
cardholderName:
description: "The name of the cardholder.\n Maximum length: 26 characters."
maxLength: 26
type: string
configuration:
description: "Settings required when creating a physical or a virtual card. \n\nReach out to your Adyen contact to get the values that you can send in this object."
$ref: '#/components/schemas/CardConfiguration'
cvc:
description: 'The CVC2 value of the card.
> The CVC2 is not sent by default. This is only returned in the `POST` response for single-use virtual cards.'
type: string
deliveryContact:
x-addedInVersion: '2'
description: The delivery contact (name and address) for physical card delivery.
$ref: '#/components/schemas/DeliveryContact'
expiration:
description: The expiration date of the card.
$ref: '#/components/schemas/Expiry'
formFactor:
description: 'The form factor of the card.
Possible values: **virtual**, **physical**.'
enum:
- physical
- unknown
- virtual
type: string
lastFour:
description: Last last four digits of the card number.
type: string
number:
description: 'The primary account number (PAN) of the card.
> The PAN is masked by default and returned only for single-use virtual cards.'
readOnly: true
type: string
threeDSecure:
description: 'Allocates a specific product range for either a physical or a virtual card. Possible values: **fullySupported**, **secureCorporate**.
>Reach out to your Adyen contact to get the values relevant for your integration.'
type: string
required:
- formFactor
- cardholderName
- brand
- brandVariant
- number
type: object
USLocalAccountIdentification:
additionalProperties: false
properties:
accountNumber:
description: The bank account number, without separators or whitespace.
maxLength: 18
minLength: 2
type: string
accountType:
default: checking
description: 'The bank account type.
Possible values: **checking** or **savings**. Defaults to **checking**.'
enum:
- checking
- savings
type: string
routingNumber:
description: The 9-digit [routing number](https://en.wikipedia.org/wiki/ABA_routing_transit_number), without separators or whitespace.
maxLength: 9
minLength: 9
type: string
type:
default: usLocal
description: '**usLocal**'
enum:
- usLocal
type: string
required:
- type
- accountNumber
- routingNumber
type: object
AreaSize:
type: object
properties:
X:
type: string
Y:
type: string
required:
- X
- Y
SaleToIssuerData:
type: object
description: The POI System receives this information and sends it to the Acquirer for the Issuer without any change. Sale information intended for the Issuer.
properties:
StatementReference:
type: string
pattern: ^.+$
description: Information to print on the bank statement.
LoyaltyAccount:
type: object
description: This data structure conveys the identification of the account and the associated loyalty brand. Data related to a loyalty account processed in the transaction.
properties:
LoyaltyAccountID:
$ref: '#/components/schemas/LoyaltyAccountID'
LoyaltyBrand:
type: string
pattern: ^.+$
description: If a card is analysed.
required:
- LoyaltyAccountID
Expiry:
properties:
month:
description: The month in which the card will expire.
type: string
year:
description: The year in which the card will expire.
type: string
type: object
PaymentAcquirerData:
type: object
description: Data related to the response from the payment Acquirer.
properties:
AcquirerID:
type: integer
description: If several Acquirers.
MerchantID:
type: string
pattern: ^.+$
description: Identification of the Merchant for the Acquirer.
AcquirerPOIID:
type: string
pattern: ^.+$
description: Identification of the POI for the payment Acquirer.
AcquirerTransactionID:
$ref: '#/components/schemas/TransactionIDType'
ApprovalCode:
type: string
pattern: ^.+$
description: If available.
HostReconciliationID:
type: string
pattern: ^.+$
required:
- MerchantID
- AcquirerPOIID
Point:
type: object
properties:
X:
type: string
Y:
type: string
required:
- X
- Y
BulkAddress:
properties:
city:
description: The name of the city.
type: string
company:
description: The name of the company.
type: string
country:
description: The two-character ISO-3166-1 alpha-2 country code. For example, **US**.
type: string
email:
description: The email address.
type: string
houseNumberOrName:
description: The house number or name.
type: string
mobile:
description: The full telephone number.
type: string
postalCode:
description: 'The postal code.
Maximum length:
* 5 digits for addresses in the US.
* 10 characters for all other countries.'
type: string
stateOrProvince:
description: 'The two-letter ISO 3166-2 state or province code.
Maximum length: 2 characters for addresses in the US.'
type: string
street:
description: The streetname of the house.
type: string
required:
- country
type: object
ErrorCondition:
type: string
enum:
- Aborted
- Busy
- Cancel
- DeviceOut
- InProgress
- InsertedCard
- InvalidCard
- LoggedOut
- MessageFormat
- NotAllowed
- NotFound
- PaymentRestriction
- Refusal
- UnavailableDevice
- UnavailableService
- UnreachableHost
- WrongPIN
Rebates:
type: object
properties:
TotalRebate:
type: number
maximum: 99999999.999999
minimum: 0
RebateLabel:
type: string
pattern: ^.+$
SaleItemRebate:
type: array
items:
$ref: '#/components/schemas/SaleItemRebate'
TransactionIDType:
type: object
description: Identification of a transaction for the Sale System or the POI System.
properties:
TransactionID:
type: string
pattern: ^.+$
TimeStamp:
type: string
format: date-time
required:
- TransactionID
- TimeStamp
Result:
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/adyen/refs/heads/main/openapi/adyen-payment-api-openapi.yml