adyen-openapi/yaml/HopService-v5.yaml

openapi: 3.0.3
servers:
  - url: 'https://cal-test.adyen.com/cal/services/Hop/v5'
info:
  version: '5'
  title: 'Adyen for Platforms: Hosted Onboarding Page API'
  description: |-
    The Hosted Onboarding Page (HOP) API provides endpoints for using the Hosted Onboarding Page. The related entities include account holders only.
    For more information, refer to our [documentation](https://docs.adyen.com/platforms/onboarding-and-verification/hosted-onboarding-page).
    ## Authentication
    To connect to the HOP 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@MarketPlace.YourMarketPlace":"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/development-resources/live-endpoints).

    ## Versioning
    The HOP 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/Hop/v5/getOnboardingUrl
    ```
  termsOfService: 'https://www.adyen.com/legal/terms-and-conditions'
  contact:
    name: Adyen Support
    url: 'https://support.adyen.com/'
    email: support@adyen.com
x-groups:
  - Hosted Onboarding Page
paths:
  /getOnboardingUrl:
    post:
      summary: Get a new onboarding url for an account holder.
      description: 'This endpoint is used to get a new onboarding url for a specific account holder. Each account holder represents a single sub-merchant, and each sub-merchant must be represented by an account holder. A returnUrl can also be specified as part of this request.'
      operationId: post-getOnboardingUrl
      x-groupName: Hosted Onboarding Page
      x-sortIndex: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetOnboardingUrlRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetOnboardingUrlResponse'
          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:
    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:
            - accountCode
            - accountHolderCode
            - accountHolderDetails
            - accountNumber
            - accountStateType
            - accountStatus
            - accountType
            - address
            - bankAccount
            - bankAccountCode
            - bankAccountName
            - bankAccountUUID
            - bankBicSwift
            - bankCity
            - bankCode
            - bankName
            - bankStatement
            - branchCode
            - businessContact
            - cardToken
            - checkCode
            - city
            - companyRegistration
            - country
            - countryCode
            - currency
            - currencyCode
            - dateOfBirth
            - description
            - destinationAccountCode
            - document
            - documentExpirationDate
            - documentIssuerCountry
            - documentIssuerState
            - documentName
            - documentNumber
            - documentType
            - doingBusinessAs
            - drivingLicence
            - drivingLicenceBack
            - drivingLicense
            - email
            - firstName
            - fullPhoneNumber
            - gender
            - hopWebserviceUser
            - houseNumberOrName
            - iban
            - idCard
            - idCardBack
            - idCardFront
            - idNumber
            - identityDocument
            - individualDetails
            - lastName
            - legalBusinessName
            - legalEntity
            - legalEntityType
            - merchantAccount
            - merchantCategoryCode
            - merchantReference
            - microDeposit
            - name
            - nationality
            - originalReference
            - ownerCity
            - ownerCountryCode
            - ownerHouseNumberOrName
            - ownerName
            - ownerPostalCode
            - ownerState
            - ownerStreet
            - passport
            - passportNumber
            - payoutMethodCode
            - personalData
            - phoneCountryCode
            - phoneNumber
            - postalCode
            - primaryCurrency
            - reason
            - registrationNumber
            - returnUrl
            - schedule
            - shareholder
            - shareholderCode
            - socialSecurityNumber
            - sourceAccountCode
            - stateOrProvince
            - status
            - stockExchange
            - stockNumber
            - stockTicker
            - store
            - storeDetail
            - storeName
            - storeReference
            - street
            - taxId
            - tier
            - tierNumber
            - transferCode
            - unknown
            - value
            - virtualAccount
            - visaNumber
            - 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
    GetOnboardingUrlRequest:
      properties:
        accountHolderCode:
          description: The account holder code you provided when you created the account holder.
          type: string
        editMode:
          description: Allows editing checks even if all the checks have passed.
          type: boolean
        platformName:
          description: The platform name which will show up in the welcome page.
          type: string
        returnUrl:
          description: 'The URL where the sub-merchant will be redirected back to after they complete the onboarding, or if their session times out. Maximum length of 500 characters. If you don''t provide this, the sub-merchant will be redirected back to the default return URL configured in your platform account.'
          type: string
      required:
        - accountHolderCode
    GetOnboardingUrlResponse:
      properties:
        invalidFields:
          description: Contains field validation errors that would prevent requests from being processed.
          items:
            $ref: '#/components/schemas/ErrorFieldType'
          type: array
        pspReference:
          description: The reference of a request. Can be used to uniquely identify the request.
          type: string
        redirectUrl:
          description: The URL to the Hosted Onboarding Page where you should redirect your sub-merchant. This URL must be used within 15 seconds and can only be used once.
          type: string
        resultCode:
          description: The result code.
          type: string
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http