From 49367fa5545dd462f75f30252e87fc3fd592f778 Mon Sep 17 00:00:00 2001 From: Aleksei Akimov Date: Fri, 1 Jun 2018 14:08:13 +0200 Subject: [PATCH] Update MarketPay specs --- specs/3.0/AccountService-v3.yaml | 210 +++++++++++++++---------------- 1 file changed, 103 insertions(+), 107 deletions(-) diff --git a/specs/3.0/AccountService-v3.yaml b/specs/3.0/AccountService-v3.yaml index f071a27..3e9e689 100644 --- a/specs/3.0/AccountService-v3.yaml +++ b/specs/3.0/AccountService-v3.yaml @@ -24,7 +24,7 @@ info: For example: ``` - https://cal-test.adyen.com/cal/services/Account/v3/createAccountHolder + https://cal-test.adyen.com/cal/services/Account/v4/createAccountHolder ``` termsOfService: 'https://docs.adyen.com/legal/terms-conditions' contact: @@ -225,7 +225,7 @@ paths: /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. + 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: @@ -312,7 +312,7 @@ paths: 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). + For further information regarding KYC Verification, please refer to [Verification checks](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks). x-groupName: Verification x-sortIndex: 2 requestBody: @@ -536,7 +536,7 @@ paths: 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). + For further information regarding KYC Verification, please refer to [Verification checks](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks). x-groupName: Verification x-sortIndex: 1 requestBody: @@ -606,7 +606,7 @@ components: description: |- The event. >Permitted values: `InactivateAccount`, `RefundNotPaidOutTransfers`. - Please refer to the KYC documentation for further information. + For more information, refer to [Verification checks](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks). enum: - InactivateAccount - RefundNotPaidOutTransfers @@ -654,7 +654,7 @@ components: 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). + > For comprehensive detail regarding the required `BankAccountDetail` fields, please refer to the [KYC Verification documentation](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks). items: $ref: '#/components/schemas/BankAccountDetail' type: array @@ -700,7 +700,7 @@ components: - email AccountHolderStatus: properties: - accountEvents: + events: description: A list of events scheduled for the account holder. items: $ref: '#/components/schemas/AccountEvent' @@ -729,7 +729,7 @@ components: - statusReason - processingState - payoutState - - accountEvents + - events AccountHolderStatusChangeNotification: properties: content: @@ -757,10 +757,10 @@ components: accountHolderCode: description: The code of the account holder. type: string - newAccountHolderStatus: + newStatus: description: The new status of the account holder. $ref: '#/components/schemas/AccountHolderStatus' - oldAccountHolderStatus: + oldStatus: description: The former status of the account holder. $ref: '#/components/schemas/AccountHolderStatus' reason: @@ -768,8 +768,8 @@ components: type: string required: - accountHolderCode - - oldAccountHolderStatus - - newAccountHolderStatus + - oldStatus + - newStatus - reason AccountHolderUpdateNotification: properties: @@ -820,7 +820,7 @@ components: AccountHolderVerificationNotificationContent: properties: accountHolderCode: - description: The code of the Account Holder. + description: The code of the account holder. type: string bankAccountUUID: description: The unique ID of the bank account that has been verified. @@ -861,15 +861,13 @@ components: 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. + 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. + 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. + description: The payout tier that the account holder occupies. format: int32 type: integer required: @@ -887,19 +885,13 @@ components: 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. + 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).' $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. + 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).' $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. + description: The processing tier that the account holder occupies. format: int32 type: integer required: @@ -965,7 +957,7 @@ components: accountNumber: description: |- The bank account number (without separators). - >Please refer to the KYC Verification section for details on field requirements. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on field requirements. type: string accountType: description: |- @@ -973,7 +965,7 @@ components: 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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on field requirements. type: string bankAccountName: description: The name of the bank account. @@ -981,81 +973,83 @@ components: 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 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 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 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.** + >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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + The branch code of the branch under which the bank account is registered. The value to be specified in this parameter depends on the country of the bank account: + * United States - Routing number + * United Kingdom - Sort code + * Germany - Bankleitzahl + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on field requirements. type: string ownerDateOfBirth: description: | @@ -1064,34 +1058,34 @@ components: 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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on field requirements. type: string primaryAccount: description: 'If set to true, the bank account is a primary account.' @@ -1100,14 +1094,14 @@ components: description: |- The tax ID number. - >Please refer to the KYC Verification section for details on field requirements. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on field requirements. type: string BusinessDetails: properties: @@ -1215,7 +1209,7 @@ components: - NonProfit type: string processingTier: - description: 'The starting [processing tier](https://docs.adyen.com/developers/marketpay/kyc-verification/verification-process) for the prospective account holder.' + description: 'The starting [processing tier](https://docs.adyen.com/developers/marketpay/onboarding-and-verification/verification-checks#tiers) for the prospective account holder.' format: int32 type: integer required: @@ -1251,7 +1245,7 @@ components: * **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: + verification: description: The details of KYC Verification of the account holder. $ref: '#/components/schemas/KYCVerificationResult' required: @@ -1260,7 +1254,7 @@ components: - accountHolderCode - accountHolderStatus - accountHolderDetails - - verificationResult + - verification CreateAccountRequest: properties: accountHolderCode: @@ -1352,14 +1346,14 @@ components: DocumentDetail: properties: accountHolderCode: - description: The code of Account Holder to which the document applies. + 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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-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. @@ -1367,15 +1361,15 @@ components: 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. + 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 the KYC Verification section for details on when each document type should 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 @@ -1394,10 +1388,10 @@ components: 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). + 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. + >Refer to the [Onboarding and verification](https://docs.adyen.com/developers/marketpay/onboarding-and-verification) section for details on when a document should be submitted in order to verify a shareholder. type: string required: - accountHolderCode @@ -1548,7 +1542,7 @@ components: * **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: + verification: description: The details of KYC Verification of the account holder. $ref: '#/components/schemas/KYCVerificationResult' required: @@ -1558,7 +1552,7 @@ components: - legalEntity - accountHolderStatus - accountHolderDetails - - verificationResult + - verification GetAccountHolderStatusResponse: properties: accountHolderCode: @@ -1628,26 +1622,31 @@ components: bankAccountUUID: description: The unique ID of the bank account to which the check applies. type: string - checkStatusData: + checks: description: A list of the checks and their statuses. items: $ref: '#/components/schemas/KYCCheckStatusData' type: array required: - - checkStatusData + - checks - bankAccountUUID KYCCheckResult: properties: - checkStatusData: + checks: description: A list of the checks and their statuses. items: $ref: '#/components/schemas/KYCCheckStatusData' type: array required: - - checkStatusData + - checks KYCCheckStatusData: properties: - checkStatus: + requiredFields: + description: A list of the fields required for execution of the check. + items: + type: string + type: array + status: description: |- The status of the check. >Permitted Values: `UNCHECKED`, `DATA_PROVIDED`, `PASSED`, `PENDING`, `AWAITING_DATA`, `RETRY_LIMIT_REACHED`, `INVALID_DATA`, `FAILED`. @@ -1662,7 +1661,10 @@ components: - RETRY_LIMIT_REACHED - UNCHECKED type: string - checkType: + summary: + description: A summary of the execution of the check. + $ref: '#/components/schemas/KYCCheckSummary' + type: description: |- The type of check. >Permitted Values: `COMPANY_VERIFICATION`, `IDENTITY_VERIFICATION`, `PASSPORT_VERIFICATION`, `BANK_ACCOUNT_VERIFICATION`, `NONPROFIT_VERIFICATION`. @@ -1673,17 +1675,9 @@ components: - 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 + - type + - status - summary - requiredFields KYCCheckSummary: @@ -1699,7 +1693,7 @@ components: - code KYCShareholderCheckResult: properties: - checkStatusData: + checks: description: A list of the checks and their statuses. items: $ref: '#/components/schemas/KYCCheckStatusData' @@ -1708,27 +1702,27 @@ components: description: The code of the shareholder to which the check applies. type: string required: - - checkStatusData + - checks - shareholderCode KYCVerificationResult: properties: - accountHolderCheckResult: + accountHolder: description: The result(s) of the checks on the account holder. $ref: '#/components/schemas/KYCCheckResult' - bankAccountCheckResult: + bankAccounts: description: The result(s) of the checks on the bank account(s). items: $ref: '#/components/schemas/KYCBankAccountCheckResult' type: array - shareholderCheckResult: + shareholders: description: The result(s) of the checks on the shareholder(s). items: $ref: '#/components/schemas/KYCShareholderCheckResult' type: array required: - - accountHolderCheckResult - - shareholderCheckResult - - bankAccountCheckResult + - accountHolder + - shareholders + - bankAccounts Name: properties: firstName: @@ -1858,7 +1852,7 @@ components: SuspendAccountHolderRequest: properties: accountHolderCode: - description: The code of the Account Holder to be suspended. + description: The code of the account holder to be suspended. type: string required: - accountHolderCode @@ -1884,14 +1878,14 @@ components: UnSuspendAccountHolderRequest: properties: accountHolderCode: - description: The code of the Account Holder to be reinstated. + 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. + 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. @@ -1959,14 +1953,14 @@ components: items: $ref: '#/components/schemas/FieldType' type: array - verificationResult: + verification: description: The details of KYC Verification of the account holder. $ref: '#/components/schemas/KYCVerificationResult' required: - pspReference - submittedAsync - accountHolderStatus - - verificationResult + - verification UpdateAccountHolderStateRequest: properties: accountHolderCode: @@ -2034,22 +2028,24 @@ components: 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. + 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**. + 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`. + Permitted values: `DEFAULT`, `HOLD`, `DAILY`, `WEEKLY`, `MONTHLY`. enum: - DAILY - DEFAULT