Adyen debitAccountHolder API

openapi: 3.1.0
info:
  version: '6'
  x-publicVersion: true
  title: Adyen Account acceptDispute debitAccountHolder API
  description: "This API is used for the classic integration. If you are just starting your implementation, refer to our [new integration guide](https://docs.adyen.com/marketplaces-and-platforms) instead.\n\nThe Account API provides endpoints for managing account-related entities on your platform. These related entities include account holders, accounts, bank accounts, shareholders, and verification-related documents. The management operations include actions such as creation, retrieval, updating, and deletion of them.\n\nFor more information, refer to our [documentation](https://docs.adyen.com/marketplaces-and-platforms/classic).\n## Authentication\nYour Adyen contact will provide your API credential and an API key. To connect to the API, add an `X-API-Key` header with the API key as the value, for example:\n\n ```\ncurl\n-H \"Content-Type: application/json\" \\\n-H \"X-API-Key: YOUR_API_KEY\" \\\n...\n```\n\nAlternatively, you can use the username and password to connect to the API using basic authentication. For example:\n\n```\ncurl\n-U \"ws@MarketPlace.YOUR_PLATFORM_ACCOUNT\":\"YOUR_WS_PASSWORD\" \\\n-H \"Content-Type: application/json\" \\\n...\n```\nWhen going live, you need to generate new web service user credentials to access the [live endpoints](https://docs.adyen.com/development-resources/live-endpoints).\n\n## Versioning\nThe Account API supports [versioning](https://docs.adyen.com/development-resources/versioning) using a version suffix in the endpoint URL. This suffix has the following format: \"vXX\", where XX is the version number.\n\nFor example:\n```\nhttps://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder\n```"
  x-timestamp: '2023-05-30T15:27:20Z'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
servers:
- url: https://cal-test.adyen.com/cal/services/Account/v6
tags:
- name: debitAccountHolder
paths:
  /debitAccountHolder:
    post:
      tags:
      - debitAccountHolder
      summary: Adyen Send a Direct Debit Request
      description: "Sends a direct debit request to an account holder's bank account. If the direct debit is successful, the funds are settled in the accounts specified in the split instructions. Adyen sends the result of the direct debit in a [`DIRECT_DEBIT_INITIATED`](https://docs.adyen.com/api-explorer/#/NotificationService/latest/post/DIRECT_DEBIT_INITIATED) notification webhook.\n\n To learn more about direct debits, see [Top up accounts](https://docs.adyen.com/marketplaces-and-platforms/classic/top-up-accounts)."
      operationId: post-debitAccountHolder
      x-groupName: General
      x-sortIndex: 8
      x-methodName: debitAccountHolder
      security:
      - BasicAuth: []
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              debit-account-holder:
                $ref: '#/components/examples/post-debitAccountHolder-debit-account-holder'
            schema:
              $ref: '#/components/schemas/DebitAccountHolderRequest'
      responses:
        '200':
          content:
            application/json:
              examples:
                debit-account-holder:
                  $ref: '#/components/examples/post-debitAccountHolder-debit-account-holder-200'
              schema:
                $ref: '#/components/schemas/DebitAccountHolderResponse'
          description: OK - the request has succeeded.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DebitAccountHolderResponse'
              examples:
                post-debitAccountHolder202Example:
                  summary: Default post-debitAccountHolder 202 response
                  x-microcks-default: true
                  value:
                    accountHolderCode: CODE123
                    bankAccountUUID: '500123'
                    invalidFields:
                    - example_value
                    merchantReferences:
                    - REF-001
                    pspReference: REF-001
                    resultCode: CODE123
          description: Accepted - the request has been accepted for processing, but the processing has not been completed.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-debitAccountHolder400Example:
                  summary: Default post-debitAccountHolder 400 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Bad Request - a problem reading or understanding the request.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-debitAccountHolder401Example:
                  summary: Default post-debitAccountHolder 401 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-debitAccountHolder403Example:
                  summary: Default post-debitAccountHolder 403 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-debitAccountHolder422Example:
                  summary: Default post-debitAccountHolder 422 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceError'
              examples:
                post-debitAccountHolder500Example:
                  summary: Default post-debitAccountHolder 500 response
                  x-microcks-default: true
                  value:
                    errorCode: CODE123
                    errorType: standard
                    message: example_value
                    pspReference: REF-001
                    status: 500
          description: Internal Server Error - the server could not process the request.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    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'
      type: object
    FieldType:
      properties:
        field:
          description: The full name of the property.
          type: string
        fieldName:
          description: The type of the field.
          enum:
          - accountCode
          - accountHolderCode
          - accountHolderDetails
          - accountNumber
          - accountStateType
          - accountStatus
          - accountType
          - address
          - balanceAccount
          - balanceAccountActive
          - balanceAccountCode
          - balanceAccountId
          - bankAccount
          - bankAccountCode
          - bankAccountName
          - bankAccountUUID
          - bankBicSwift
          - bankCity
          - bankCode
          - bankName
          - bankStatement
          - branchCode
          - businessContact
          - cardToken
          - checkCode
          - city
          - companyRegistration
          - constitutionalDocument
          - controller
          - country
          - countryCode
          - currency
          - currencyCode
          - dateOfBirth
          - description
          - destinationAccountCode
          - document
          - documentContent
          - documentExpirationDate
          - documentIssuerCountry
          - documentIssuerState
          - documentName
          - documentNumber
          - documentType
          - doingBusinessAs
          - drivingLicence
          - drivingLicenceBack
          - drivingLicenceFront
          - drivingLicense
          - email
          - firstName
          - formType
          - fullPhoneNumber
          - gender
          - hopWebserviceUser
          - houseNumberOrName
          - iban
          - idCard
          - idCardBack
          - idCardFront
          - idNumber
          - identityDocument
          - individualDetails
          - infix
          - jobTitle
          - lastName
          - lastReviewDate
          - legalArrangement
          - legalArrangementCode
          - legalArrangementEntity
          - legalArrangementEntityCode
          - legalArrangementLegalForm
          - legalArrangementMember
          - legalArrangementMembers
          - legalArrangementName
          - legalArrangementReference
          - legalArrangementRegistrationNumber
          - legalArrangementTaxNumber
          - legalArrangementType
          - legalBusinessName
          - legalEntity
          - legalEntityType
          - logo
          - merchantAccount
          - merchantCategoryCode
          - merchantHouseNumber
          - merchantReference
          - microDeposit
          - name
          - nationality
          - originalReference
          - ownerCity
          - ownerCountryCode
          - ownerDateOfBirth
          - ownerHouseNumberOrName
          - ownerName
          - ownerPostalCode
          - ownerState
          - ownerStreet
          - passport
          - passportNumber
          - payoutMethod
          - payoutMethodCode
          - payoutSchedule
          - pciSelfAssessment
          - personalData
          - phoneCountryCode
          - phoneNumber
          - postalCode
          - primaryCurrency
          - reason
          - registrationNumber
          - returnUrl
          - schedule
          - shareholder
          - shareholderCode
          - shareholderCodeAndSignatoryCode
          - shareholderCodeOrSignatoryCode
          - shareholderType
          - shareholderTypes
          - shopperInteraction
          - signatory
          - signatoryCode
          - socialSecurityNumber
          - sourceAccountCode
          - splitAccount
          - splitConfigurationUUID
          - splitCurrency
          - splitValue
          - splits
          - stateOrProvince
          - status
          - stockExchange
          - stockNumber
          - stockTicker
          - store
          - storeDetail
          - storeName
          - storeReference
          - street
          - taxId
          - tier
          - tierNumber
          - transferCode
          - ultimateParentCompany
          - ultimateParentCompanyAddressDetails
          - ultimateParentCompanyAddressDetailsCountry
          - ultimateParentCompanyBusinessDetails
          - ultimateParentCompanyBusinessDetailsLegalBusinessName
          - ultimateParentCompanyBusinessDetailsRegistrationNumber
          - ultimateParentCompanyCode
          - ultimateParentCompanyStockExchange
          - ultimateParentCompanyStockNumber
          - ultimateParentCompanyStockNumberOrStockTicker
          - ultimateParentCompanyStockTicker
          - unknown
          - value
          - verificationType
          - virtualAccount
          - visaNumber
          - webAddress
          - year
          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
      type: object
    DebitAccountHolderRequest:
      properties:
        accountHolderCode:
          description: The code of the account holder.
          type: string
        amount:
          description: The amount to be debited from the account holder's bank account.
          $ref: '#/components/schemas/Amount'
        bankAccountUUID:
          description: The Adyen-generated unique alphanumeric identifier (UUID) of the account holder's bank account.
          type: string
        description:
          description: 'A description of the direct debit. Maximum length: 35 characters.


            Allowed characters: **a-z**, **A-Z**, **0-9**, and special characters **/?:().,''+ ";**.'
          maxLength: 35
          type: string
        merchantAccount:
          description: Your merchant account.
          type: string
        splits:
          description: Contains instructions on how to split the funds between the accounts in your platform. The request must have at least one split item.
          items:
            $ref: '#/components/schemas/Split'
          type: array
      required:
      - accountHolderCode
      - bankAccountUUID
      - amount
      - splits
      - merchantAccount
      type: object
    DebitAccountHolderResponse:
      properties:
        accountHolderCode:
          description: The code of the account holder.
          type: string
        bankAccountUUID:
          description: The Adyen-generated unique alphanumeric identifier (UUID) of the account holder's bank account.
          type: string
        invalidFields:
          x-addedInVersion: '5'
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        merchantReferences:
          description: List of the `reference` values from the `split` array in the request.
          items:
            type: string
          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
      type: object
    Amount:
      properties:
        currency:
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      - currency
      type: object
    ServiceError:
      properties:
        errorCode:
          description: The error code mapped to the error message.
          type: string
        errorType:
          description: The category of the error.
          type: string
        message:
          description: A short explanation of the issue.
          type: string
        pspReference:
          description: The PSP reference of the payment.
          type: string
        status:
          description: The HTTP response status.
          format: int32
          type: integer
      type: object
    Split:
      properties:
        account:
          description: 'Unique identifier of the account where the split amount should be sent. This is required if `type` is **MarketPlace** or **BalanceAccount**.


            '
          type: string
        amount:
          description: The amount of this split.
          $ref: '#/components/schemas/SplitAmount'
        description:
          description: A description of this split.
          type: string
        reference:
          description: 'Your reference for the split, which you can use to link the split to other operations such as captures and refunds.


            This is required if `type` is **MarketPlace** or **BalanceAccount**. For the other types, we also recommend sending a reference so you can reconcile the split and the associated payment in the transaction overview and in the reports. If the reference is not provided, the split is reported as part of the aggregated [TransferBalance record type](https://docs.adyen.com/reporting/marketpay-payments-accounting-report) in Adyen for Platforms.'
          type: string
        type:
          description: 'The type of split.

            Possible values: **Default**, **PaymentFee**, **VAT**, **Commission**, **MarketPlace**, **BalanceAccount**, **Remainder**, **Surcharge**, **Tip**.'
          enum:
          - BalanceAccount
          - Commission
          - Default
          - MarketPlace
          - PaymentFee
          - PaymentFeeAcquiring
          - PaymentFeeAdyen
          - PaymentFeeAdyenCommission
          - PaymentFeeAdyenMarkup
          - PaymentFeeInterchange
          - PaymentFeeSchemeFee
          - Remainder
          - Surcharge
          - Tip
          - VAT
          - Verification
          type: string
      required:
      - amount
      - type
      type: object
    SplitAmount:
      properties:
        currency:
          description: 'The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).


            If this value is not provided, the currency in which the payment is made will be used.'
          maxLength: 3
          minLength: 3
          type: string
        value:
          description: The amount in [minor units](https://docs.adyen.com/development-resources/currency-codes).
          format: int64
          type: integer
      required:
      - value
      type: object
  examples:
    post-debitAccountHolder-debit-account-holder:
      summary: Send a bank account direct debit
      description: Example request to send a direct debit from a bank account
      value:
        accountHolderCode: ACCOUNT_HOLDER_CODE
        description: YOUR_DESCRIPTION
        bankAccountUUID: 000b81aa-ae7e-4492-aa7e-72b2129dce0c
        amount:
          value: 6200
          currency: USD
        merchantAccount: YOUR_MERCHANT_ACCOUNT
        splits:
        - amount:
            value: 6000
          type: MarketPlace
          account: '8535516988037431'
          reference: YOUR_SPLIT_REFERENCE_1
        - amount:
            value: 200
          type: Commission
          reference: YOUR_SPLIT_REFERENCE_2
    post-debitAccountHolder-debit-account-holder-200:
      summary: Direct debit request sent
      description: Example response for requesting a direct debit from a bank account
      value:
        pspReference: '8816480354727275'
        submittedAsync: 'false'
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
x-groups:
- Account holders
- Accounts
- Verification