From 289fdc011d821f55f83a7bd4af3a114aa24a03aa Mon Sep 17 00:00:00 2001 From: Aleksei Akimov Date: Thu, 17 May 2018 11:21:12 +0200 Subject: [PATCH] Specifications for Payout and MarketPay services --- specs/3.0/AccountService-v3.yaml | 2079 ++++++++++++++++ specs/3.0/AccountService-v4.yaml | 2172 +++++++++++++++++ specs/3.0/FundService-v3.yaml | 763 ++++++ .../NotificationConfigurationService-v1.yaml | 416 ++++ specs/3.0/PayoutService-v30.yaml | 1201 +++++++++ 5 files changed, 6631 insertions(+) create mode 100644 specs/3.0/AccountService-v3.yaml create mode 100644 specs/3.0/AccountService-v4.yaml create mode 100644 specs/3.0/FundService-v3.yaml create mode 100644 specs/3.0/NotificationConfigurationService-v1.yaml create mode 100644 specs/3.0/PayoutService-v30.yaml diff --git a/specs/3.0/AccountService-v3.yaml b/specs/3.0/AccountService-v3.yaml new file mode 100644 index 0000000..f071a27 --- /dev/null +++ b/specs/3.0/AccountService-v3.yaml @@ -0,0 +1,2079 @@ +openapi: 3.0.0 +servers: + - url: 'https://cal-test.adyen.com/cal/services/Account/v3' +info: + version: '3' + title: Adyen MarketPay Account Service + description: |- + The MarketPay Account API provides endpoints for managing MarketPay account-related entities. These related entities include account holders, accounts, bank accounts, shareholders, and KYC-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them. + + For further information on MarketPay API, visit the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + ## Authentication + To connect to the MarketPay API, you must use basic authentication credentials of your web service user. If you don't have one, please contact the [Adyen Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials to authenticate your request, for example: + + ``` + curl + -U "ws@Company.YourCompany":"YourWsPassword" \ + -H "Content-Type: application/json" \ + ... + ``` + Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/developers/api-reference/live-endpoints). + + ## Versioning + MarketPay API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number. + + For example: + ``` + https://cal-test.adyen.com/cal/services/Account/v3/createAccountHolder + ``` + termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com +x-groups: + - Account holders + - Accounts + - Verification +paths: + /closeAccount: + post: + summary: Close an existing account under an account holder. + description: 'This endpoint is used to close an existing account under an account holder. If an account is closed, it may not process transactions or have its funds paid out,and it may not be reopened. Any payments made to a closed account will be directed to the merchant''s liable account.' + x-groupName: Accounts + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /closeAccountHolder: + post: + summary: Close an existing account holder. + description: 'This endpoint is used to close an existing account holder and its accounts. If an account holder is closed, it may not process transactions or pay out funds, and it may not be reopened. Any payments made to a closed account will be directed to the merchant''s liable account.' + x-groupName: Account holders + x-sortIndex: 7 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /createAccount: + post: + summary: Create a new account under an existing account holder. + description: This endpoint is used to create an account under an existing account holder. An account holder may have multiple accounts. + x-groupName: Accounts + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account. + description: This notification is sent when an Account has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /createAccountHolder: + post: + summary: Create a new account holder. + description: 'This endpoint is used to create an account holder. Each account holder represents a single sub-merchant, and each sub-merchant must be represented by an account holder. Depending on the legal entity type, different details are required to be provided in the call to this endpoint.' + x-groupName: Account holders + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account. + description: This notification is sent when an Account has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + accountHolderVerification: + notificationURL: + post: + summary: Triggered upon the receipt of KYC Verification results. + description: This notification is sent when KYC Verification results are made available. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderVerificationNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + accountHolderCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account Holder. + description: This notification is sent when an Account Holder has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /deleteBankAccounts: + post: + summary: Delete bank accounts of an existing account holder. + description: This endpoint is used to delete existing bank accounts from an account holder. + x-groupName: Verification + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteBankAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GenericResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /deleteShareholders: + post: + summary: Delete shareholders of an existing account holder. + description: This endpoint is used to delete existing shareholders from an account holder. + x-groupName: Verification + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteShareholderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GenericResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /getAccountHolder: + post: + summary: Retrieve the details of an account holder. + description: This endpoint is used to retrieve the details of an account holder. + x-groupName: Account holders + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /getUploadedDocuments: + post: + summary: Retrieve the uploaded documents of an existing account holder. + description: |- + This endpoint is used to retrieve documents previously uploaded for use in the KYC Verification of an account holder. + + For further information regarding KYC Verification, please refer to the [KYC Documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + x-groupName: Verification + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadedDocumentsRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadedDocumentsResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /suspendAccountHolder: + post: + summary: Suspend an existing account holder. + description: 'This endpoint is used to suspend an existing account holder. If an account holder is suspended, it may not process transactions or pay out funds. Any payments made to a suspended account holder will be directed to the merchant''s liable account.' + x-groupName: Account holders + x-sortIndex: 5 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SuspendAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SuspendAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /unSuspendAccountHolder: + post: + summary: Reinstate a disabled account holder. + description: 'This endpoint is used to reinstate an existing account holder, which has been suspended through the `/suspendAccountHolder` endpoint. An account holder which has been suspended due to KYC verification issues cannot be reinstated through this endpoint.' + x-groupName: Account holders + x-sortIndex: 6 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UnSuspendAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UnSuspendAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /updateAccount: + post: + summary: Update an existing account under an account holder. + description: This endpoint is used to update the description or payout schedule of an existing account. + x-groupName: Accounts + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /updateAccountHolder: + post: + summary: Update an existing account holder. + description: |- + This endpoint is used to update the `accountHolderDetails` or `processingTier` of an account holder. + + If updating the `accountHolderDetails`, only the details which have been provided will be updated. Other details will be left as-is with the exception of the following fields: + * `accountHolderDetails.address` + * `accountHolderDetails.phoneNumber` + * `accountHolderDetails.bankAccountDetails.BankAccountDetail` + * `accountHolderDetails.businessDetails.shareholders.ShareholderContact`, which requires all fields necessary for validation (i.e. in order to update only the `accountHolderDetails.address.postalCode`, the fields `accountHolderDetails.address.country`, `.city`, `.street`, `.postalCode`, and possibly `.stateOrProvince` must be provided as well, so that the address can be properly validated). + + Note that this endpoint can also be used to create new bank accounts. For this, provide details of a bank account without providing a `bankAccountUUID`. + + Similarly, it can also be used to create new shareholders by providing details of a shareholder without providing a `shareholderCode`. + > The updating of the `metadata` field will overwite all of the existing account holder metadata. In order to update an existing metadata key-value pair, all otherkey-value pairs should be provided in order to not delete them. + x-groupName: Account holders + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountHolderUpdated: + notificationURL: + post: + summary: Triggered upon the update of an Account Holder. + description: This notification is sent when an Account Holder has been updated. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderUpdateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /updateAccountHolderState: + post: + summary: Update the state of an existing account holder. + description: |- + This endpoint is used to disable or enable the processing or payout state of an account holder. It cannot be used to enable an account holder whose processing or payout state has not been disabled through this endpoint. + + For further information regarding processing and payout states of an account holder, please refer to the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + x-groupName: Account holders + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderStateRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderStatusResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountHolderStatusChange: + notificationURL: + post: + summary: Triggered upon the status change of an Account Holder. + description: This notification is sent when the status of an Account Holder has been changed. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderStatusChangeNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /uploadDocument: + post: + summary: Upload a document for an existing account holder. + description: |- + This endpoint is used to upload a document for use in the KYC verification of an account holder. + + For further information regarding KYC Verification, please refer to the [KYC Documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + x-groupName: Verification + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UploadDocumentRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. +components: + schemas: + Account: + properties: + accountCode: + description: The code of the account. + type: string + beneficiaryAccount: + description: The beneficiary of the account. + type: string + beneficiaryMerchantReference: + description: The reason that a beneficiary has been set up for this account. This may have been supplied during the setup of a beneficiary at the discretion of the executing user. + type: string + payoutSchedule: + description: The account's payout schedule. + $ref: '#/components/schemas/PayoutScheduleResponse' + AccountCreateNotification: + properties: + content: + description: The details of the account creation. + $ref: '#/components/schemas/CreateAccountResponse' + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - content + AccountEvent: + properties: + event: + description: |- + The event. + >Permitted values: `InactivateAccount`, `RefundNotPaidOutTransfers`. + Please refer to the KYC documentation for further information. + enum: + - InactivateAccount + - RefundNotPaidOutTransfers + type: string + executionDate: + description: The date on which the event will take place. + format: date-time + type: string + reason: + description: The reason why this event has been created. + type: string + required: + - event + - executionDate + - reason + AccountHolderCreateNotification: + properties: + content: + description: The details of the account holder creation. + $ref: '#/components/schemas/CreateAccountHolderResponse' + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - content + AccountHolderDetails: + properties: + address: + description: The address of the account holder. + $ref: '#/components/schemas/Address' + bankAccountDetails: + description: |- + Each of the the bank accounts associated with the account holder. + > Each array entry should represent one bank account. + > For comprehensive detail regarding the required `BankAccountDetail` fields, please refer to the [KYC Verification documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + items: + $ref: '#/components/schemas/BankAccountDetail' + type: array + businessDetails: + description: |- + Details applicable to `Business` legal entities. + Populated only if the account holder's legal entity is of type `Business`. + > Required when being used in a `/createAccountHolder` request in which the legal entity is `Business`. + $ref: '#/components/schemas/BusinessDetails' + email: + description: The email address of the account holder. + type: string + fullPhoneNumber: + description: |- + The phone number of the account holder 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 + individualDetails: + description: |- + Details applicable to `Individual` legal entities. + Populated only if the account holder's legal entity is of type `Individual`. + > Required when being used in a `/createAccountHolder` request in which the legal entity is `Individual`. + $ref: '#/components/schemas/IndividualDetails' + merchantCategoryCode: + description: |- + The Merchant Category Code of the account holder. + > If not specified in the request, this will be derived from the marketplace account (which is configured by Adyen). + type: string + metadata: + additionalProperties: + type: string + description: |- + A set of key and value pairs for general use by the account holder or merchant. + The keys do not have specific names and may be used for storing miscellaneous data as desired. + > The values being stored have a maximum length of eighty (80) characters and will be truncated if necessary. + > Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs. + type: object + webAddress: + description: The URL of the website of the account holder. + type: string + required: + - fullPhoneNumber + - email + AccountHolderStatus: + properties: + accountEvents: + description: A list of events scheduled for the account holder. + items: + $ref: '#/components/schemas/AccountEvent' + type: array + payoutState: + description: The payout state of the account holder. + $ref: '#/components/schemas/AccountPayoutState' + processingState: + description: The processing state of the account holder. + $ref: '#/components/schemas/AccountProcessingState' + status: + description: |- + The status of the account holder. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + statusReason: + description: The reason why the status was assigned to the account holder. + type: string + required: + - status + - statusReason + - processingState + - payoutState + - accountEvents + AccountHolderStatusChangeNotification: + properties: + content: + description: The details of the Account Holder status change. + $ref: '#/components/schemas/AccountHolderStatusChangeNotificationContent' + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + AccountHolderStatusChangeNotificationContent: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + newAccountHolderStatus: + description: The new status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + oldAccountHolderStatus: + description: The former status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + reason: + description: The reason for the status change. + type: string + required: + - accountHolderCode + - oldAccountHolderStatus + - newAccountHolderStatus + - reason + AccountHolderUpdateNotification: + properties: + content: + description: The details of the Account Holder update. + $ref: '#/components/schemas/UpdateAccountHolderResponse' + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - content + AccountHolderVerificationNotification: + properties: + content: + description: The details of the Account Holder verification. + $ref: '#/components/schemas/AccountHolderVerificationNotificationContent' + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - content + AccountHolderVerificationNotificationContent: + properties: + accountHolderCode: + description: The code of the Account Holder. + type: string + bankAccountUUID: + description: The unique ID of the bank account that has been verified. + type: string + shareholderCode: + description: The code of the shareholder that has been verified. + type: string + verificationStatus: + description: The status of verification. + enum: + - AWAITING_DATA + - DATA_PROVIDED + - FAILED + - INVALID_DATA + - PASSED + - PENDING + - PENDING_REVIEW + - RETRY_LIMIT_REACHED + - UNCHECKED + type: string + verificationType: + description: The type of validation performed. + enum: + - BANK_ACCOUNT_VERIFICATION + - COMPANY_VERIFICATION + - IDENTITY_VERIFICATION + - NONPROFIT_VERIFICATION + - PASSPORT_VERIFICATION + type: string + required: + - accountHolderCode + AccountPayoutState: + properties: + allowPayout: + description: Indicates whether payouts are allowed. + type: boolean + disableReason: + description: The reason why payouts have been disabled (by the marketplace). + type: string + disabled: + description: Indicates whether payouts have been disabled (by the marketplace) for all of the Account Holder's accounts. + type: boolean + payoutLimit: + description: The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited. + $ref: '#/components/schemas/Amount' + tierNumber: + description: |- + The payout tier that the Account Holder occupies. + >Please refer to the KYC Verification documentation for further detail on payout tiers. + format: int32 + type: integer + required: + - allowPayout + - disabled + - tierNumber + - disableReason + - payoutLimit + AccountProcessingState: + properties: + disableReason: + description: The reason why processing has been disabled. + type: string + disabled: + description: Indicates whether the processing of payments is allowed. + type: boolean + processedFrom: + description: |- + The lower bound of the processing tier (i.e., an Account Holder must have processed at least this amount of money in order to be placed into this tier). + >Please refer to the KYC Verification documentation for further detail on processing tiers. + $ref: '#/components/schemas/Amount' + processedTo: + description: |- + The upper bound of the processing tier (i.e., an Account Holder must have processed less than this amount of money in order to be placed into this tier). + >Please refer to the KYC Verification documentation for further detail on processing tiers. + $ref: '#/components/schemas/Amount' + tierNumber: + description: |- + The processing tier that the Account Holder occupies. + >Please refer to the KYC Verification documentation for further detail on processing tiers. + format: int32 + type: integer + required: + - disabled + - disableReason + - processedFrom + - processedTo + - tierNumber + Address: + properties: + city: + description: |- + The name of the city. + >Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided. + type: string + country: + description: |- + The two-character country code of the address + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + type: string + houseNumberOrName: + description: The number or name of the house. + type: string + postalCode: + 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: |- + The abbreviation of the state or province. + >Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries. + >Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided. + type: string + street: + description: |- + The name of the street. + >The house number should not be included in this field; it should be separately provided via `houseNumberOrName`. + >Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided. + type: string + required: + - country + Amount: + properties: + currency: + description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).' + maxLength: 3 + minLength: 3 + type: string + value: + 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). + format: int64 + type: integer + required: + - value + - currency + BankAccountDetail: + properties: + accountNumber: + description: |- + The bank account number (without separators). + >Please refer to the KYC Verification section for details on field requirements. + type: string + accountType: + description: |- + The type of bank account. + Only applicable to bank accounts held in the USA. + The permitted values are: `checking`, `savings`. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankAccountName: + description: The name of the bank account. + type: string + bankAccountUUID: + description: | + The unique identifier (UUID) of the Bank Account. + >**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Bank Account will be created with a procedurally-generated UUID.** + + >**If, during an Account Holder create request, a UUID is provided, the creation of the Bank Account will fail while the creation of the Account Holder will continue.** + + >**If, during an Account Holder update request, a UUID that is not correlated with an existing Bank Account is provided, the update of the Account Holder will fail.** + + >**If, during an Account Holder update request, a UUID that is correlated with an existing Bank Account is provided, the existing Bank Account will be updated.** + type: string + bankBicSwift: + description: |- + The bank identifier code. + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCity: + description: |- + The city in which the bank branch is located. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCode: + description: |- + The bank code of the banking institution with which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankName: + description: |- + The name of the banking institution with which the bank account is held. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + branchCode: + description: |- + The branch code of the branch under which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + checkCode: + description: |- + The check code of the bank account. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + countryCode: + description: |- + The two-letter country code in which the bank account is registered. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + currencyCode: + description: |- + The currency in which the bank account deals. + >The permitted currency codes are defined in ISO-4217 (e.g. 'EUR'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + iban: + description: |- + The international bank account number. + >The IBAN standard is defined in ISO-13616. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCity: + description: |- + The city of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCountryCode: + description: |- + The country code of the country of residence of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerDateOfBirth: + description: | + The date of birth of the bank account owner. + type: string + ownerHouseNumberOrName: + description: |- + The house name or number of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerName: + description: |- + The name of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerNationality: + description: |- + The country code of the country of nationality of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerPostalCode: + description: |- + The postal code of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerState: + description: |- + The state of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerStreet: + description: |- + The street name of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + primaryAccount: + description: 'If set to true, the bank account is a primary account.' + type: boolean + taxId: + description: |- + The tax ID number. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + urlForVerification: + description: |- + The URL to be used for bank account verification. + This may be generated on bank account creation. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + BusinessDetails: + properties: + doingBusinessAs: + description: The registered name of the company (if it differs from the legal name of the company). + type: string + legalBusinessName: + description: The legal name of the company. + type: string + shareholders: + description: |- + Each of the shareholders associated with the company. + Each array entry should represent one shareholder. + items: + $ref: '#/components/schemas/ShareholderContact' + type: array + taxId: + description: The tax ID of the company. + type: string + CloseAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be closed. + type: string + required: + - accountHolderCode + CloseAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + CloseAccountRequest: + properties: + accountCode: + description: The code of account to be closed. + type: string + required: + - accountCode + CloseAccountResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + status: + description: |- + The new status of the account. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - status + CreateAccountHolderRequest: + properties: + accountHolderCode: + description: |- + The desired code of the prospective account holder. + > Must be between three (3) and fifty (50) characters long. Only letters, digits, and hyphens (-) are permitted. + type: string + accountHolderDetails: + description: The details of the prospective account holder. + $ref: '#/components/schemas/AccountHolderDetails' + createDefaultAccount: + description: |- + If set to true, an account with the default options is created for this account holder. + **Default Value:** true + type: boolean + legalEntity: + description: |- + The entity type. + Permitted values: `Business`, `Individual` + + If an account holder is 'Business', then `accountHolderDetails.businessDetails` must be provided, as well as at least one entry in the `accountHolderDetails.businessDetails.shareholders` list. + + If an account holder is 'Individual', then `accountHolderDetails.individualDetails` must be provided. + enum: + - Business + - Individual + - NonProfit + type: string + processingTier: + description: 'The starting [processing tier](https://docs.adyen.com/developers/marketpay/kyc-verification/verification-process) for the prospective account holder.' + format: int32 + type: integer + required: + - accountHolderCode + - legalEntity + - accountHolderDetails + CreateAccountHolderResponse: + properties: + accountCode: + description: The code of a new account created for the account holder. + type: string + accountHolderCode: + description: The code of the new account holder. + type: string + accountHolderDetails: + description: Details of the new account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The status of the new account holder. + $ref: '#/components/schemas/AccountHolderStatus' + invalidFields: + description: A list of fields that caused the `/createAccountHolder` request to fail. + items: + $ref: '#/components/schemas/ErrorFieldType' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountHolderStatus + - accountHolderDetails + - verificationResult + CreateAccountRequest: + properties: + accountHolderCode: + description: The code of Account Holder under which to create the account. + type: string + payoutSchedule: + description: |- + The payout schedule of the prospective account. + >Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + payoutScheduleReason: + description: |- + The reason for the payout schedule choice. + >Required if the payoutSchedule is `HOLD`. + type: string + required: + - accountHolderCode + - payoutSchedule + - payoutScheduleReason + CreateAccountResponse: + properties: + accountCode: + description: The code of the new account. + type: string + accountHolderCode: + description: The code of the account holder. + type: string + payoutSchedule: + description: The payout schedule of the account. + $ref: '#/components/schemas/PayoutScheduleResponse' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + status: + description: |- + The status of the account. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountCode + - status + DeleteBankAccountRequest: + properties: + accountHolderCode: + description: The code of the Account Holder from which to delete the Bank Account(s). + type: string + bankAccountUUIDs: + description: The code(s) of the Bank Accounts to be deleted. + items: + type: string + type: array + required: + - accountHolderCode + - bankAccountUUIDs + DeleteShareholderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder from which to delete the Shareholders. + type: string + shareholderCodes: + description: The code(s) of the Shareholders to be deleted. + items: + type: string + type: array + required: + - accountHolderCode + - shareholderCodes + DocumentDetail: + properties: + accountHolderCode: + description: The code of Account Holder to which the document applies. + type: string + bankAccountUUID: + description: |- + The unique ID of the Bank Account to which the document applies. + >Required if the documentType is `BANK_STATEMENT` (i.e., a document is being submitted in order to verify a bank account). + + >Please refer to the KYC Verification section for details on when a document should be submitted in order to verify a bank account. + type: string + description: + description: Description of the document. + type: string + documentType: + description: |- + The type of document. + >Permitted values: `PASSPORT`, `ID_CARD`, `ID_CARD_FRONT`, ID_CARD_BACK`, `DRIVING_LICENSE`, `DRIVING_LICENCE_FRONT`, `DRIVING_LICENCE_BACK`, `BANK_STATEMENT`. + >* `ID_CARD` denotes an image containing both the front and back of the ID card. + >* `ID_CARD_FRONT` denotes an image containing only the front of the ID card. In order for a document to be usable, both the ID_CARD_FRONT and ID_CARD_BACK must be submitted. + >* `ID_CARD_BACK` denotes an image containing only the back of the ID card. In order for a document to be usable, both the ID_CARD_FRONT and ID_CARD_BACK must be submitted. + >* `DRIVING_LICENCE` denotes an image containing both the front and back of the driving licence. + >* `DRIVING_LICENCE_FRONT` denotes an image containing only the front of the driving licence. In order for a document to be usable, both the DRIVING_LICENCE_FRONT and DRIVING_LICENCE_BACK must be submitted. + >* `DRIVING_LICENCE_BACK` denotes an image containing only the back of the driving licence. In order for a document to be usable, both the DRIVING_LICENCE_FRONT and DRIVING_LICENCE_FRONT must be submitted. + + >Please refer to the KYC Verification section for details on when each document type should be submitted. + enum: + - BANK_STATEMENT + - BSN + - DRIVING_LICENCE + - DRIVING_LICENCE_BACK + - DRIVING_LICENCE_FRONT + - ID_CARD + - ID_CARD_BACK + - ID_CARD_FRONT + - NHIS + - PASSPORT + - SSN + type: string + filename: + description: Filename of the document. + type: string + shareholderCode: + description: |- + The code of the Shareholder to which the document applies. + >Required if the Account Holder referred to by the accountHolderCode has a legalEntity of type `Business` and the documentType is either `PASSPORT`, `ID_CARD`, ID_CARD_FRONT`, `ID_CARD_BACK`, `DRIVING_LICENCE`, `DRIVING_LICENCE_FRONT`, `DRIVING_LICENCE_BACK` (i.e. a document is being submitted in order to verify a shareholder). + + >Please refer to the KYC Verification section for details on when a document should be submitted in order to verify a shareholder. + type: string + required: + - accountHolderCode + - documentType + - filename + ErrorFieldType: + properties: + errorCode: + description: The validation error code. + format: int32 + type: integer + errorDescription: + description: A description of the validation error. + type: string + fieldType: + description: The type of error field. + $ref: '#/components/schemas/FieldType' + FieldType: + properties: + field: + description: The full name of the property. + type: string + fieldName: + description: The type of the field. + enum: + - accountHolderCode + - accountHolderDetails + - accountNumber + - accountType + - address + - bankAccount + - bankBicSwift + - bankCity + - bankCode + - bankName + - bankStatement + - branchCode + - businessContact + - checkCode + - city + - country + - countryCode + - currencyCode + - dateOfBirth + - description + - document + - drivingLicence + - drivingLicenceBack + - email + - firstName + - fullPhoneNumber + - gender + - houseNumberOrName + - iban + - idCard + - idCardBack + - idCardFront + - idNumber + - identityDocument + - lastName + - legalBusinessName + - merchantCategoryCode + - microDeposit + - name + - nationality + - ownerCity + - ownerCountryCode + - ownerHouseNumberOrName + - ownerName + - ownerPostalCode + - ownerState + - ownerStreet + - passport + - personalData + - phoneCountryCode + - phoneNumber + - postalCode + - registrationNumber + - shareholder + - stateOrProvince + - street + - taxId + - tierNumber + - unknown + - virtualAccount + - webAddress + type: string + shareholderCode: + description: 'The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.' + type: string + GenericResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + GetAccountHolderRequest: + properties: + accountCode: + description: |- + The code of the account of which to retrieve the details. + > Required if no `accountHolderCode` is provided. + type: string + accountHolderCode: + description: |- + The code of the account holder of which to retrieve the details. + > Required if no `accountCode` is provided. + type: string + GetAccountHolderResponse: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + accountHolderDetails: + description: Details of the account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + accounts: + description: A list of the accounts under the account holder. + items: + $ref: '#/components/schemas/Account' + type: array + legalEntity: + description: The legal entity of the account holder. + enum: + - Business + - Individual + - NonProfit + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderCode + - legalEntity + - accountHolderStatus + - accountHolderDetails + - verificationResult + GetAccountHolderStatusResponse: + properties: + accountHolderCode: + description: The code of the Account Holder. + type: string + accountHolderStatus: + description: The status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountHolderStatus + GetUploadedDocumentsRequest: + properties: + accountHolderCode: + description: The code of the Account Holder for which to retrieve the documents. + type: string + bankAccountUUID: + description: The code of the Bank Account for which to retrieve the documents. + type: string + shareholderCode: + description: The code of the Shareholder for which to retrieve the documents. + type: string + required: + - accountHolderCode + GetUploadedDocumentsResponse: + properties: + documentDetails: + description: A list of the documents and their details. + items: + $ref: '#/components/schemas/DocumentDetail' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + IndividualDetails: + properties: + name: + description: The name of the individual. + $ref: '#/components/schemas/Name' + personalData: + description: Personal information of the individual. + $ref: '#/components/schemas/PersonalData' + KYCBankAccountCheckResult: + properties: + bankAccountUUID: + description: The unique ID of the bank account to which the check applies. + type: string + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + required: + - checkStatusData + - bankAccountUUID + KYCCheckResult: + properties: + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + required: + - checkStatusData + KYCCheckStatusData: + properties: + checkStatus: + description: |- + The status of the check. + >Permitted Values: `UNCHECKED`, `DATA_PROVIDED`, `PASSED`, `PENDING`, `AWAITING_DATA`, `RETRY_LIMIT_REACHED`, `INVALID_DATA`, `FAILED`. + enum: + - AWAITING_DATA + - DATA_PROVIDED + - FAILED + - INVALID_DATA + - PASSED + - PENDING + - PENDING_REVIEW + - RETRY_LIMIT_REACHED + - UNCHECKED + type: string + checkType: + description: |- + The type of check. + >Permitted Values: `COMPANY_VERIFICATION`, `IDENTITY_VERIFICATION`, `PASSPORT_VERIFICATION`, `BANK_ACCOUNT_VERIFICATION`, `NONPROFIT_VERIFICATION`. + enum: + - BANK_ACCOUNT_VERIFICATION + - COMPANY_VERIFICATION + - IDENTITY_VERIFICATION + - NONPROFIT_VERIFICATION + - PASSPORT_VERIFICATION + type: string + requiredFields: + description: A list of the fields required for execution of the check. + items: + type: string + type: array + summary: + description: A summary of the execution of the check. + $ref: '#/components/schemas/KYCCheckSummary' + required: + - checkType + - checkStatus + - summary + - requiredFields + KYCCheckSummary: + properties: + code: + description: The code of the check. + format: int32 + type: integer + description: + description: A description of the check. + type: string + required: + - code + KYCShareholderCheckResult: + properties: + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + shareholderCode: + description: The code of the shareholder to which the check applies. + type: string + required: + - checkStatusData + - shareholderCode + KYCVerificationResult: + properties: + accountHolderCheckResult: + description: The result(s) of the checks on the account holder. + $ref: '#/components/schemas/KYCCheckResult' + bankAccountCheckResult: + description: The result(s) of the checks on the bank account(s). + items: + $ref: '#/components/schemas/KYCBankAccountCheckResult' + type: array + shareholderCheckResult: + description: The result(s) of the checks on the shareholder(s). + items: + $ref: '#/components/schemas/KYCShareholderCheckResult' + type: array + required: + - accountHolderCheckResult + - shareholderCheckResult + - bankAccountCheckResult + Name: + properties: + firstName: + description: The first name. + type: string + gender: + description: |- + The gender. + >The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`. + enum: + - MALE + - FEMALE + - UNKNOWN + maxLength: 1 + minLength: 1 + type: string + infix: + description: |- + The name's infix, if applicable. + >A maximum length of twenty (20) characters is imposed. + type: string + lastName: + description: The last name. + type: string + required: + - firstName + - lastName + - gender + PayoutScheduleResponse: + properties: + nextScheduledPayout: + description: The date of the next scheduled payout. + format: date-time + type: string + schedule: + description: |- + The payout schedule of the account. + >Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + required: + - schedule + - nextScheduledPayout + PersonalData: + properties: + dateOfBirth: + description: |- + The date of birth of the person. + The date should be in ISO-8601 format yyyy-mm-dd (e.g. 2000-01-31). + type: string + idNumber: + description: An ID number of the person. + type: string + nationality: + description: |- + The nationality of the person represented by a two-character country code. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + maxLength: 2 + minLength: 2 + type: string + PhoneNumber: + properties: + phoneCountryCode: + description: |- + The two-character country code of the phone number. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + type: string + phoneNumber: + description: |- + The phone number. + >The inclusion of the phone number country code is not necessary. + type: string + phoneType: + description: |- + The type of the phone number. + >The following values are permitted: `Landline`, `Mobile`, `SIP`, `Fax`. + enum: + - Fax + - Landline + - Mobile + - SIP + type: string + required: + - phoneCountryCode + - phoneNumber + ShareholderContact: + properties: + address: + description: The address of the contact. + $ref: '#/components/schemas/Address' + email: + description: The e-mail address of the contact. + type: string + fullPhoneNumber: + description: |- + The 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' + personalData: + description: Personal data of the contact. + $ref: '#/components/schemas/PersonalData' + phoneNumber: + description: The phone number of the contact. + $ref: '#/components/schemas/PhoneNumber' + shareholderCode: + description: | + The unique identifier (UUID) of the Shareholder. + >**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Shareholder will be created with a procedurally-generated UUID.** + + >**If, during an Account Holder create request, a UUID is provided, the creation of the Shareholder will fail while the creation of the Account Holder will continue.** + + >**If, during an Account Holder update request, a UUID that is not correlated with an existing Shareholder is provided, the update of the Shareholder will fail.** + + >**If, during an Account Holder update request, a UUID that is correlated with an existing Shareholder is provided, the existing Bank Account will be updated.** + type: string + webAddress: + description: The URL of the website of the contact. + type: string + SuspendAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be suspended. + type: string + required: + - accountHolderCode + SuspendAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + UnSuspendAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be reinstated. + type: string + required: + - accountHolderCode + UnSuspendAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + UpdateAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be updated. + type: string + accountHolderDetails: + description: |- + The details to which the Account Holder should be updated. + + Required if a processingTier is not provided. + $ref: '#/components/schemas/AccountHolderDetails' + processingTier: + description: |- + The processing tier to which the Account Holder should be updated. + >The processing tier can not be lowered through this request. + + >Required if accountHolderDetails are not provided. + format: int32 + type: integer + required: + - accountHolderCode + UpdateAccountHolderResponse: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + accountHolderDetails: + description: Details of the account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The new status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + invalidFields: + description: 'in case the account holder has not been updated, contains account holder fields, that did not pass the validation.' + items: + $ref: '#/components/schemas/ErrorFieldType' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + updatedFields: + description: A list of the fields updated through the request. + items: + $ref: '#/components/schemas/FieldType' + type: array + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderStatus + - verificationResult + UpdateAccountHolderStateRequest: + properties: + accountHolderCode: + description: The code of the Account Holder on which to update the state. + type: string + disable: + description: 'If true, disable the requested state. If false, enable the requested state.' + type: boolean + reason: + description: |- + The reason that the state is being updated. + >Required if the state is being disabled. + type: string + stateType: + description: |- + The state to be updated. + >Permitted values are: `Processing`, `Payout` + enum: + - LimitedPayout + - LimitedProcessing + - LimitlessPayout + - LimitlessProcessing + - Payout + - Processing + type: string + required: + - accountHolderCode + - stateType + - disable + UpdateAccountRequest: + properties: + accountCode: + description: The code of the account to update. + type: string + payoutSchedule: + description: 'The details of the payout schedule, to which the account should be updated.' + $ref: '#/components/schemas/UpdatePayoutScheduleRequest' + required: + - accountCode + UpdateAccountResponse: + properties: + accountCode: + description: The code of the account. + type: string + payoutSchedule: + description: The payout schedule of the account. + $ref: '#/components/schemas/PayoutScheduleResponse' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountCode + - payoutSchedule + UpdatePayoutScheduleRequest: + properties: + action: + description: |- + Direction on how to handle any payouts that have already been scheduled. + >Permitted values: `CLOSE`, `UPDATE`, `NOTHING` (**default**). + >* `CLOSE` will close the existing batch of payouts. + >* `UPDATE` will reschedule the existing batch to the new schedule. + >* `NOTHING` will allow the payout to proceed. + enum: + - CLOSE + - NOTHING + - UPDATE + type: string + reason: + description: The reason for the payout schedule update. This field is required when the `schedule` parameter is set to **HOLD**. + type: string + schedule: + description: |- + The payout schedule to which the account is to be updated. + > Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + required: + - schedule + UploadDocumentRequest: + properties: + documentContent: + description: |- + The content of the document as represented by a Base64-encoded string. + + Restrictions: + * Maximum 2 pages. + * File size must be no less than 1000 bytes and no greater than 10 MB. + * File format must be either a jpeg, jpg, pdf, or png. + format: byte + type: string + documentDetail: + description: Details of the document being submitted. + $ref: '#/components/schemas/DocumentDetail' + required: + - documentDetail + - documentContent diff --git a/specs/3.0/AccountService-v4.yaml b/specs/3.0/AccountService-v4.yaml new file mode 100644 index 0000000..015f75c --- /dev/null +++ b/specs/3.0/AccountService-v4.yaml @@ -0,0 +1,2172 @@ +openapi: 3.0.0 +servers: + - url: 'https://cal-test.adyen.com/cal/services/Account/v4' +info: + version: '4' + title: Adyen MarketPay Account Service + description: |- + The MarketPay Account API provides endpoints for managing MarketPay account-related entities. These related entities include account holders, accounts, bank accounts, shareholders, and KYC-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them. + + For further information on MarketPay API, visit the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + ## Authentication + To connect to the MarketPay API, you must use basic authentication credentials of your web service user. If you don't have one, please contact the [Adyen Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials to authenticate your request, for example: + + ``` + curl + -U "ws@Company.YourCompany":"YourWsPassword" \ + -H "Content-Type: application/json" \ + ... + ``` + Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/developers/api-reference/live-endpoints). + + ## Versioning + MarketPay API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number. + + For example: + ``` + https://cal-test.adyen.com/cal/services/Account/v4/createAccountHolder + ``` + termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com +x-groups: + - Account holders + - Accounts + - Verification +paths: + /closeAccount: + post: + summary: Close an existing account under an account holder. + description: 'This endpoint is used to close an existing account under an account holder. If an account is closed, it may not process transactions or have its funds paid out,and it may not be reopened. Any payments made to a closed account will be directed to the merchant''s liable account.' + x-groupName: Accounts + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /closeAccountHolder: + post: + summary: Close an existing account holder. + description: 'This endpoint is used to close an existing account holder and its accounts. If an account holder is closed, it may not process transactions or pay out funds, and it may not be reopened. Any payments made to a closed account will be directed to the merchant''s liable account.' + x-groupName: Account holders + x-sortIndex: 7 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CloseAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /createAccount: + post: + summary: Create a new account under an existing account holder. + description: This endpoint is used to create an account under an existing account holder. An account holder may have multiple accounts. + x-groupName: Accounts + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account. + description: This notification is sent when an Account has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /createAccountHolder: + post: + summary: Create a new account holder. + description: 'This endpoint is used to create an account holder. Each account holder represents a single sub-merchant, and each sub-merchant must be represented by an account holder. Depending on the legal entity type, different details are required to be provided in the call to this endpoint.' + x-groupName: Account holders + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account. + description: This notification is sent when an Account has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + accountHolderVerification: + notificationURL: + post: + summary: Triggered upon the receipt of KYC Verification results. + description: This notification is sent when KYC Verification results are made available. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderVerificationNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + accountHolderCreated: + notificationURL: + post: + summary: Triggered upon the creation of an Account Holder. + description: This notification is sent when an Account Holder has been created. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderCreateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /deleteBankAccounts: + post: + summary: Delete bank accounts of an existing account holder. + description: 'This endpoint is used to delete existing bank accounts from an account holder. For this, pass the `accountHolderCode` you got on the account holder creation, and one or more `bankAccountUUIDs` specifying bank accounts to delete.' + x-groupName: Verification + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteBankAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GenericResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /deleteShareholders: + post: + summary: Delete shareholders of an existing account holder. + description: This endpoint is used to delete existing shareholders from an account holder. + x-groupName: Verification + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteShareholderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GenericResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /getAccountHolder: + post: + summary: Retrieve the details of an account holder. + description: This endpoint is used to retrieve the details of an account holder. + x-groupName: Account holders + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /getUploadedDocuments: + post: + summary: Retrieve the uploaded documents of an existing account holder. + description: |- + This endpoint is used to retrieve documents previously uploaded for use in the KYC Verification of an account holder. + + For further information regarding KYC Verification, please refer to the [KYC Documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + x-groupName: Verification + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadedDocumentsRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetUploadedDocumentsResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /suspendAccountHolder: + post: + summary: Suspend an existing account holder. + description: 'This endpoint is used to suspend an existing account holder. If an account holder is suspended, it may not process transactions or pay out funds. Any payments made to a suspended account holder will be directed to the merchant''s liable account.' + x-groupName: Account holders + x-sortIndex: 5 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SuspendAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SuspendAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /unSuspendAccountHolder: + post: + summary: Reinstate a disabled account holder. + description: 'This endpoint is used to reinstate an existing account holder, which has been suspended through the `/suspendAccountHolder` endpoint. An account holder which has been suspended due to KYC verification issues cannot be reinstated through this endpoint.' + x-groupName: Account holders + x-sortIndex: 6 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UnSuspendAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UnSuspendAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /updateAccount: + post: + summary: Update an existing account under an account holder. + description: This endpoint is used to update the description or payout schedule of an existing account. + x-groupName: Accounts + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /updateAccountHolder: + post: + summary: Update an existing account holder. + description: |- + This endpoint is used to update the `accountHolderDetails` or `processingTier` of an account holder. + + If updating the `accountHolderDetails`, only the details which have been provided will be updated. Other details will be left as-is with the exception of the following fields: + * `accountHolderDetails.address` + * `accountHolderDetails.phoneNumber` + * `accountHolderDetails.bankAccountDetails.BankAccountDetail` + * `accountHolderDetails.businessDetails.shareholders.ShareholderContact`, which requires all fields necessary for validation (i.e. in order to update only the `accountHolderDetails.address.postalCode`, the fields `accountHolderDetails.address.country`, `.city`, `.street`, `.postalCode`, and possibly `.stateOrProvince` must be provided as well, so that the address can be properly validated). + + Note that this endpoint can also be used to create new bank accounts. For this, provide details of a bank account without providing a `bankAccountUUID`. + + Similarly, it can also be used to create new shareholders by providing details of a shareholder without providing a `shareholderCode`. + > The updating of the `metadata` field will overwite all of the existing account holder metadata. In order to update an existing metadata key-value pair, all otherkey-value pairs should be provided in order to not delete them. + x-groupName: Account holders + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountHolderUpdated: + notificationURL: + post: + summary: Triggered upon the update of an Account Holder. + description: This notification is sent when an Account Holder has been updated. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderUpdateNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /updateAccountHolderState: + post: + summary: Update the state of an existing account holder. + description: |- + This endpoint is used to disable or enable the processing or payout state of an account holder. It cannot be used to enable an account holder whose processing or payout state has not been disabled through this endpoint. + + For further information regarding processing and payout states of an account holder, please refer to the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + x-groupName: Account holders + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderStateRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetAccountHolderStatusResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + callbacks: + accountHolderStatusChange: + notificationURL: + post: + summary: Triggered upon the status change of an Account Holder. + description: This notification is sent when the status of an Account Holder has been changed. + x-sortIndex: 0 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderStatusChangeNotification' + responses: + '200': + content: + application/json: + schema: + type: string + description: '[accepted]' + /uploadDocument: + post: + summary: Upload a document for an existing account holder. + description: |- + This endpoint is used to upload a document for use in the KYC verification of an account holder. + + For further information regarding KYC Verification, please refer to the [KYC Documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + x-groupName: Verification + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UploadDocumentRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. +components: + schemas: + Account: + properties: + accountCode: + description: The code of the account. + type: string + beneficiaryAccount: + description: The beneficiary of the account. + type: string + beneficiaryMerchantReference: + description: The reason that a beneficiary has been set up for this account. This may have been supplied during the setup of a beneficiary at the discretion of the executing user. + type: string + description: + description: A description of the account. + type: string + payoutSchedule: + description: The account's payout schedule. + $ref: '#/components/schemas/PayoutScheduleResponse' + status: + description: 'The status of the account. Possible values: `Active`, `Inactive`, `Suspended`, `Closed`.' + type: string + AccountCreateNotification: + properties: + content: + description: The details of the account creation. + $ref: '#/components/schemas/CreateAccountResponse' + eventDate: + description: The date and time when an event has been completed. + format: date-time + type: string + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - eventDate + - content + AccountEvent: + properties: + event: + description: |- + The event. + >Permitted values: `InactivateAccount`, `RefundNotPaidOutTransfers`. + Please refer to the KYC documentation for further information. + enum: + - InactivateAccount + - RefundNotPaidOutTransfers + type: string + executionDate: + description: The date on which the event will take place. + format: date-time + type: string + reason: + description: The reason why this event has been created. + type: string + required: + - event + - executionDate + - reason + AccountHolderCreateNotification: + properties: + content: + description: The details of the account holder creation. + $ref: '#/components/schemas/CreateAccountHolderResponse' + eventDate: + description: The date and time when an event has been completed. + format: date-time + type: string + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - eventDate + - content + AccountHolderDetails: + properties: + address: + description: The address of the account holder. + $ref: '#/components/schemas/Address' + bankAccountDetails: + description: |- + Each of the the bank accounts associated with the account holder. + > Each array entry should represent one bank account. + > For comprehensive detail regarding the required `BankAccountDetail` fields, please refer to the [KYC Verification documentation](https://docs.adyen.com/developers/marketpay/kyc-verification). + items: + $ref: '#/components/schemas/BankAccountDetail' + type: array + businessDetails: + description: |- + Details applicable to `Business` legal entities. + Populated only if the account holder's legal entity is of type `Business`. + > Required when being used in a `/createAccountHolder` request in which the legal entity is `Business`. + $ref: '#/components/schemas/BusinessDetails' + email: + description: The email address of the account holder. + type: string + fullPhoneNumber: + description: |- + The phone number of the account holder 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 + individualDetails: + description: |- + Details applicable to `Individual` legal entities. + Populated only if the account holder's legal entity is of type `Individual`. + > Required when being used in a `/createAccountHolder` request in which the legal entity is `Individual`. + $ref: '#/components/schemas/IndividualDetails' + merchantCategoryCode: + description: |- + The Merchant Category Code of the account holder. + > If not specified in the request, this will be derived from the marketplace account (which is configured by Adyen). + type: string + metadata: + additionalProperties: + type: string + description: |- + A set of key and value pairs for general use by the account holder or merchant. + The keys do not have specific names and may be used for storing miscellaneous data as desired. + > The values being stored have a maximum length of eighty (80) characters and will be truncated if necessary. + > Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs. + type: object + webAddress: + description: The URL of the website of the account holder. + type: string + required: + - fullPhoneNumber + - email + AccountHolderStatus: + properties: + accountEvents: + description: A list of events scheduled for the account holder. + items: + $ref: '#/components/schemas/AccountEvent' + type: array + payoutState: + description: The payout state of the account holder. + $ref: '#/components/schemas/AccountPayoutState' + processingState: + description: The processing state of the account holder. + $ref: '#/components/schemas/AccountProcessingState' + status: + description: |- + The status of the account holder. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + statusReason: + description: The reason why the status was assigned to the account holder. + type: string + required: + - status + - statusReason + - processingState + - payoutState + - accountEvents + AccountHolderStatusChangeNotification: + properties: + content: + description: The details of the Account Holder status change. + $ref: '#/components/schemas/AccountHolderStatusChangeNotificationContent' + eventDate: + description: The date and time when an event has been completed. + format: date-time + type: string + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - eventDate + AccountHolderStatusChangeNotificationContent: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + newAccountHolderStatus: + description: The new status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + oldAccountHolderStatus: + description: The former status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + reason: + description: The reason for the status change. + type: string + required: + - accountHolderCode + - oldAccountHolderStatus + - newAccountHolderStatus + - reason + AccountHolderUpdateNotification: + properties: + content: + description: The details of the Account Holder update. + $ref: '#/components/schemas/UpdateAccountHolderResponse' + eventDate: + description: The date and time when an event has been completed. + format: date-time + type: string + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - eventDate + - content + AccountHolderVerificationNotification: + properties: + content: + description: The details of the Account Holder verification. + $ref: '#/components/schemas/AccountHolderVerificationNotificationContent' + eventDate: + description: The date and time when an event has been completed. + format: date-time + type: string + eventType: + description: The event type of the notification. + type: string + executingUserKey: + description: The user or process that has triggered the notification. + type: string + live: + description: 'Indicates whether the notification originated from the live environment or the test environment. If true, the notification originated from the live environment. If false, the notification originated from the test environment.' + type: boolean + pspReference: + description: The PSP reference of the request from which the notification originates. + type: string + required: + - executingUserKey + - pspReference + - eventType + - live + - eventDate + - content + AccountHolderVerificationNotificationContent: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + bankAccountUUID: + description: The unique ID of the bank account that has been verified. + type: string + shareholderCode: + description: The code of the shareholder that has been verified. + type: string + statusSummary: + description: A summary of the verification status. + $ref: '#/components/schemas/KYCCheckSummary' + verificationStatus: + description: The status of verification. + enum: + - AWAITING_DATA + - DATA_PROVIDED + - FAILED + - INVALID_DATA + - PASSED + - PENDING + - PENDING_REVIEW + - RETRY_LIMIT_REACHED + - UNCHECKED + type: string + verificationType: + description: The type of validation performed. + enum: + - BANK_ACCOUNT_VERIFICATION + - COMPANY_VERIFICATION + - IDENTITY_VERIFICATION + - NONPROFIT_VERIFICATION + - PASSPORT_VERIFICATION + type: string + required: + - accountHolderCode + AccountPayoutState: + properties: + allowPayout: + description: Indicates whether payouts are allowed. + type: boolean + disableReason: + description: The reason why payouts have been disabled (by the marketplace). + type: string + disabled: + description: Indicates whether payouts have been disabled (by the marketplace) for all of the Account Holder's accounts. + type: boolean + payoutLimit: + description: The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited. + $ref: '#/components/schemas/Amount' + tierNumber: + description: |- + The payout tier that the Account Holder occupies. + >Please refer to the KYC Verification documentation for further detail on payout tiers. + format: int32 + type: integer + required: + - allowPayout + - disabled + - tierNumber + - disableReason + - payoutLimit + AccountProcessingState: + properties: + disableReason: + description: The reason why processing has been disabled. + type: string + disabled: + description: Indicates whether the processing of payments is allowed. + type: boolean + processedFrom: + description: |- + The lower bound of the processing tier (i.e., an account holder must have processed at least this amount of money in order to be placed into this tier). + >Please refer to the KYC Verification documentation for further detail on processing tiers. + $ref: '#/components/schemas/Amount' + processedTo: + description: |- + The upper bound of the processing tier (i.e., an account holder must have processed less than this amount of money in order to be placed into this tier). + >Please refer to the KYC Verification documentation for further detail on processing tiers. + $ref: '#/components/schemas/Amount' + tierNumber: + description: |- + The processing tier that the account holder occupies. + >Please refer to the KYC Verification documentation for further detail on processing tiers. + format: int32 + type: integer + required: + - disabled + - disableReason + - processedFrom + - processedTo + - tierNumber + Address: + properties: + city: + description: |- + The name of the city. + >Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided. + type: string + country: + description: |- + The two-character country code of the address + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + type: string + houseNumberOrName: + description: The number or name of the house. + type: string + postalCode: + 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: |- + The abbreviation of the state or province. + >Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries. + >Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided. + type: string + street: + description: |- + The name of the street. + >The house number should not be included in this field; it should be separately provided via `houseNumberOrName`. + >Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided. + type: string + required: + - country + Amount: + properties: + currency: + description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).' + maxLength: 3 + minLength: 3 + type: string + value: + 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). + format: int64 + type: integer + required: + - value + - currency + BankAccountDetail: + properties: + accountNumber: + description: |- + The bank account number (without separators). + >Please refer to the KYC Verification section for details on field requirements. + type: string + accountType: + description: |- + The type of bank account. + Only applicable to bank accounts held in the USA. + The permitted values are: `checking`, `savings`. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankAccountName: + description: The name of the bank account. + type: string + bankAccountUUID: + description: | + The unique identifier (UUID) of the Bank Account. + >**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Bank Account will be created with a procedurally-generated UUID.** + + >**If, during an Account Holder create request, a UUID is provided, the creation of the Bank Account will fail while the creation of the Account Holder will continue.** + + >**If, during an Account Holder update request, a UUID that is not correlated with an existing Bank Account is provided, the update of the Account Holder will fail.** + + >**If, during an Account Holder update request, a UUID that is correlated with an existing Bank Account is provided, the existing Bank Account will be updated.** + type: string + bankBicSwift: + description: |- + The bank identifier code. + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCity: + description: |- + The city in which the bank branch is located. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCode: + description: |- + The bank code of the banking institution with which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankName: + description: |- + The name of the banking institution with which the bank account is held. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + branchCode: + description: |- + The branch code of the branch under which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + checkCode: + description: |- + The check code of the bank account. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + countryCode: + description: |- + The two-letter country code in which the bank account is registered. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + currencyCode: + description: |- + The currency in which the bank account deals. + >The permitted currency codes are defined in ISO-4217 (e.g. 'EUR'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + iban: + description: |- + The international bank account number. + >The IBAN standard is defined in ISO-13616. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCity: + description: |- + The city of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCountryCode: + description: |- + The country code of the country of residence of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerDateOfBirth: + description: | + The date of birth of the bank account owner. + type: string + ownerHouseNumberOrName: + description: |- + The house name or number of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerName: + description: |- + The name of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerNationality: + description: |- + The country code of the country of nationality of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerPostalCode: + description: |- + The postal code of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerState: + description: |- + The state of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerStreet: + description: |- + The street name of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + primaryAccount: + description: 'If set to true, the bank account is a primary account.' + type: boolean + taxId: + description: |- + The tax ID number. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + urlForVerification: + description: |- + The URL to be used for bank account verification. + This may be generated on bank account creation. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + BusinessDetails: + properties: + doingBusinessAs: + description: The registered name of the company (if it differs from the legal name of the company). + type: string + legalBusinessName: + description: The legal name of the company. + type: string + registrationNumber: + description: The registration number of the company. + type: string + shareholders: + description: |- + Each of the shareholders associated with the company. + Each array entry should represent one shareholder. + items: + $ref: '#/components/schemas/ShareholderContact' + type: array + taxId: + description: The tax ID of the company. + type: string + CloseAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be closed. + type: string + required: + - accountHolderCode + CloseAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + CloseAccountRequest: + properties: + accountCode: + description: The code of account to be closed. + type: string + required: + - accountCode + CloseAccountResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + status: + description: |- + The new status of the account. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - status + CreateAccountHolderRequest: + properties: + accountHolderCode: + description: |- + The desired code of the prospective account holder. + > Must be between three (3) and fifty (50) characters long. Only letters, digits, and hyphens (-) are permitted. + type: string + accountHolderDetails: + description: The details of the prospective account holder. + $ref: '#/components/schemas/AccountHolderDetails' + createDefaultAccount: + description: |- + If set to true, an account with the default options is created for this account holder. + **Default Value:** true + type: boolean + description: + description: A description of the prospective account holder. + type: string + legalEntity: + description: |- + The entity type. + Permitted values: `Business`, `Individual` + + If an account holder is 'Business', then `accountHolderDetails.businessDetails` must be provided, as well as at least one entry in the `accountHolderDetails.businessDetails.shareholders` list. + + If an account holder is 'Individual', then `accountHolderDetails.individualDetails` must be provided. + enum: + - Business + - Individual + - NonProfit + type: string + primaryCurrency: + description: The currency with which the prospective account holder primarily deals. + type: string + processingTier: + description: 'The starting [processing tier](https://docs.adyen.com/developers/marketpay/kyc-verification/verification-process) for the prospective account holder.' + format: int32 + type: integer + required: + - accountHolderCode + - legalEntity + - accountHolderDetails + - description + CreateAccountHolderResponse: + properties: + accountCode: + description: The code of a new account created for the account holder. + type: string + accountHolderCode: + description: The code of the new account holder. + type: string + accountHolderDetails: + description: Details of the new account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The status of the new account holder. + $ref: '#/components/schemas/AccountHolderStatus' + description: + description: The description of the new account holder. + type: string + invalidFields: + description: A list of fields that caused the `/createAccountHolder` request to fail. + items: + $ref: '#/components/schemas/ErrorFieldType' + type: array + legalEntity: + description: The type of legal entity of the new account holder. + enum: + - Business + - Individual + - NonProfit + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountHolderStatus + - accountHolderDetails + - verificationResult + - legalEntity + CreateAccountRequest: + properties: + accountHolderCode: + description: The code of Account Holder under which to create the account. + type: string + description: + description: A description of the account. + type: string + payoutSchedule: + description: |- + The payout schedule of the prospective account. + >Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + payoutScheduleReason: + description: |- + The reason for the payout schedule choice. + >Required if the payoutSchedule is `HOLD`. + type: string + required: + - accountHolderCode + - payoutSchedule + - payoutScheduleReason + - description + CreateAccountResponse: + properties: + accountCode: + description: The code of the new account. + type: string + accountHolderCode: + description: The code of the account holder. + type: string + description: + description: The description of the account. + type: string + payoutSchedule: + description: The payout schedule of the account. + $ref: '#/components/schemas/PayoutScheduleResponse' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + status: + description: |- + The status of the account. + >Permitted values: `Active`, `Inactive`, `Suspended`, `Closed`. + enum: + - Active + - Closed + - Inactive + - Suspended + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountCode + - status + DeleteBankAccountRequest: + properties: + accountHolderCode: + description: The code of the Account Holder from which to delete the Bank Account(s). + type: string + bankAccountUUIDs: + description: The code(s) of the Bank Accounts to be deleted. + items: + type: string + type: array + required: + - accountHolderCode + - bankAccountUUIDs + DeleteShareholderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder from which to delete the Shareholders. + type: string + shareholderCodes: + description: The code(s) of the Shareholders to be deleted. + items: + type: string + type: array + required: + - accountHolderCode + - shareholderCodes + DocumentDetail: + properties: + accountHolderCode: + description: The code of Account Holder to which the document applies. + type: string + bankAccountUUID: + description: |- + The unique ID of the Bank Account to which the document applies. + >Required if the documentType is `BANK_STATEMENT` (i.e., a document is being submitted in order to verify a bank account). + + >Please refer to the KYC Verification section for details on when a document should be submitted in order to verify a bank account. + type: string + description: + description: Description of the document. + type: string + documentType: + description: |- + The type of document. + Permitted values: + * `ID_CARD` denotes an image containing both the front and back of the ID card. + * `ID_CARD_FRONT` denotes an image containing only the front of the ID card. In order for a document to be usable, both the ID_CARD_FRONT and ID_CARD_BACK must be submitted. + * `ID_CARD_BACK` denotes an image containing only the back of the ID card. In order for a document to be usable, both the ID_CARD_FRONT and ID_CARD_BACK must be submitted. + * `DRIVING_LICENCE` denotes an image containing both the front and back of the driving licence. + * `DRIVING_LICENCE_FRONT` denotes an image containing only the front of the driving licence. In order for a document to be usable, both the DRIVING_LICENCE_FRONT and DRIVING_LICENCE_BACK must be submitted. + * `DRIVING_LICENCE_BACK` denotes an image containing only the back of the driving licence. In order for a document to be usable, both the DRIVING_LICENCE_FRONT and DRIVING_LICENCE_FRONT must be submitted. + + >Please refer to [Verification checks](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks) for details on when each document type should be submitted. + enum: + - BANK_STATEMENT + - BSN + - DRIVING_LICENCE + - DRIVING_LICENCE_BACK + - DRIVING_LICENCE_FRONT + - ID_CARD + - ID_CARD_BACK + - ID_CARD_FRONT + - NHIS + - PASSPORT + - SSN + type: string + filename: + description: Filename of the document. + type: string + shareholderCode: + description: |- + The code of the Shareholder to which the document applies. + >Required if the Account Holder referred to by the accountHolderCode has a legalEntity of type `Business` and the documentType is either `PASSPORT`, `ID_CARD`, ID_CARD_FRONT`, `ID_CARD_BACK`, `DRIVING_LICENCE`, `DRIVING_LICENCE_FRONT`, `DRIVING_LICENCE_BACK` (i.e. a document is being submitted in order to verify a shareholder). + + >Please refer to the KYC Verification section for details on when a document should be submitted in order to verify a shareholder. + type: string + required: + - accountHolderCode + - documentType + - filename + ErrorFieldType: + properties: + errorCode: + description: The validation error code. + format: int32 + type: integer + errorDescription: + description: A description of the validation error. + type: string + fieldType: + description: The type of error field. + $ref: '#/components/schemas/FieldType' + FieldType: + properties: + field: + description: The full name of the property. + type: string + fieldName: + description: The type of the field. + enum: + - accountHolderCode + - accountHolderDetails + - accountNumber + - accountType + - address + - bankAccount + - bankBicSwift + - bankCity + - bankCode + - bankName + - bankStatement + - branchCode + - businessContact + - checkCode + - city + - country + - countryCode + - currencyCode + - dateOfBirth + - description + - document + - drivingLicence + - drivingLicenceBack + - email + - firstName + - fullPhoneNumber + - gender + - houseNumberOrName + - iban + - idCard + - idCardBack + - idCardFront + - idNumber + - identityDocument + - lastName + - legalBusinessName + - merchantCategoryCode + - microDeposit + - name + - nationality + - ownerCity + - ownerCountryCode + - ownerHouseNumberOrName + - ownerName + - ownerPostalCode + - ownerState + - ownerStreet + - passport + - personalData + - phoneCountryCode + - phoneNumber + - postalCode + - registrationNumber + - shareholder + - stateOrProvince + - street + - taxId + - tierNumber + - unknown + - virtualAccount + - webAddress + type: string + shareholderCode: + description: 'The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.' + type: string + GenericResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + GetAccountHolderRequest: + properties: + accountCode: + description: |- + The code of the account of which to retrieve the details. + > Required if no `accountHolderCode` is provided. + type: string + accountHolderCode: + description: |- + The code of the account holder of which to retrieve the details. + > Required if no `accountCode` is provided. + type: string + GetAccountHolderResponse: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + accountHolderDetails: + description: Details of the account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + accounts: + description: A list of the accounts under the account holder. + items: + $ref: '#/components/schemas/Account' + type: array + description: + description: The description of the account holder. + type: string + legalEntity: + description: The legal entity of the account holder. + enum: + - Business + - Individual + - NonProfit + type: string + primaryCurrency: + description: The currency with which the prospective account holder primarily deals. + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderCode + - legalEntity + - accountHolderStatus + - accountHolderDetails + - verificationResult + GetAccountHolderStatusResponse: + properties: + accountHolderCode: + description: The code of the Account Holder. + type: string + accountHolderStatus: + description: The status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderCode + - accountHolderStatus + GetUploadedDocumentsRequest: + properties: + accountHolderCode: + description: The code of the Account Holder for which to retrieve the documents. + type: string + bankAccountUUID: + description: The code of the Bank Account for which to retrieve the documents. + type: string + shareholderCode: + description: The code of the Shareholder for which to retrieve the documents. + type: string + required: + - accountHolderCode + GetUploadedDocumentsResponse: + properties: + documentDetails: + description: A list of the documents and their details. + items: + $ref: '#/components/schemas/DocumentDetail' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + IndividualDetails: + properties: + name: + description: The name of the individual. + $ref: '#/components/schemas/Name' + personalData: + description: Personal information of the individual. + $ref: '#/components/schemas/PersonalData' + KYCBankAccountCheckResult: + properties: + bankAccountUUID: + description: The unique ID of the bank account to which the check applies. + type: string + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + required: + - checkStatusData + - bankAccountUUID + KYCCheckResult: + properties: + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + required: + - checkStatusData + KYCCheckStatusData: + properties: + checkStatus: + description: |- + The status of the check. + >Permitted Values: `UNCHECKED`, `DATA_PROVIDED`, `PASSED`, `PENDING`, `AWAITING_DATA`, `RETRY_LIMIT_REACHED`, `INVALID_DATA`, `FAILED`. + enum: + - AWAITING_DATA + - DATA_PROVIDED + - FAILED + - INVALID_DATA + - PASSED + - PENDING + - PENDING_REVIEW + - RETRY_LIMIT_REACHED + - UNCHECKED + type: string + checkType: + description: |- + The type of check. + >Permitted Values: `COMPANY_VERIFICATION`, `IDENTITY_VERIFICATION`, `PASSPORT_VERIFICATION`, `BANK_ACCOUNT_VERIFICATION`, `NONPROFIT_VERIFICATION`. + enum: + - BANK_ACCOUNT_VERIFICATION + - COMPANY_VERIFICATION + - IDENTITY_VERIFICATION + - NONPROFIT_VERIFICATION + - PASSPORT_VERIFICATION + type: string + requiredFields: + description: A list of the fields required for execution of the check. + items: + type: string + type: array + summary: + description: A summary of the execution of the check. + $ref: '#/components/schemas/KYCCheckSummary' + required: + - checkType + - checkStatus + - summary + - requiredFields + KYCCheckSummary: + properties: + code: + description: The code of the check. + format: int32 + type: integer + description: + description: A description of the check. + type: string + required: + - code + KYCShareholderCheckResult: + properties: + checkStatusData: + description: A list of the checks and their statuses. + items: + $ref: '#/components/schemas/KYCCheckStatusData' + type: array + shareholderCode: + description: The code of the shareholder to which the check applies. + type: string + required: + - checkStatusData + - shareholderCode + KYCVerificationResult: + properties: + accountHolderCheckResult: + description: The result(s) of the checks on the account holder. + $ref: '#/components/schemas/KYCCheckResult' + bankAccountCheckResult: + description: The result(s) of the checks on the bank account(s). + items: + $ref: '#/components/schemas/KYCBankAccountCheckResult' + type: array + shareholderCheckResult: + description: The result(s) of the checks on the shareholder(s). + items: + $ref: '#/components/schemas/KYCShareholderCheckResult' + type: array + required: + - accountHolderCheckResult + - shareholderCheckResult + - bankAccountCheckResult + Name: + properties: + firstName: + description: The first name. + type: string + gender: + description: |- + The gender. + >The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`. + enum: + - MALE + - FEMALE + - UNKNOWN + maxLength: 1 + minLength: 1 + type: string + infix: + description: |- + The name's infix, if applicable. + >A maximum length of twenty (20) characters is imposed. + type: string + lastName: + description: The last name. + type: string + required: + - firstName + - lastName + - gender + PayoutScheduleResponse: + properties: + nextScheduledPayout: + description: The date of the next scheduled payout. + format: date-time + type: string + schedule: + description: |- + The payout schedule of the account. + >Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + required: + - schedule + - nextScheduledPayout + PersonalData: + properties: + dateOfBirth: + description: |- + The date of birth of the person. + The date should be in ISO-8601 format yyyy-mm-dd (e.g. 2000-01-31). + type: string + idNumber: + description: An ID number of the person. + type: string + nationality: + description: |- + The nationality of the person represented by a two-character country code. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + maxLength: 2 + minLength: 2 + type: string + PhoneNumber: + properties: + phoneCountryCode: + description: |- + The two-character country code of the phone number. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + type: string + phoneNumber: + description: |- + The phone number. + >The inclusion of the phone number country code is not necessary. + type: string + phoneType: + description: |- + The type of the phone number. + >The following values are permitted: `Landline`, `Mobile`, `SIP`, `Fax`. + enum: + - Fax + - Landline + - Mobile + - SIP + type: string + required: + - phoneCountryCode + - phoneNumber + ShareholderContact: + properties: + address: + description: The address of the contact. + $ref: '#/components/schemas/Address' + email: + description: The e-mail address of the contact. + type: string + fullPhoneNumber: + description: |- + The 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' + personalData: + description: Personal data of the contact. + $ref: '#/components/schemas/PersonalData' + phoneNumber: + description: The phone number of the contact. + $ref: '#/components/schemas/PhoneNumber' + shareholderCode: + description: | + The unique identifier (UUID) of the Shareholder. + >**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Shareholder will be created with a procedurally-generated UUID.** + + >**If, during an Account Holder create request, a UUID is provided, the creation of the Shareholder will fail while the creation of the Account Holder will continue.** + + >**If, during an Account Holder update request, a UUID that is not correlated with an existing Shareholder is provided, the update of the Shareholder will fail.** + + >**If, during an Account Holder update request, a UUID that is correlated with an existing Shareholder is provided, the existing Bank Account will be updated.** + type: string + webAddress: + description: The URL of the website of the contact. + type: string + SuspendAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the account holder to be suspended. + type: string + required: + - accountHolderCode + SuspendAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the Account Holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + UnSuspendAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the account holder to be reinstated. + type: string + required: + - accountHolderCode + UnSuspendAccountHolderResponse: + properties: + accountHolderStatus: + description: The new status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountHolderStatus + UpdateAccountHolderRequest: + properties: + accountHolderCode: + description: The code of the Account Holder to be updated. + type: string + accountHolderDetails: + description: |- + The details to which the Account Holder should be updated. + + Required if a processingTier is not provided. + $ref: '#/components/schemas/AccountHolderDetails' + description: + description: The description to which the Account Holder should be updated. + type: string + primaryCurrency: + description: The primary currency to which the Account Holder should be updated. + type: string + processingTier: + description: |- + The processing tier to which the Account Holder should be updated. + >The processing tier can not be lowered through this request. + + >Required if accountHolderDetails are not provided. + format: int32 + type: integer + required: + - accountHolderCode + UpdateAccountHolderResponse: + properties: + accountHolderCode: + description: The code of the account holder. + type: string + accountHolderDetails: + description: Details of the account holder. + $ref: '#/components/schemas/AccountHolderDetails' + accountHolderStatus: + description: The new status of the account holder. + $ref: '#/components/schemas/AccountHolderStatus' + description: + description: The description of the account holder. + type: string + invalidFields: + description: 'in case the account holder has not been updated, contains account holder fields, that did not pass the validation.' + items: + $ref: '#/components/schemas/ErrorFieldType' + type: array + legalEntity: + description: The legal entity of the account holder. + enum: + - Business + - Individual + - NonProfit + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + updatedFields: + description: A list of the fields updated through the request. + items: + $ref: '#/components/schemas/FieldType' + type: array + verificationResult: + description: The details of KYC Verification of the account holder. + $ref: '#/components/schemas/KYCVerificationResult' + required: + - pspReference + - submittedAsync + - accountHolderStatus + - verificationResult + - legalEntity + UpdateAccountHolderStateRequest: + properties: + accountHolderCode: + description: The code of the Account Holder on which to update the state. + type: string + disable: + description: 'If true, disable the requested state. If false, enable the requested state.' + type: boolean + reason: + description: |- + The reason that the state is being updated. + >Required if the state is being disabled. + type: string + stateType: + description: |- + The state to be updated. + >Permitted values are: `Processing`, `Payout` + enum: + - LimitedPayout + - LimitedProcessing + - LimitlessPayout + - LimitlessProcessing + - Payout + - Processing + type: string + required: + - accountHolderCode + - stateType + - disable + UpdateAccountRequest: + properties: + accountCode: + description: The code of the account to update. + type: string + description: + description: A description of the account. + type: string + payoutSchedule: + description: 'The details of the payout schedule, to which the account should be updated.' + $ref: '#/components/schemas/UpdatePayoutScheduleRequest' + required: + - accountCode + UpdateAccountResponse: + properties: + accountCode: + description: The code of the account. + type: string + description: + description: The description of the account. + type: string + payoutSchedule: + description: The payout schedule of the account. + $ref: '#/components/schemas/PayoutScheduleResponse' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - accountCode + - payoutSchedule + UpdatePayoutScheduleRequest: + properties: + action: + description: |- + Direction on how to handle any payouts that have already been scheduled. + Permitted values: + * `CLOSE` will close the existing batch of payouts. + * `UPDATE` will reschedule the existing batch to the new schedule. + * `NOTHING` (**default**) will allow the payout to proceed. + enum: + - CLOSE + - NOTHING + - UPDATE + type: string + reason: + description: |- + The reason for the payout schedule update. + > This field is required when the `schedule` parameter is set to `HOLD`. + type: string + schedule: + description: |- + The payout schedule to which the account is to be updated. + Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. + enum: + - DAILY + - DEFAULT + - HOLD + - MONTHLY + - WEEKLY + type: string + required: + - schedule + UploadDocumentRequest: + properties: + documentContent: + description: |- + The content of the document as represented by a Base64-encoded string. + + Restrictions: + * Maximum 2 pages. + * File size must be no less than 1000 bytes and no greater than 10 MB. + * File format must be either a jpeg, jpg, pdf, or png. + format: byte + type: string + documentDetail: + description: Details of the document being submitted. + $ref: '#/components/schemas/DocumentDetail' + required: + - documentDetail + - documentContent diff --git a/specs/3.0/FundService-v3.yaml b/specs/3.0/FundService-v3.yaml new file mode 100644 index 0000000..6e5048f --- /dev/null +++ b/specs/3.0/FundService-v3.yaml @@ -0,0 +1,763 @@ +openapi: 3.0.0 +servers: + - url: 'https://cal-test.adyen.com/cal/services/Fund/v3' +info: + version: '3' + title: Adyen MarketPay Fund Service + description: |- + The MarketPay Funding API provides endpoints for managing the funds in MarketPay accounts. These management operations include actions such as the transfer of funds from one account to another, the payout of funds to an account holder, and the retrieval of balances in an account. + + For further information on MarketPay fund management, please visit the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + ## Authentication + To connect to the MarketPay API, you must use basic authentication credentials of your web service user. If you don't have one, please contact the [Adyen Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials to authenticate your request, for example: + + ``` + curl + -U "ws@Company.YourCompany":"YourWsPassword" \ + -H "Content-Type: application/json" \ + ... + ``` + Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/developers/api-reference/live-endpoints). + + ## Versioning + MarketPay API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number. + + For example: + ``` + https://cal-test.adyen.com/cal/services/Fund/v3/accountHolderBalance + ``` + termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com +x-groups: + - General +paths: + /accountHolderBalance: + post: + summary: Retrieve the balance(s) of an account holder. + description: 'This endpoint is used to retrieve the balance(s) of the accounts of an account holder. An account''s balances are on a per-currency basis (i.e., an account may have multiple balances: one per currency).' + x-groupName: General + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderBalanceRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderBalanceResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /accountHolderTransactionList: + post: + summary: Retrieve a list of transactions. + description: This endpoint is used to retrieve a list of Transactions for an account holder's accounts. The accounts and Transaction Statuses to be included on the list can be specified. Each call will return a maximum of fifty (50) Transactions per account; in order to retrieve the following set of Transactions another call should be made with the 'page' value incremented. Note that Transactions are ordered with most recent first. + x-groupName: General + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderTransactionListRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/AccountHolderTransactionListResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /payoutAccountHolder: + post: + summary: Disburse a specified amount from an account to the account holder. + description: This endpoint is used to pay out a specified amount from an account to the bank account of the account's account holder. + x-groupName: General + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PayoutAccountHolderRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/PayoutAccountHolderResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /refundNotPaidOutTransfers: + post: + summary: Refund all transactions of an account since the most recent payout. + description: 'This endpoint is used to refund all the transactions of an account which have taken place since the most recent payout. This request is on a per-account basis (as opposed to a per-payment basis), so only the portion of the payment which was made to the specified account will be refunded. The commission(s), fee(s), and payment(s) to other account(s), will remain in the accounts to which they were sent as designated by the original payment''s split details.' + x-groupName: General + x-sortIndex: 6 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RefundNotPaidOutTransfersRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/RefundNotPaidOutTransfersResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /setupBeneficiary: + post: + summary: Designate an account to be the beneficiary of a separate account and transfer the benefactor's current balance to the beneficiary. + description: 'This endpoint is used to define a benefactor and a beneficiary relationship between two accounts. At the time of benefactor/beneficiary setup, the funds in the benefactor account are transferred to the beneficiary account, and any further payments to the benefactor account are automatically sent to the beneficiary account. Note that a series of benefactor/beneficiaries may not exceed four (4) beneficiaries and may not have a cycle in it.' + x-groupName: General + x-sortIndex: 5 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SetupBeneficiaryRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SetupBeneficiaryResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /transferFunds: + post: + summary: Transfer funds from one marketplace account to another. + description: 'This endpoint is used to transfer funds from one account to another account. Both accounts must be in the same marketplace, but can have different account holders. The transfer must include a transfer code, which should be determined by the marketplace, in compliance with local regulations.' + x-groupName: General + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TransferFundsRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TransferFundsResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. +components: + schemas: + AccountDetailBalance: + properties: + accountCode: + description: The code of the account that holds the balance. + type: string + detailBalance: + description: Details of the balance held by the account. + $ref: '#/components/schemas/DetailBalance' + AccountHolderBalanceRequest: + properties: + accountHolderCode: + description: The code of the Account Holder of which to retrieve the balance. + type: string + required: + - accountHolderCode + AccountHolderBalanceResponse: + properties: + balancePerAccount: + description: A list of each account and their balances. + items: + $ref: '#/components/schemas/AccountDetailBalance' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + resultCode: + description: The result code. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + totalBalance: + description: The total balance of the account holder. + $ref: '#/components/schemas/DetailBalance' + required: + - pspReference + - submittedAsync + - resultCode + AccountHolderTransactionListRequest: + properties: + accountHolderCode: + description: The code of the Account Holder that owns the account(s) of which retrieve the transaction list. + type: string + transactionListsPerAccount: + description: 'A list of accounts to include in the transaction list. If left blank, the last fifty (50) transactions for all accounts of the Account Holder will be included.' + items: + $ref: '#/components/schemas/TransactionListForAccount' + type: array + transactionStatuses: + description: |- + A list of statuses to include in the transaction list. If left blank, all transactions will be included. + >Permitted values: `PendingCredit`, `CreditFailed`, `Credited`, `Converted`, `PendingDebit`, `DebitFailed`, `Debited`, `DebitReversedReceived`, `DebitedReversed`, `ChargebackReceived`, `Chargeback`, `ChargebackReversedReceived`, `ChargebackReversed`, `Payout`, `PayoutReversed`, `FundTransfer`, `PendingFundTransfer`. + >* `PendingCredit`: a pending balance credit. + >* `CreditFailed`: a pending credit failure; the balance will not be credited. + >* `Credited`: a credited balance. + >* `PendingDebit`: a pending balance debit (e.g., a refund). + >* `DebitFailed`: a pending debit failure; the balance will not be debited. + >* `Debited`: a debited balance (e.g., a refund). + >* `DebitReversedReceived`: a pending refund reversal. + >* `DebitedReversed`: a reversed refund. + >* `ChargebackReceived`: a received chargeback request. + >* `Chargeback`: a processed chargeback. + >* `ChargebackReversedReceived`: a pending chargeback reversal. + >* `ChargebackReversed`: a reversed chargeback. + >* `Payout`: a payout. + >* `PayoutReversed`: a reversed payout. + >* `FundTransfer`: the transfer of funds from one account to another. + items: + enum: + - Chargeback + - ChargebackReceived + - ChargebackReversed + - ChargebackReversedReceived + - Converted + - CreditFailed + - Credited + - DebitFailed + - DebitReversedReceived + - Debited + - DebitedReversed + - FundTransfer + - Payout + - PayoutReversed + - PendingCredit + - PendingDebit + - PendingFundTransfer + type: string + type: array + required: + - accountHolderCode + AccountHolderTransactionListResponse: + properties: + accountTransactionLists: + description: A list of the transactions. + items: + $ref: '#/components/schemas/AccountTransactionList' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + resultCode: + description: The result code. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - resultCode + AccountTransactionList: + properties: + accountCode: + description: The code of the account. + type: string + hasNextPage: + description: Indicates whether there is a next page of transactions available. + type: boolean + transactions: + description: The list of transactions. + items: + $ref: '#/components/schemas/Transaction' + type: array + Amount: + properties: + currency: + description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).' + maxLength: 3 + minLength: 3 + type: string + value: + 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). + format: int64 + type: integer + required: + - value + - currency + BankAccountDetail: + properties: + accountNumber: + description: |- + The bank account number (without separators). + >Please refer to the KYC Verification section for details on field requirements. + type: string + accountType: + description: |- + The type of bank account. + Only applicable to bank accounts held in the USA. + The permitted values are: `checking`, `savings`. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankAccountName: + description: The name of the bank account. + type: string + bankAccountUUID: + description: | + The unique identifier (UUID) of the Bank Account. + >**If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Bank Account will be created with a procedurally-generated UUID.** + + >**If, during an Account Holder create request, a UUID is provided, the creation of the Bank Account will fail while the creation of the Account Holder will continue.** + + >**If, during an Account Holder update request, a UUID that is not correlated with an existing Bank Account is provided, the update of the Account Holder will fail.** + + >**If, during an Account Holder update request, a UUID that is correlated with an existing Bank Account is provided, the existing Bank Account will be updated.** + type: string + bankBicSwift: + description: |- + The bank identifier code. + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCity: + description: |- + The city in which the bank branch is located. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankCode: + description: |- + The bank code of the banking institution with which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + bankName: + description: |- + The name of the banking institution with which the bank account is held. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + branchCode: + description: |- + The branch code of the branch under which the bank account is registered. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + checkCode: + description: |- + The check code of the bank account. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + countryCode: + description: |- + The two-letter country code in which the bank account is registered. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + currencyCode: + description: |- + The currency in which the bank account deals. + >The permitted currency codes are defined in ISO-4217 (e.g. 'EUR'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + iban: + description: |- + The international bank account number. + >The IBAN standard is defined in ISO-13616. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCity: + description: |- + The city of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerCountryCode: + description: |- + The country code of the country of residence of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerDateOfBirth: + description: | + The date of birth of the bank account owner. + type: string + ownerHouseNumberOrName: + description: |- + The house name or number of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerName: + description: |- + The name of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerNationality: + description: |- + The country code of the country of nationality of the bank account owner. + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerPostalCode: + description: |- + The postal code of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerState: + description: |- + The state of residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + ownerStreet: + description: |- + The street name of the residence of the bank account owner. + >Please refer to the KYC Verification section for details on field requirements. + type: string + primaryAccount: + description: 'If set to true, the bank account is a primary account.' + type: boolean + taxId: + description: |- + The tax ID number. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + urlForVerification: + description: |- + The URL to be used for bank account verification. + This may be generated on bank account creation. + + >Please refer to the KYC Verification section for details on field requirements. + type: string + DetailBalance: + properties: + balance: + description: The list of balances held by the account. + items: + $ref: '#/components/schemas/Amount' + type: array + pendingBalance: + description: The list of pending balances held by the account. + items: + $ref: '#/components/schemas/Amount' + type: array + PayoutAccountHolderRequest: + properties: + accountCode: + description: The code of the account from which the payout is to be made. + type: string + accountHolderCode: + description: |- + The code of the Account Holder who owns the account from which the payout is to be made. + The Account Holder is the party to which the payout will be made. + type: string + amount: + description: The amount to pay out. + $ref: '#/components/schemas/Amount' + bankAccountUUID: + description: |- + The unique ID of the Bank Account held by the Account Holder to which the payout is to be made. + If left blank, a bank account is automatically selected. + type: string + description: + description: A description of the payout. + type: string + merchantReference: + description: A value that can be supplied at the discretion of the executing user in order to link multiple transactions to one another. + type: string + required: + - accountHolderCode + - accountCode + - amount + PayoutAccountHolderResponse: + properties: + bankAccountUUID: + description: The unique ID of the Bank Account to which the payout was made. + type: string + merchantReference: + description: The value supplied by the executing user when initiating the transfer; may be used to link multiple transactions. + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - bankAccountUUID + RefundNotPaidOutTransfersRequest: + properties: + accountCode: + description: The code of the account from which to perform the refund(s). + type: string + accountHolderCode: + description: The code of the Account Holder which owns the account from which to perform the refund(s). + type: string + required: + - accountHolderCode + - accountCode + RefundNotPaidOutTransfersResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + resultCode: + description: The result code. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - resultCode + SetupBeneficiaryRequest: + properties: + destinationAccountCode: + description: The destination account code. + type: string + merchantReference: + description: A value that can be supplied at the discretion of the executing user. + type: string + sourceAccountCode: + description: The benefactor account. + type: string + required: + - sourceAccountCode + - destinationAccountCode + - merchantReference + SetupBeneficiaryResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + resultCode: + description: The result code. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + Transaction: + properties: + amount: + description: The amount of the transaction. + $ref: '#/components/schemas/Amount' + bankAccountDetail: + description: The details of the Bank Account to where a payout was made. + $ref: '#/components/schemas/BankAccountDetail' + captureMerchantReference: + description: The merchant reference of a related capture. + type: string + capturePspReference: + description: The psp reference of a related capture. + type: string + creationDate: + description: The date on which the transaction was performed. + format: date-time + type: string + description: + description: A description of the transaction. + type: string + destinationAccountCode: + description: The code of the account to which funds were credited during an outgoing fund transfer. + type: string + disputePspReference: + description: The psp reference of the related dispute. + type: string + disputeReasonCode: + description: The reason code of a dispute. + type: string + merchantReference: + description: The merchant reference of a transaction. + type: string + paymentPspReference: + description: The psp reference of the related authorisation or transfer. + type: string + payoutPspReference: + description: The psp reference of the related payout. + type: string + pspReference: + description: The psp reference of a transaction. + type: string + sourceAccountCode: + description: The code of the account from which funds were debited during an incoming fund transfer. + type: string + transactionStatus: + description: |- + The status of the transaction. + >Permitted values: `PendingCredit`, `CreditFailed`, `Credited`, `Converted`, `PendingDebit`, `DebitFailed`, `Debited`, `DebitReversedReceived`, `DebitedReversed`, `ChargebackReceived`, `Chargeback`, `ChargebackReversedReceived`, `ChargebackReversed`, `Payout`, `PayoutReversed`, `FundTransfer`, `PendingFundTransfer`. + enum: + - Chargeback + - ChargebackReceived + - ChargebackReversed + - ChargebackReversedReceived + - Converted + - CreditFailed + - Credited + - DebitFailed + - DebitReversedReceived + - Debited + - DebitedReversed + - FundTransfer + - Payout + - PayoutReversed + - PendingCredit + - PendingDebit + - PendingFundTransfer + type: string + transferCode: + description: The transfer code of the transaction. + type: string + TransactionListForAccount: + properties: + accountCode: + description: The account for which to retrieve the transactions. + type: string + page: + description: |- + The page of transactions to retrieve. + Each page lists fifty (50) transactions. The most recent transactions are included on page 1. + format: int32 + type: integer + required: + - accountCode + - page + TransferFundsRequest: + properties: + amount: + description: The amount to be transferred. + $ref: '#/components/schemas/Amount' + destinationAccountCode: + description: |- + The code of the account to which the funds are to be credited. + >The state of the Account Holder of this account must be Active. + type: string + merchantReference: + description: A value that can be supplied at the discretion of the executing user in order to link multiple transactions to one another. + type: string + sourceAccountCode: + description: |- + The code of the account from which the funds are to be debited. + >The state of the Account Holder of this account must be Active and allow payouts. + type: string + transferCode: + description: |- + The code related to the type of transfer being performed. + >The permitted codes differ for each Marketplace and are defined in their service level agreement. + type: string + required: + - sourceAccountCode + - destinationAccountCode + - transferCode + - amount + TransferFundsResponse: + properties: + merchantReference: + description: The value supplied by the executing user when initiating the transfer; may be used to link multiple transactions. + type: string + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + resultCode: + description: The result code. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - resultCode diff --git a/specs/3.0/NotificationConfigurationService-v1.yaml b/specs/3.0/NotificationConfigurationService-v1.yaml new file mode 100644 index 0000000..f1d355f --- /dev/null +++ b/specs/3.0/NotificationConfigurationService-v1.yaml @@ -0,0 +1,416 @@ +openapi: 3.0.0 +servers: + - url: 'https://cal-test.adyen.com/cal/services/Notification/v1' +info: + version: '1' + title: Adyen MarketPay Notification Configuration Service + description: |- + The MarketPay Notification Configuration API provides endpoints for configuration a subscription to a marketplace's MarketPay-related notifications. Notifications are sent upon the occurrence of certain events (such as a KYC check completion or a payout completion), and the subscription to these notifications dictates to where they are sent. + + For further information on MarketPay notifications, please visit the [MarketPay documentation](https://docs.adyen.com/developers/marketpay/marketpay-overview). + ## Authentication + To connect to the MarketPay API, you must use basic authentication credentials of your web service user. If you don't have one, please contact the [Adyen Support Team](https://support.adyen.com/hc/en-us/requests/new). Then use its credentials to authenticate your request, for example: + + ``` + curl + -U "ws@Company.YourCompany":"YourWsPassword" \ + -H "Content-Type: application/json" \ + ... + ``` + Note that when going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/developers/api-reference/live-endpoints). + + ## Versioning + MarketPay API supports versioning of its endpoints through a version suffix in the endpoint URL. This suffix has the following format: "vXX", where XX is the version number. + + For example: + ``` + https://cal-test.adyen.com/cal/services/Notification/v1/createNotificationConfiguration + ``` + termsOfService: 'https://docs.adyen.com/legal/terms-conditions' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com +x-groups: + - General +paths: + /createNotificationConfiguration: + post: + summary: Configure a new subscription to notifications. + description: 'This endpoint is used to create a subscription to MarketPay event notifications. After the subscription is created, the events specified in the configuration will be sent to the URL specified in the configuration. Subscriptions must be configured on a per-event basis (as opposed to, for example, a per-account holder basis), so all event notifications of a marketplace and of a given type will be sent to the same endpoint(s). A marketplace may have multiple endpoints if desired; an event notification may be sent to as many or as few different endpoints as configured.' + x-groupName: General + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/CreateNotificationConfigurationRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetNotificationConfigurationResponse' + description: OK - the request has succeeded. + /deleteNotificationConfigurations: + post: + summary: Delete an existing notification subscription configuration. + description: 'This endpoint is used to delete an existing notification subscription configuration. After the subscription is deleted, no further event notifications will be sent to the URL that was in the subscription.' + x-groupName: General + x-sortIndex: 6 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteNotificationConfigurationRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GenericResponse' + description: OK - the request has succeeded. + /getNotificationConfiguration: + post: + summary: Retrieve an existing notification subscription configuration. + description: This endpoint is used to retrieve the details of the configuration of a notification subscription. + x-groupName: General + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetNotificationConfigurationRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetNotificationConfigurationResponse' + description: OK - the request has succeeded. + /getNotificationConfigurationList: + post: + summary: Retrive a list of existing notification subscription configurations. + description: This endpoint is used to retrieve the details of the configurations of all of the notification subscriptions in the marketplace of the executing user. + x-groupName: General + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/EmptyRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetNotificationConfigurationListResponse' + description: OK - the request has succeeded. + /testNotificationConfiguration: + post: + summary: Test an existing notification configuration. + description: 'This endpoint is used to test an existing notification subscription configuration. For each event type specified, a test notification will be generated and sent to the URL configured in the subscription specified.' + x-groupName: General + x-sortIndex: 4 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/TestNotificationConfigurationRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/TestNotificationConfigurationResponse' + description: OK - the request has succeeded. + /updateNotificationConfiguration: + post: + summary: Update an existing notification subscription configuration. + description: 'This endpoint is used to update an existing notification subscription configuration. If updating the event types, all event types desired must be provided, otherwise the previous event type configuration will be overwritten.' + x-groupName: General + x-sortIndex: 5 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateNotificationConfigurationRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/GetNotificationConfigurationResponse' + description: OK - the request has succeeded. +components: + schemas: + CreateNotificationConfigurationRequest: + properties: + configurationDetails: + description: Details of the prospective notification subscription configuration. + $ref: '#/components/schemas/NotificationConfigurationDetails' + required: + - configurationDetails + DeleteNotificationConfigurationRequest: + properties: + notificationIds: + description: A list of IDs of the notification subscription configurations to be deleted. + items: + format: int64 + type: integer + type: array + required: + - notificationIds + EmptyRequest: {} + ExchangeMessage: + properties: + messageCode: + type: string + messageDescription: + type: string + GenericResponse: + properties: + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + GetNotificationConfigurationListResponse: + properties: + configurations: + description: Details of the notification subscription configurations. + items: + $ref: '#/components/schemas/NotificationConfigurationDetails' + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - configurations + GetNotificationConfigurationRequest: + properties: + notificationId: + description: The ID of the notification subscription configuration whose details are to be retrieved. + format: int64 + type: integer + required: + - notificationId + GetNotificationConfigurationResponse: + properties: + configurationDetails: + description: Details of the notification subscription configuration. + $ref: '#/components/schemas/NotificationConfigurationDetails' + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - configurationDetails + NotificationConfigurationDetails: + properties: + active: + description: Indicates whether the notification subscription is active. + type: boolean + apiVersion: + description: The API version of the notification to send. + format: int32 + type: integer + description: + description: |- + A description of the notification subscription configuration. + >Required when creating a configuration, forbidden when updating a configuration. + type: string + eventConfigs: + description: The types of events whose notifications apply to this configuration. + items: + $ref: '#/components/schemas/NotificationEventConfiguration' + type: array + notificationId: + description: |- + The ID of the configuration. + >Required if updating an existing configuration, ignored during the creation of a configuration. + format: int64 + type: integer + notifyPassword: + description: The password to use when accessing the notifyURL with the specified username. + type: string + notifyURL: + description: The URL to which the notifications are to be sent. + type: string + notifyUsername: + description: The username to use when accessing the notifyURL. + type: string + sslProtocol: + description: |- + The SSL protocol employed by the endpoint. + >Permitted values: `SSL`, `SSLv3`, `SSLInsecureCiphers`, `TLS`, `TLSv10`, `TLSv10InsecureCiphers`, `TLSv11`, `TLSv12`. + enum: + - SSL + - SSLInsecureCiphers + - SSLv3 + - TLS + - TLSv10 + - TLSv10InsecureCiphers + - TLSv11 + - TLSv12 + type: string + required: + - eventConfigs + - notifyURL + NotificationEventConfiguration: + properties: + eventType: + description: |- + The type of event triggering the notification. + >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`. + enum: + - ACCOUNT_CREATED + - ACCOUNT_HOLDER_CREATED + - ACCOUNT_HOLDER_LIMIT_REACHED + - ACCOUNT_HOLDER_PAYOUT + - ACCOUNT_HOLDER_STATUS_CHANGE + - ACCOUNT_HOLDER_UPDATED + - ACCOUNT_HOLDER_VERIFICATION + - ACCOUNT_UPDATED + - BENEFICIARY_SETUP + - COMPENSATE_NEGATIVE_BALANCE + - PAYMENT_FAILURE + - REPORT_AVAILABLE + - SCHEDULED_REFUNDS + - TRANSFER_FUNDS + type: string + includeMode: + description: |- + Indicates whether the specified eventType is to be sent to the endpoint or all events other than the specified eventType (and other specified eventTypes) are to be sent. + >Permitted values: `INCLUDE`, `EXCLUDE`. + >- `INCLUDE`: send the specified eventType. + >- `EXCLUDE`: send all eventTypes other than the specified eventType (and other eventTypes marked with `EXCLUDE`). + enum: + - EXCLUDE + - INCLUDE + type: string + required: + - eventType + - includeMode + TestNotificationConfigurationRequest: + properties: + eventTypes: + description: |- + The event types to test. If left blank, then all of the configured event types will be tested. + >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`. + items: + enum: + - ACCOUNT_CREATED + - ACCOUNT_HOLDER_CREATED + - ACCOUNT_HOLDER_LIMIT_REACHED + - ACCOUNT_HOLDER_PAYOUT + - ACCOUNT_HOLDER_STATUS_CHANGE + - ACCOUNT_HOLDER_UPDATED + - ACCOUNT_HOLDER_VERIFICATION + - ACCOUNT_UPDATED + - BENEFICIARY_SETUP + - COMPENSATE_NEGATIVE_BALANCE + - PAYMENT_FAILURE + - REPORT_AVAILABLE + - SCHEDULED_REFUNDS + - TRANSFER_FUNDS + type: string + type: array + notificationId: + description: The ID of the notification subscription configuration to be tested. + format: int64 + type: integer + required: + - notificationId + TestNotificationConfigurationResponse: + properties: + errorMessages: + description: Any error messages encountered. + items: + type: string + type: array + eventTypes: + description: |- + The event types that were tested. + >Permitted values: `ACCOUNT_HOLDER_CREATED`, `ACCOUNT_CREATED`, `ACCOUNT_UPDATED`, `ACCOUNT_HOLDER_UPDATED`, `ACCOUNT_HOLDER_STATUS_CHANGE`, `ACCOUNT_HOLDER_VERIFICATION`, `ACCOUNT_HOLDER_LIMIT_REACHED`, `ACCOUNT_HOLDER_PAYOUT`, `PAYMENT_FAILURE`, `SCHEDULED_REFUNDS`, `REPORT_AVAILABLE`, `TRANSFER_FUNDS`, `BENEFICIARY_SETUP`, `COMPENSATE_NEGATIVE_BALANCE`. + items: + enum: + - ACCOUNT_CREATED + - ACCOUNT_HOLDER_CREATED + - ACCOUNT_HOLDER_LIMIT_REACHED + - ACCOUNT_HOLDER_PAYOUT + - ACCOUNT_HOLDER_STATUS_CHANGE + - ACCOUNT_HOLDER_UPDATED + - ACCOUNT_HOLDER_VERIFICATION + - ACCOUNT_UPDATED + - BENEFICIARY_SETUP + - COMPENSATE_NEGATIVE_BALANCE + - PAYMENT_FAILURE + - REPORT_AVAILABLE + - SCHEDULED_REFUNDS + - TRANSFER_FUNDS + type: string + type: array + exchangeMessages: + description: The notification message and related response messages. + items: + $ref: '#/components/schemas/ExchangeMessage' + type: array + notificationId: + description: The ID of the notification subscription configuration. + format: int64 + type: integer + okMessages: + description: A list of messages describing the testing steps. + items: + type: string + type: array + pspReference: + description: The reference of a request. Can be used to uniquely identify the request. + type: string + submittedAsync: + description: |- + Indicates whether the request is processed synchronously or asynchronously. Depending on the request's marketplace settings, the following scenarios may be applied: + * **sync:** The processing of the request is immediately attempted; it may result in an error if the providing service is unavailable. + * **async:** The request is queued and will be executed when the providing service is available in the order in which the requests are received. + * **asyncOnError:** The processing of the request is immediately attempted, but if the providing service is unavailable, the request is scheduled in a queue. + type: boolean + required: + - pspReference + - submittedAsync + - notificationId + - eventTypes + - okMessages + - exchangeMessages + UpdateNotificationConfigurationRequest: + properties: + configurationDetails: + description: Details of the notification subscription configuration to be updated. + $ref: '#/components/schemas/NotificationConfigurationDetails' + required: + - configurationDetails diff --git a/specs/3.0/PayoutService-v30.yaml b/specs/3.0/PayoutService-v30.yaml new file mode 100644 index 0000000..b8611bf --- /dev/null +++ b/specs/3.0/PayoutService-v30.yaml @@ -0,0 +1,1201 @@ +openapi: 3.0.0 +servers: + - url: 'https://pal-test.adyen.com/pal/servlet/Payout/v30' +info: + version: '30' + title: Adyen Payout Service + description: |- + 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' + contact: + name: Adyen Support + url: 'https://support.adyen.com/' + email: support@adyen.com +x-groups: + - Initialization + - Reviewing + - Instant payouts +paths: + /confirmThirdParty: + post: + summary: Confirms a payout. + description: |- + Confirms a previously submitted payout. + + To cancel a payout, use the `/declineThirdParty` endpoint. + x-groupName: Reviewing + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ModifyRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ModifyResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /declineThirdParty: + post: + summary: Cancels a payout. + description: |- + Cancels a previously submitted payout. + + To confirm and send a payout, use the `/confirmThirdParty` endpoint. + x-groupName: Reviewing + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ModifyRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/ModifyResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /payout: + post: + summary: Pay out directly. + description: 'With this call, you can pay out to your customers, and funds will be made available within 30 minutes on the cardholder''s bank account (this is dependent on whether the issuer supports this functionality). Instant card payouts are only supported for Visa and Mastercard cards.' + x-groupName: Instant payouts + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PayoutRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/PayoutResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /storeDetail: + post: + summary: Stores payout details. + description: Stores payment details under the `PAYOUT` recurring contract. These payment details can be used later to submit a payout via the `/submitThirdParty` call. + x-groupName: Initialization + x-sortIndex: 2 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StoreDetailRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/StoreDetailResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /storeDetailAndSubmitThirdParty: + post: + summary: Stores details and submits a payout. + description: |- + Submits a payout and stores its details for subsequent payouts. + + The submitted payout must be confirmed or declined either by a reviewer or via `/confirmThirdParty` or `/declineThirdParty` calls. + x-groupName: Initialization + x-sortIndex: 1 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/StoreDetailAndSubmitRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/StoreDetailAndSubmitResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. + /submitThirdParty: + post: + summary: Submits a payout. + description: |- + Submits a payout using the previously stored payment details. To store payment details, use the `/storeDetail` API call. + + The submitted payout must be confirmed or declined either by a reviewer or via `/confirmThirdParty` or `/declineThirdParty` calls. + x-groupName: Initialization + x-sortIndex: 3 + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitRequest' + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/SubmitResponse' + description: OK - the request has succeeded. + '400': + description: Bad Request - a problem reading or understanding the request. + '401': + description: Unauthorized - authentication required. + '403': + description: Forbidden - insufficient permissions to process the request. + '422': + description: Unprocessable Entity - a request validation error. + '500': + description: Internal Server Error - the server could not process the request. +components: + schemas: + Address: + properties: + city: + description: |- + The name of the city. + >Required if either houseNumberOrName, street, postalCode, or stateOrProvince are provided. + type: string + country: + description: |- + The two-character country code of the address + >The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL'). + type: string + houseNumberOrName: + description: The number or name of the house. + type: string + postalCode: + 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: |- + The abbreviation of the state or province. + >Two (2) characters for an address in the USA or Canada, or a maximum of three (3) characters for an address in all other countries. + >Required for an address in the USA or Canada if either houseNumberOrName, street, city, or postalCode are provided. + type: string + street: + description: |- + The name of the street. + >The house number should not be included in this field; it should be separately provided via `houseNumberOrName`. + >Required if either houseNumberOrName, city, postalCode, or stateOrProvince are provided. + type: string + required: + - country + Amount: + properties: + currency: + description: 'The three-character [ISO currency code](https://docs.adyen.com/developers/currency-codes).' + maxLength: 3 + minLength: 3 + type: string + value: + 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). + format: int64 + type: integer + required: + - value + - currency + BankAccount: + properties: + bankAccountNumber: + description: The bank account number (without separators). + type: string + bankCity: + description: The bank city. + type: string + bankLocationId: + description: The location id of the bank. The field value is `nil` in most cases. + type: string + bankName: + description: The name of the bank. + type: string + bic: + description: 'The [Business Identifier Code](https://en.wikipedia.org/wiki/ISO_9362) (BIC) is the SWIFT address assigned to a bank. The field value is `nil` in most cases.' + type: string + countryCode: + description: |- + Country code where the bank is located. + + A valid value is an ISO two-character country code (e.g. 'NL'). + type: string + iban: + description: 'The [International Bank Account Number](https://en.wikipedia.org/wiki/International_Bank_Account_Number) (IBAN).' + type: string + ownerName: + description: |- + The name of the bank account holder. + If you submit a name with non-Latin characters, we automatically replace some of them with corresponding Latin characters to meet the FATF recommendations. For example: + * χ12 is converted to ch12. + * üA is converted to euA. + * Peter Møller is converted to Peter Mller, because banks don't accept 'ø'. + After replacement, the ownerName must have at least three alphanumeric characters (A-Z, a-z, 0-9), and at least one of them must be a valid Latin character (A-Z, a-z). For example: + * John17 - allowed. + * J17 - allowed. + * 171 - not allowed. + * John-7 - allowed. + > If provided details don't match the required format, the response returns the error message: 203 'Invalid bank account holder name'. + type: string + taxId: + description: The bank account holder's tax ID. + type: string + BrowserInfo: + properties: + acceptHeader: + description: The accept header value of the shopper's browser. + maxLength: 50 + minLength: 10 + type: string + userAgent: + description: The user agent value of the shopper's browser. + maxLength: 50 + minLength: 10 + type: string + required: + - userAgent + - acceptHeader + 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: + * 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). + > When this value is returned in a response, it is always empty because it is not stored. + maxLength: 20 + minLength: 1 + type: string + expiryMonth: + description: |- + The card expiry month. + Format: 2 digits, zero-padded for single digits. For example: + * 03 = March + * 11 = November + maxLength: 2 + minLength: 1 + type: string + expiryYear: + description: |- + The card expiry year. + Format: 4 digits. For example: 2018 + maxLength: 4 + minLength: 4 + type: string + holderName: + description: 'The name of the cardholder, as printed on the card.' + maxLength: 50 + minLength: 1 + type: string + issueNumber: + description: The issue number of the card (for some UK debit cards only). + maxLength: 2 + minLength: 1 + type: string + number: + description: |- + The card number (4-19 characters). Do not use any separators. + When this value is returned in a response, only the last 4 digits of the card number are returned. + maxLength: 19 + minLength: 4 + type: string + startMonth: + description: The month component of the start date (for some UK debit cards only). + maxLength: 2 + minLength: 1 + type: string + startYear: + description: The year component of the start date (for some UK debit cards only). + maxLength: 4 + minLength: 4 + type: string + required: + - number + - expiryMonth + - expiryYear + - holderName + ForexQuote: + properties: + account: + description: The account name. + type: string + accountType: + description: The account type. + type: string + baseAmount: + description: The base amount. + $ref: '#/components/schemas/Amount' + basePoints: + description: The base points. + format: int32 + type: integer + buy: + description: The buy rate. + $ref: '#/components/schemas/Amount' + interbank: + description: The interbank amount. + $ref: '#/components/schemas/Amount' + reference: + description: The reference assigned to the forex quote request. + type: string + sell: + description: The sell rate. + $ref: '#/components/schemas/Amount' + signature: + description: The signature to validate the integrity. + type: string + source: + description: The source of the forex quote. + type: string + type: + description: The type of forex. + type: string + validTill: + description: The date until which the forex quote is valid. + format: date-time + type: string + required: + - validTill + - basePoints + FraudCheckResult: + properties: + accountScore: + description: The fraud score generated by the risk check. + format: int32 + type: integer + checkId: + description: The ID of the risk check. + format: int32 + type: integer + name: + description: The name of the risk check. + type: string + required: + - checkId + - name + - accountScore + FraudResult: + properties: + accountScore: + description: The total fraud score generated by the risk checks. + format: int32 + type: integer + results: + description: The result of the individual risk checks. + items: + $ref: '#/components/schemas/FraudCheckResult' + type: array + required: + - accountScore + FundSource: + properties: + additionalData: + additionalProperties: + type: string + description: a map of name/value pairs for passing in additional/industry-specific data + type: object + billingAddress: + description: the address where to send the invoice + $ref: '#/components/schemas/Address' + card: + description: a representation of a (credit or debit) card + $ref: '#/components/schemas/Card' + shopperEmail: + description: the email address of the person + type: string + shopperName: + description: the name of the person + $ref: '#/components/schemas/Name' + telephoneNumber: + description: the telephone number of the person + type: string + Installments: + properties: + value: + description: |- + Defines the number of installments. Its value needs to be greater than zero. + + Usually, the maximum allowed number of installments is capped. For example, it may not be possible to split a payment in more than 24 installments. The acquirer sets this upper limit, so its value may vary. + format: int32 + type: integer + required: + - value + ModifyRequest: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be required for a particular payout request.' + type: object + merchantAccount: + description: 'The merchant account identifier, with which you want to process the transaction.' + type: string + originalReference: + description: The PSP reference received in the `/submitThirdParty` response. + type: string + required: + - merchantAccount + - originalReference + 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. + type: string + response: + description: |- + The response: + * In case of success, it is either `payout-confirm-received` or `payout-decline-received`. + * In case of an error, an informational message is returned. + type: string + required: + - pspReference + - response + Name: + properties: + firstName: + description: The first name. + type: string + gender: + description: |- + The gender. + >The following values are permitted: `MALE`, `FEMALE`, `UNKNOWN`. + enum: + - MALE + - FEMALE + - UNKNOWN + maxLength: 1 + minLength: 1 + type: string + infix: + description: |- + The name's infix, if applicable. + >A maximum length of twenty (20) characters is imposed. + type: string + lastName: + description: The last name. + type: string + required: + - firstName + - lastName + - gender + 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). + 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).' + $ref: '#/components/schemas/Amount' + bankAccount: + description: |- + The details of the bank account, from which the payment should be made. + > 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. + $ref: '#/components/schemas/Address' + browserInfo: + description: The shopper's browser information. + $ref: '#/components/schemas/BrowserInfo' + captureDelayHours: + description: 'The delay between the authorisation and scheduled auto-capture, specified in hours.' + format: int32 + type: integer + card: + description: |- + A container for card data. + > Either `bankAccount` or `card` field must be provided in a payment request. + $ref: '#/components/schemas/Card' + dateOfBirth: + description: |- + The shopper's date of birth. + + Format [ISO-8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DD + format: date-time + type: string + dccQuote: + description: The forex quote as returned in the response of the forex service. + $ref: '#/components/schemas/ForexQuote' + deliveryAddress: + description: The address where the purchased goods should be delivered. + $ref: '#/components/schemas/Address' + deliveryDate: + description: |- + The date and time the purchased goods should be delivered. + + Format [ISO 8601](https://www.w3.org/TR/NOTE-datetime): YYYY-MM-DDThh:mm:ss.sssTZD + + Example: 2017-07-17T13:42:40.428+01:00 + 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).' + type: string + entityType: + description: The type of the entity the payment is processed for. + enum: + - NaturalPerson + - CompanyName + 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 + fundSource: + description: The person or entity funding the money. + $ref: '#/components/schemas/FundSource' + installments: + description: 'Contains installment settings. For more information, refer to [Installments](https://docs.adyen.com/developers/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.' + type: string + merchantAccount: + description: 'The merchant account identifier, with which you want to process the transaction.' + type: string + 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. + 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" + type: object + mpiData: + description: Authentication data produced by an MPI (Mastercard SecureCode or Verified By Visa). + $ref: '#/components/schemas/ThreeDSecureData' + nationality: + description: The two-character country code of the shopper's nationality. + maxLength: 2 + type: string + orderReference: + description: The order reference to link multiple partial payments. + 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).' + $ref: '#/components/schemas/Recurring' + recurringProcessingModel: + description: |- + Defines a recurring payment type. + Allowed values: + * `Subscription` – A transaction for a fixed or variable amount, which follows a fixed schedule. + * `CardOnFile` – Card details are stored to enable one-click or omnichannel journeys, or simply to streamline the checkout process. Any subscription not following a fixed schedule is also considered a card-on-file transaction. + enum: + - CardOnFile + - Subscription + type: string + reference: + description: |- + The reference to uniquely identify a payment. This reference is used in all communication with you about the payment status. We recommend using a unique value per payment; however, it is not a requirement. + If you need to provide multiple references for a transaction, separate them with hyphens ("-"). + Maximum length: 80 characters. + type: string + selectedBrand: + description: |- + Some payment methods require defining a value for this field to specify how to process the transaction. + + For the Bancontact payment method, it can be set to: + * `maestro` (default), to be processed like a Maestro card, or + * `bcmc`, to be processed like a Bancontact card. + type: string + selectedRecurringDetailReference: + description: The `recurringDetailReference` you want to use for this payment. The value `LATEST` can be used to select the most recently stored recurring detail. + type: string + sessionId: + 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.' + type: string + shopperIP: + description: |- + The shopper's IP address. We recommend that you provide this data, as it is used in a number of risk checks (for instance, number of payment attempts or location-based checks). + > This field is mandatory for some merchants depending on your business model. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new). + type: string + shopperInteraction: + description: |- + Specifies the sales channel, through which the shopper gives their card details, and whether the shopper is a returning customer. + For the web service API, Adyen assumes Ecommerce shopper interaction by default. + + This field has the following possible values: + * `Ecommerce` - Online transactions where the cardholder is present (online). For better authorisation rates, we recommend sending the card security code (CSC) along with the request. + * `ContAuth` - Card on file and/or subscription transactions, where the cardholder is known to the merchant (returning customer). If the shopper is present (online), you can supply also the CSC to improve authorisation (one-click payment). + * `Moto` - Mail-order and telephone-order transactions where the shopper is in contact with the merchant via email or telephone. + * `POS` - Point-of-sale transactions where the shopper is physically present to make a payment using a secure payment terminal. + enum: + - Ecommerce + - ContAuth + - Moto + - POS + type: string + shopperLocale: + description: The combination of a language code and a country code to specify the language to be used in the payment. + type: string + shopperName: + description: The shopper's full name and gender (if specified). + $ref: '#/components/schemas/Name' + shopperReference: + description: |- + The shopper's reference to uniquely identify this shopper (e.g. user ID or account ID). + > This field is required for recurring payments. + type: string + shopperStatement: + description: The text to appear on the shopper's bank statement. + type: string + socialSecurityNumber: + description: The shopper's social security number. + type: string + store: + description: 'The physical store, for which this payment is processed.' + maxLength: 16 + minLength: 1 + type: string + telephoneNumber: + description: The shopper's telephone number. + type: string + totalsGroup: + description: 'The reference value to aggregate sales totals in reporting. When not specified, the store field is used (if available).' + maxLength: 16 + minLength: 1 + type: string + required: + - merchantAccount + - reference + - amount + 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**.' + type: object + authCode: + description: |- + Authorisation code: + * When the payment is authorised successfully, this field holds the authorisation code for the payment. + * When the payment is not authorised, this field is empty. + type: string + dccAmount: + description: |- + Includes the currency of the conversion and the value of the transaction. + > This value only applies if you have implemented Dynamic Currency Conversion. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new). + $ref: '#/components/schemas/Amount' + dccSignature: + description: |- + Cryptographic signature used to verify `dccQuote`. + > This value only applies if you have implemented Dynamic Currency Conversion. For more information, [contact Support](https://support.adyen.com/hc/en-us/requests/new). + type: string + fraudResult: + description: The fraud result properties of the payment. + $ref: '#/components/schemas/FraudResult' + issuerUrl: + description: |- + The URL to direct the shopper to. + > In case of SecurePlus, do not redirect a shopper to this URL. + type: string + md: + description: The payment session. + type: string + paRequest: + 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). + 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. + + > `pspReference` is returned only for non-redirect payment methods. + type: string + refusalReason: + description: |- + If the payment's authorisation is refused or an error occurs during authorisation, this field holds Adyen's mapped reason for the refusal or a description of the error. + + When a transaction fails, the authorisation response includes `resultCode` and `refusalReason` values. + type: string + resultCode: + description: |- + The result of the payment. Possible values: + + * **Authorised** – Indicates the payment authorisation was successfully completed. This state serves as an indicator to proceed with the delivery of goods and services. This is a final state. + * **Refused** – Indicates the payment was refused. The reason is given in the `refusalReason` field. This is a final state. + * **RedirectShopper** – Indicates the shopper should be redirected to an external web page or app to complete the authorisation. For more information on handling a redirect, refer to [Handling a redirect](https://docs.adyen.com/developers/checkout/api-integration/make-a-payment#idealpayments). + * **Received** – Indicates the payment has successfully been received by Adyen, and will be processed. This is the initial state for all payments. + * **Cancelled** – Indicates the payment has been cancelled (either by the shopper or the merchant) before processing was completed. This is a final state. + * **Pending** – Indicates that it is not possible to obtain the final status of the payment. This can happen if the systems providing final status information for the payment are unavailable, or if the shopper needs to take further action to complete the payment. For more information on handling a pending payment, refer to [Payments with pending status](https://docs.adyen.com/developers/development-resources/payments-with-pending-status). + * **Error** – Indicates an error occurred during processing of the payment. The reason is given in the `refusalReason` field. This is a final state. + enum: + - Authorised + - PartiallyAuthorised + - Refused + - Error + - Cancelled + - Received + - RedirectShopper + type: string + Recurring: + properties: + contract: + 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,RECURRING` – Payment details can be used regardless of whether the shopper is on your site or not. + * `PAYOUT` – Payment details can be used to [make a payout](https://docs.adyen.com/developers/features/third-party-payouts). + enum: + - ONECLICK + - RECURRING + - PAYOUT + type: string + recurringDetailName: + description: A descriptive name for this detail. + type: string + tokenService: + description: The name of the token service. + enum: + - VISATOKENSERVICE + - MCTOKENSERVICE + type: string + StoreDetailAndSubmitRequest: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be required for a particular request.' + type: object + amount: + description: A container object for the payable amount information of the transaction. + $ref: '#/components/schemas/Amount' + bank: + description: |- + A container for bank account data. + > This field is mandatory if `card` is not provided. + $ref: '#/components/schemas/BankAccount' + billingAddress: + description: The billing address. + $ref: '#/components/schemas/Address' + card: + description: |- + A container for card data. + > This field is mandatory if `bank` is not provided. + $ref: '#/components/schemas/Card' + dateOfBirth: + description: |- + The date of birth. + Format: [ISO-8601](https://www.w3.org/TR/NOTE-datetime); example: YYYY-MM-DD + For Paysafecard it must be the same as used when registering the Paysafecard account. + > This field is mandatory for natural persons. + format: date-time + type: string + entityType: + description: The type of the entity the payout is processed for. + enum: + - NaturalPerson + - Company + 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 + merchantAccount: + description: 'The merchant account identifier, with which you want to process the transaction.' + type: string + nationality: + description: |- + The shopper's nationality. + + A valid value is an ISO 2-character country code (e.g. 'NL'). + maxLength: 2 + type: string + recurring: + description: |- + A container for the type of recurring contract to be retrieved. + + The recurring.contract must be set to `PAYOUT` + $ref: '#/components/schemas/Recurring' + reference: + description: 'The merchant reference for this payment. This reference will be used in all communication to the merchant about the status of the payout. Although it is a good idea to make sure it is unique, this is not a requirement.' + type: string + selectedBrand: + description: |- + The name of the brand to make a payout to. + + For Paysafecard it must be set to `paysafecard`. + type: string + shopperEmail: + description: The shopper's email address. + type: string + shopperName: + description: |- + The shopper's name. + + When the `entityType` is `Company`, the `shopperName.lastName` must contain the company name. + $ref: '#/components/schemas/Name' + shopperReference: + description: The shopper's reference for the payment transaction. + type: string + shopperStatement: + description: The description of this payout. This description is shown on the bank statement of the shopper (if this is supported by the chosen payment method). + type: string + socialSecurityNumber: + description: The shopper's social security number. + type: string + required: + - merchantAccount + - shopperEmail + - shopperReference + - recurring + - dateOfBirth + - nationality + - entityType + - reference + - amount + StoreDetailAndSubmitResponse: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be returned in a particular response.' + type: object + pspReference: + description: A new reference to uniquely identify this request. + type: string + refusalReason: + description: 'In case of refusal, an informational message for the reason.' + type: string + resultCode: + description: |- + The response: + + * In case of success is payout-submit-received. + * In case of an error, an informational message is returned. + type: string + required: + - pspReference + - resultCode + StoreDetailRequest: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be required for a particular request.' + type: object + bank: + description: |- + A container for bank account data. + > This field is mandatory if `card` is not provided. + $ref: '#/components/schemas/BankAccount' + billingAddress: + description: The billing address. + $ref: '#/components/schemas/Address' + card: + description: |- + A container for card data. + > This field is mandatory if `bank` is not provided. + $ref: '#/components/schemas/Card' + dateOfBirth: + description: |- + The date of birth. + Format: [ISO-8601](https://www.w3.org/TR/NOTE-datetime); example: YYYY-MM-DD + For Paysafecard it must be the same as used when registering the Paysafecard account. + > This field is mandatory for natural persons. + format: date-time + type: string + entityType: + description: The type of the entity the payout is processed for. + enum: + - NaturalPerson + - Company + 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 + merchantAccount: + description: 'The merchant account identifier, with which you want to process the transaction.' + type: string + nationality: + description: |- + The shopper's nationality. + + A valid value is an ISO 2-character country code (e.g. 'NL'). + maxLength: 2 + type: string + recurring: + description: |- + A container for the type of recurring contract to be retrieved. + + The recurring.contract must be set to `PAYOUT` + $ref: '#/components/schemas/Recurring' + selectedBrand: + description: |- + The name of the brand to make a payout to. + + For Paysafecard it must be set to `paysafecard`. + type: string + shopperEmail: + description: The shopper's email address. + type: string + shopperName: + description: |- + The shopper's name. + + When the `entityType` is `Company`, the `shopperName.lastName` must contain the company name. + $ref: '#/components/schemas/Name' + shopperReference: + description: The shopper's reference for the payment transaction. + type: string + socialSecurityNumber: + description: The shopper's social security number. + type: string + required: + - merchantAccount + - shopperEmail + - shopperReference + - recurring + - dateOfBirth + - nationality + - entityType + StoreDetailResponse: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be returned in a particular response.' + type: object + pspReference: + description: A new reference to uniquely identify this request. + type: string + recurringDetailReference: + description: The token which you can use later on for submitting the payout. + type: string + resultCode: + description: The result code of the transaction. `Success` indicates that the details were stored successfully. + type: string + required: + - pspReference + - recurringDetailReference + - resultCode + SubmitRequest: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be required for a particular request.' + type: object + amount: + description: A container object for the payable amount information of the transaction. + $ref: '#/components/schemas/Amount' + dateOfBirth: + description: |- + The date of birth. + Format: ISO-8601; example: YYYY-MM-DD + + For Paysafecard it must be the same as used when registering the Paysafecard account. + + > 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 + entityType: + description: |- + The type of the entity the payout is processed for. + + Allowed values: + * NaturalPerson + * Company + > This field is required to update the existing `entityType` that is associated with this recurring contract. + enum: + - NaturalPerson + - Company + 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 + merchantAccount: + description: The merchant account identifier you want to process the transaction request with. + type: string + nationality: + description: |- + The shopper's nationality. + + A valid value is an ISO 2-character country code (e.g. 'NL'). + + > This field is required to update the existing nationality that is associated with this recurring contract. + type: string + recurring: + description: |- + A container for the type of recurring contract to be retrieved. + + The `recurring.contract` must be set to "PAYOUT". + $ref: '#/components/schemas/Recurring' + reference: + description: 'The merchant reference for this payout. This reference will be used in all communication to the merchant about the status of the payout. Although it is a good idea to make sure it is unique, this is not a requirement.' + type: string + selectedRecurringDetailReference: + description: |- + This is the `recurringDetailReference` you want to use for this payout. + + You can use the value LATEST to select the most recently used recurring detail. + type: string + shopperEmail: + description: The shopper's email address. + type: string + shopperName: + description: |- + The shopper's name. + + In case the `entityType` is `Company`, the `shopperName.lastName` must contain the company name. + + > This field is required to update the existing `shopperName` associated with a recurring contract. + $ref: '#/components/schemas/Name' + shopperReference: + description: The shopper's reference for the payout transaction. + type: string + shopperStatement: + description: The description of this payout. This description is shown on the bank statement of the shopper (if this is supported by the chosen payment method). + type: string + socialSecurityNumber: + description: The shopper's social security number. + type: string + required: + - merchantAccount + - reference + - amount + - shopperEmail + - shopperReference + - recurring + - selectedRecurringDetailReference + SubmitResponse: + properties: + additionalData: + additionalProperties: + type: string + description: 'This field contains additional data, which may be returned in a particular response.' + type: object + pspReference: + description: A new reference to uniquely identify this request. + type: string + refusalReason: + description: 'In case of refusal, an informational message for the reason.' + type: string + resultCode: + description: |- + The response: + * In case of success, it is `payout-submit-received`. + * In case of an error, an informational message is returned. + type: string + required: + - pspReference + - resultCode + ThreeDSecureData: + properties: + authenticationResponse: + description: The authentication response if the shopper was redirected. + 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. + type: string + directoryResponse: + description: The enrollment response from the 3D directory server. + enum: + - 'Y' + - 'N' + - U + - E + type: string + eci: + description: The electronic commerce indicator. + type: string + xid: + description: 'The transaction identifier (base64 encoded, 20 bytes in a decoded form).' + format: byte + type: string