adyen-openapi/yaml/TransferService-v1.yaml

openapi: 3.1.0
servers:
- url: https://balanceplatform-api-test.adyen.com/btl/v1
info:
  version: '1'
  x-publicVersion: true
  title: Transfers API
  description: "The Transfers API provides endpoints that you can use to get information\
    \ about all your transactions, move funds within your balance platform or send\
    \ funds from your balance platform to a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/latest/post/transferInstruments).\n\
    \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-H \"Content-Type: application/json\" \\\n-U \"ws@BalancePlatform.YOUR_BALANCE_PLATFORM\"\
    :\"YOUR_WS_PASSWORD\" \\\n...\n```\n## Roles and permissions\nTo use the Transfers\
    \ API, you need an additional role for your API credential. Transfers must also\
    \ be enabled for the source balance account. Your Adyen contact will set up the\
    \ roles and permissions for you.\n## Versioning\nThe Transfers 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://balanceplatform-api-test.adyen.com/btl/v1/transfers\n\
    ```\n## Going live\nWhen going live, your Adyen contact will provide your API\
    \ credential for the live environment. You can then use the username and password\
    \ to send requests to `https://balanceplatform-api-live.adyen.com/btl/v1`.\n\n"
  x-timestamp: '2023-02-09T22:20:55Z'
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://www.adyen.help/hc/en-us/community/topics
    email: developer-experience@adyen.com
x-groups:
- Transfers
- Transactions
tags:
- name: Transactions
- name: Transfers
paths:
  /transactions:
    get:
      tags:
      - Transactions
      summary: Get all transactions
      description: 'Returns all transactions related to a balance account with a payment
        instrument of type **bankAccount**.


        This endpoint supports cursor-based pagination. The response returns the first
        page of results, and returns links to the next page when applicable. You can
        use the links to page through the results. The response also returns links
        to the previous page when applicable.'
      x-addedInVersion: '1'
      operationId: get-transactions
      x-groupName: Transactions
      x-sortIndex: 1
      x-methodName: getAllTransactions
      security:
      - ApiKeyAuth: []
      parameters:
      - description: Unique identifier of the [balance platform](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balancePlatforms/{id}__queryParam_id).
        name: balancePlatform
        in: query
        required: false
        schema:
          type: string
      - description: Unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/balanceplatform/latest/get/paymentInstruments/_id_).
        name: paymentInstrumentId
        in: query
        required: false
        schema:
          type: string
      - description: Unique identifier of the [account holder](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/accountHolders/{id}__queryParam_id).
        name: accountHolderId
        in: query
        required: false
        schema:
          type: string
      - description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/get/balanceAccounts/{id}__queryParam_id).
        name: balanceAccountId
        in: query
        required: false
        schema:
          type: string
      - description: The `cursor` returned in the links of the previous response.
        name: cursor
        in: query
        required: false
        schema:
          type: string
      - description: Only include transactions that have been created on or after
          this point in time. The value must be in ISO 8601 format. For example, **2021-05-30T15:07:40Z**.
        name: createdSince
        in: query
        required: true
        schema:
          format: date-time
          type: string
      - description: Only include transactions that have been created on or before
          this point in time. The value must be in ISO 8601 format. For example, **2021-05-30T15:07:40Z**.
        name: createdUntil
        in: query
        required: true
        schema:
          format: date-time
          type: string
      - description: The number of items returned per page, maximum of 100 items.
          By default, the response returns 10 items per page.
        name: limit
        in: query
        required: false
        schema:
          format: int32
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSearchResponse'
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
  /transactions/{id}:
    get:
      tags:
      - Transactions
      summary: Get a transaction
      description: Returns a transaction.
      x-addedInVersion: '1'
      operationId: get-transactions-id
      x-groupName: Transactions
      x-sortIndex: 2
      x-methodName: getTransaction
      security:
      - ApiKeyAuth: []
      parameters:
      - description: Unique identifier of the transaction.
        name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Transaction'
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
  /transfers:
    post:
      tags:
      - Transfers
      summary: Transfer funds
      description: 'Starts a transfer request to move funds within your balance platform,
        or send funds to a [transfer instrument](https://docs.adyen.com/api-explorer/#/legalentity/v1/post/transferInstruments).
        Adyen sends the outcome of the transfer request through webhooks.


        To use this endpoint, you need an additional role for your API credential
        and transfers must be enabled for the source balance account. Your Adyen contact
        will set these up for you.'
      x-addedInVersion: '1'
      operationId: post-transfers
      x-groupName: Transfers
      x-sortIndex: 1
      x-methodName: transferFunds
      security:
      - ApiKeyAuth: []
      requestBody:
        content:
          application/json:
            examples:
              payout-to-balance-account:
                $ref: '#/components/examples/post-transfers-payout-to-balance-account'
              payout-to-transfer-instrument:
                $ref: '#/components/examples/post-transfers-payout-to-transfer-instrument'
            schema:
              $ref: '#/components/schemas/TransferInfoOld'
      responses:
        '200':
          content:
            application/json:
              examples:
                payout-to-balance-account:
                  $ref: '#/components/examples/post-transfers-payout-to-balance-account-200'
                payout-to-transfer-instrument:
                  $ref: '#/components/examples/post-transfers-payout-to-transfer-instrument-200'
              schema:
                $ref: '#/components/schemas/TransferOld'
          description: OK - the request has succeeded.
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unauthorized - authentication required.
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Forbidden - insufficient permissions to process the request.
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Unprocessable Entity - a request validation error.
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestServiceError'
          description: Internal Server Error - the server could not process the request.
components:
  schemas:
    Address:
      properties:
        city:
          description: 'The name of the city. Maximum length: 3000 characters.'
          maxLength: 3000
          type: string
        country:
          description: 'The two-character ISO-3166-1 alpha-2 country code. For example,
            **US**.

            > If you don''t know the country or are not collecting the country from
            the shopper, provide `country` as `ZZ`.'
          type: string
        houseNumberOrName:
          description: 'The number or name of the house. Maximum length: 3000 characters.'
          maxLength: 3000
          type: string
        postalCode:
          description: A maximum of five digits for an address in the US, or a maximum
            of ten characters for an address in all other countries.
          type: string
        stateOrProvince:
          description: 'The two-character ISO 3166-2 state or province code. For example,
            **CA** in the US or **ON** in Canada.

            > Required for the US and Canada.'
          type: string
        street:
          description: 'The name of the street. Maximum length: 3000 characters.

            > The house number should not be included in this field; it should be
            separately provided via `houseNumberOrName`.'
          maxLength: 3000
          type: string
      required:
      - street
      - houseNumberOrName
      - city
      - postalCode
      - country
    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
    BankAccountInfo:
      properties:
        address:
          description: The address of the bank account owner.
          $ref: '#/components/schemas/Address'
        iban:
          description: The international bank account number as defined in the [ISO-13616](https://www.iso.org/standard/81090.html)
            standard.
          type: string
        ownerName:
          description: The name of the bank account owner.
          $ref: '#/components/schemas/Name'
    Counterparty:
      properties:
        balanceAccountId:
          description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
          type: string
        bankAccount:
          description: Contains information about the bank account.
          $ref: '#/components/schemas/BankAccountInfo'
        merchant:
          description: Contains information about the merchant.
          $ref: '#/components/schemas/MerchantData'
        transferInstrumentId:
          description: Unique identifier of the [transfer instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/transferInstruments__resParam_id).
          type: string
    InternalPartyIdentification:
      properties:
        balanceAccountId:
          description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
          type: string
        paymentInstrumentId:
          description: Unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__resParam_id).
          type: string
    InvalidField:
      properties:
        message:
          description: Description of the validation error.
          type: string
        name:
          description: The field that has an invalid value.
          type: string
        value:
          description: The invalid value.
          type: string
      required:
      - name
      - value
      - message
    JSONObject:
      properties:
        paths:
          items:
            $ref: '#/components/schemas/JSONPath'
          type: array
        rootPath:
          $ref: '#/components/schemas/JSONPath'
    JSONPath:
      properties:
        content:
          items:
            type: string
          type: array
    Link:
      properties:
        href:
          type: string
    Links:
      properties:
        next:
          description: Contains a link to the next page.
          $ref: '#/components/schemas/Link'
        prev:
          description: Contains a link to the previous page.
          $ref: '#/components/schemas/Link'
    MerchantData:
      properties:
        mcc:
          description: The merchant category code.
          type: string
        merchantId:
          description: The merchant identifier.
          type: string
        nameLocation:
          description: Contains the merchant's name and location.
          $ref: '#/components/schemas/NameLocation'
        postalCode:
          description: The merchant postal code.
          type: string
    Name:
      properties:
        firstName:
          description: The first name.
          type: string
        fullName:
          description: The full name.
          type: string
        infix:
          description: The infix in the name, if any.
          type: string
        lastName:
          description: The last name.
          type: string
    NameLocation:
      properties:
        city:
          description: The city where the merchant is located.
          type: string
        country:
          description: The country where the merchant is located in [three-letter
            country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) format.
          type: string
        countryOfOrigin:
          description: The home country in [three-digit country code](https://en.wikipedia.org/wiki/ISO_3166-1_numeric)
            format, used for government-controlled merchants such as embassies.
          type: string
        name:
          description: The name of the merchant's shop or service.
          type: string
        rawData:
          description: The raw data.
          type: string
        state:
          description: The state where the merchant is located.
          type: string
    PartyIdentification:
      properties:
        balanceAccountId:
          description: Unique identifier of the [balance account](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/balanceAccounts__resParam_id).
          type: string
        paymentInstrumentId:
          description: Unique identifier of the [payment instrument](https://docs.adyen.com/api-explorer/#/balanceplatform/latest/post/paymentInstruments__resParam_id).
          type: string
    RestServiceError:
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of
            the problem.
          type: string
        errorCode:
          description: A code that identifies the problem type.
          type: string
        instance:
          description: A unique URI that identifies the specific occurrence of the
            problem.
          type: string
        invalidFields:
          description: Detailed explanation of each validation error, when applicable.
          items:
            $ref: '#/components/schemas/InvalidField'
          type: array
        requestId:
          description: A unique reference for the request, essentially the same as
            `pspReference`.
          type: string
        response:
          description: JSON response payload.
          $ref: '#/components/schemas/JSONObject'
        status:
          description: The HTTP status code.
          format: int32
          type: integer
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        type:
          description: A URI that identifies the problem type, pointing to human-readable
            documentation on this problem type.
          type: string
      required:
      - type
      - errorCode
      - title
      - detail
      - status
    Transaction:
      properties:
        accountHolderId:
          x-addedInVersion: '1'
          description: Unique identifier of the account holder.
          type: string
        amount:
          x-addedInVersion: '1'
          description: The amount.
          $ref: '#/components/schemas/Amount'
        balanceAccountId:
          x-addedInVersion: '1'
          description: Unique identifier of the balance account.
          type: string
        balancePlatform:
          x-addedInVersion: '1'
          description: Unique identifier of the balance platform.
          type: string
        bookingDate:
          x-addedInVersion: '1'
          description: The date the transaction was booked to the balance account.
          format: date-time
          type: string
        category:
          x-addedInVersion: '1'
          description: "The category of the transaction indicating the type of activity.\n\
            \n Possible values:\n\n* **platformPayment**: The transaction is a payment\
            \ or payment modification made with an Adyen merchant account.\n\n* **internal**:\
            \ The transaction resulted from an internal adjustment such as a deposit\
            \ correction or invoice deduction.\n\n* **bank**: The transaction is a\
            \ bank-related activity, such as sending a payout or receiving funds.\n\
            \n* **issuedCard**: The transaction is a card-related activity, such as\
            \ using an Adyen-issued card to pay online.\n\n"
          enum:
          - bank
          - grants
          - internal
          - issuedCard
          - platformPayment
          type: string
        counterparty:
          x-addedInVersion: '1'
          description: Contains information about the other party in the transaction.
          $ref: '#/components/schemas/Counterparty'
        createdAt:
          x-addedInVersion: '1'
          description: The date the transaction was created.
          format: date-time
          type: string
        description:
          x-addedInVersion: '1'
          description: The `description` from the `/transfers` request.
          type: string
        id:
          x-addedInVersion: '1'
          description: Unique identifier of the transaction.
          type: string
        instructedAmount:
          x-addedInVersion: '1'
          description: The amount that the sender instructed their bank to send. This
            can be higher than `amount.value` when their bank deducts costs for the
            transfer.
          $ref: '#/components/schemas/Amount'
        paymentInstrumentId:
          x-addedInVersion: '1'
          description: Unique identifier of the payment instrument that was used for
            the transaction.
          type: string
        reference:
          x-addedInVersion: '1'
          description: The [`reference`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_reference)
            from the `/transfers` request. If you haven't provided any, Adyen generates
            a unique reference.
          type: string
        referenceForBeneficiary:
          x-addedInVersion: '1'
          description: "The reference sent to or received from the counterparty.\n\
            \n* For outgoing funds, this is the [`referenceForBeneficiary`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__resParam_referenceForBeneficiary)\
            \ from the  [`/transfers`](https://docs.adyen.com/api-explorer/#/transfers/latest/post/transfers__reqParam_referenceForBeneficiary)\
            \ request.\n\n * For incoming funds, this is the reference from the sender."
          type: string
        status:
          x-addedInVersion: '1'
          description: "The status of the transaction.\n\n Possible values:\n\n* **pending**:\
            \ The transaction is still pending.\n\n* **booked**: The transaction has\
            \ been booked to the balance account.\n\n"
          enum:
          - booked
          - pending
          type: string
        transferId:
          x-addedInVersion: '1'
          description: Unique identifier of the related transfer.
          type: string
        type:
          x-addedInVersion: '1'
          description: "The type of the transaction.\n\n Possible values: **payment**,\
            \ **capture**, **captureReversal**, **refund** **refundReversal**, **chargeback**,\
            \ **chargebackReversal**, **secondChargeback**, **atmWithdrawal**, **atmWithdrawalReversal**,\
            \ **internalTransfer**, **manualCorrection**, **invoiceDeduction**, **depositCorrection**,\
            \ **bankTransfer**, **miscCost**, **paymentCost**, **fee**"
          enum:
          - atmWithdrawal
          - atmWithdrawalReversal
          - balanceAdjustment
          - balanceRollover
          - bankTransfer
          - capture
          - captureReversal
          - chargeback
          - chargebackReversal
          - depositCorrection
          - fee
          - grant
          - installment
          - installmentReversal
          - internalTransfer
          - invoiceDeduction
          - leftover
          - manualCorrection
          - miscCost
          - payment
          - paymentCost
          - refund
          - refundReversal
          - repayment
          - reserveAdjustment
          - secondChargeback
          type: string
        valueDate:
          x-addedInVersion: '1'
          description: The date the transfer amount becomes available in the balance
            account.
          format: date-time
          type: string
      required:
      - id
      - accountHolderId
      - balanceAccountId
      - amount
      - reference
      - status
      - createdAt
      - bookingDate
      - valueDate
      - counterparty
      - balancePlatform
    TransactionSearchResponse:
      properties:
        _links:
          description: Contains links to the next and previous page whenever applicable.
          $ref: '#/components/schemas/Links'
        data:
          description: Contains the transactions that match the query parameters.
          items:
            $ref: '#/components/schemas/Transaction'
          type: array
    TransferInfoOld:
      properties:
        amount:
          x-addedInVersion: '1'
          description: The amount of the transfer.
          $ref: '#/components/schemas/Amount'
        description:
          x-addedInVersion: '1'
          description: A human-readable description for the transfer. You can use
            alphanumeric characters and hyphens. We recommend sending a maximum of
            140 characters, otherwise the description will be truncated in the webhooks
            that you receive about the transfer.
          type: string
        destination:
          x-addedInVersion: '1'
          description: Contains information about the resource to which funds will
            be transferred.
          $ref: '#/components/schemas/PartyIdentification'
        reference:
          x-addedInVersion: '1'
          description: 'Your unique reference for the transfer. You can use alphanumeric
            characters and hyphens. Maximum length: 80 characters.'
          maxLength: 80
          type: string
        source:
          x-addedInVersion: '1'
          description: Contains information about the resource from which funds will
            be taken.
          $ref: '#/components/schemas/InternalPartyIdentification'
      required:
      - source
      - destination
      - amount
    TransferOld:
      properties:
        amount:
          x-addedInVersion: '1'
          description: The amount of the transfer.
          $ref: '#/components/schemas/Amount'
        description:
          x-addedInVersion: '1'
          description: A human-readable description for the transfer. You can use
            alphanumeric characters and hyphens. We recommend sending a maximum of
            140 characters, otherwise the description will be truncated in the webhooks
            that you receive about the transfer.
          type: string
        destination:
          x-addedInVersion: '1'
          description: Contains information about the resource to which funds will
            be transferred.
          $ref: '#/components/schemas/PartyIdentification'
        id:
          x-addedInVersion: '1'
          description: Unique identifier of the transfer.
          type: string
        reference:
          x-addedInVersion: '1'
          description: 'Your unique reference for the transfer. You can use alphanumeric
            characters and hyphens. Maximum length: 80 characters.'
          maxLength: 80
          type: string
        refusalReason:
          x-addedInVersion: '1'
          description: Additional information about the result of the transfer request.
          type: string
        resultCode:
          x-addedInVersion: '1'
          description: "The result of the transfer request.\n\n Possible values: **Authorised**,\
            \ **Refused**."
          type: string
        source:
          x-addedInVersion: '1'
          description: Contains information about the resource from which funds will
            be taken.
          $ref: '#/components/schemas/InternalPartyIdentification'
      required:
      - source
      - destination
      - amount
      - id
      - resultCode
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: X-API-Key
      type: apiKey
    BasicAuth:
      scheme: basic
      type: http
  examples:
    post-transfers-payout-to-balance-account:
      summary: Transfer funds to another balance account
      description: Example request to transfer funds to another balance account
      value:
        source:
          balanceAccountId: BAB8B2C3D4E5F6G7H8D9J6GD4
        destination:
          balanceAccountId: BAB1234567890ABC123456789
        amount:
          value: 10000
          currency: EUR
        reference: Your internal reference for the transfer
        description: Your description
    post-transfers-payout-to-balance-account-200:
      summary: Response code - 200 OK
      description: Example response for a transfers request
      value:
        id: 1W1UG35U8A9J5ZLG
        resultCode: Authorised
    post-transfers-payout-to-transfer-instrument:
      summary: Pay out to a transfer instrument
      description: Example request to pay out to a transfer instrument
      value:
        source:
          balanceAccountId: BAB8B2C3D4E5F6G7H8D9J6GD4
        destination:
          transferInstrumentId: SE1234567890ABC1234567890
        amount:
          value: 10000
          currency: EUR
        reference: Your internal reference for the transfer
        description: Your description
    post-transfers-payout-to-transfer-instrument-200:
      summary: Response code - 200 OK
      description: Example response for a transfers request
      value:
        id: 1W1UG35U8A9J5ZLG
        resultCode: Authorised