openapi: 3.0.3
info:
  title: api-onboarding Account Usage Funding API
  version: v1
  description: Find funding accounts that can be used to settle and collect funds in each available currency.
servers:
- url: /onboarding
  description: Relative URL
- url: https://api.currencycloud.com/onboarding
  description: Production server (uses live data)
- url: https://devapi.currencycloud.com/onboarding
  description: Dev server (uses test data)
tags:
- name: Funding
  description: Find funding accounts that can be used to settle and collect funds in each available currency.
paths:
  /funding_accounts/find:
    get:
      tags:
      - Funding
      x-api-group: collect
      summary: Find Funding Accounts
      description: Gets details of the Standard Settlement Instructions (SSIs) that can be used to settle and collect funds in each available currency.
      operationId: FindFundingAccounts
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: payment_type
        in: query
        required: false
        type: string
        description: The type of SSI to be returned, priority (Swift) or regular (local). A null value returns all payment types.
        enum:
        - priority
        - regular
      - name: currency
        in: query
        required: true
        type: string
        description: The currency of the account details required, ISO 4217 standard.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: account_id
        in: query
        required: false
        type: string
        description: UUID of a specific sub-account you want to see the SSIs for.
        format: uuid
      - name: on_behalf_of
        in: query
        required: false
        type: string
        description: A contact UUID for the sub-account you're acting on behalf of.
        format: uuid
      - name: page
        in: query
        required: false
        type: integer
        description: Page number
        pattern: ^\d+$
      - name: per_page
        in: query
        required: false
        type: integer
        description: Number of results per page.
        pattern: ^\d+$
      - name: order
        in: query
        required: false
        type: string
        description: Any field name to change the sort order.
        minLength: 1
        maxLength: 255
      - name: order_asc_desc
        in: query
        required: false
        type: string
        enum:
        - asc
        - desc
        default: asc
        description: Sort records in ascending or descending order.
      responses:
        '200':
          description: Success.
          schema:
            type: object
            properties:
              funding_accounts:
                type: array
                items:
                  $ref: '#/definitions/FundingAccount'
              pagination:
                $ref: '#/definitions/Pagination'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: payment_type_not_in_range
            category: payment_type
            message: 'payment_type should be in range: priority, regular'
            params: '{ "range" => "priority, regular" }'
          - code: currency_is_required
            category: currency
            message: currency is required
            params: ''
          - code: currency_is_in_invalid_format
            category: currency
            message: currency is not a valid ISO 4217 currency code
            params: '{ "type" => "currency" }'
          - code: currency_is_not_supported
            category: currency
            message: currency is not supported
            params: ''
          - code: funding_accounts_not_found
            category: funding_accounts
            message: No funding accounts found for this account
            params: ''
          - code: account_id_is_not_valid_uuid
            category: account_id
            message: account_id should be in UUID format
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You cannot act on behalf of your own Contact
            params: ''
          - code: on_behalf_of_is_not_valid_uuid
            category: on_behalf_of
            message: on_behalf_of should be in UUID format
            params: ''
          schema:
            $ref: '#/definitions/FindFundingAccountsError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Resource not found.
          x-errors:
          - code: account_not_found
            category: account
            message: Account was not found for this id
            params: ''
          - code: contact_not_found
            category: contact
            message: Contact was not found for this id
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable.
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
  /funding_transactions/{id}:
    get:
      tags:
      - Funding
      x-api-group: collect
      summary: Get Funding Transaction
      description: '

        Gets the details of an approved funding transaction with the given ID.'
      operationId: GetFundingTransaction
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: id
        in: path
        required: true
        type: string
        description: The Related Entity UUID (related_entity_id) for the transaction.
        format: uuid
      - name: on_behalf_of
        in: query
        required: false
        type: string
        description: A contact UUID for the sub-account you're acting on behalf of.
        format: uuid
      responses:
        '200':
          description: Success
          schema:
            $ref: '#/definitions/FundingTransaction'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: id_is_not_valid_uuid
            category: id
            message: id should be in UUID format
            params: ''
          - code: on_behalf_of_self
            category: contact
            message: You cannot act on behalf of your own Contact
            params: ''
          schema:
            $ref: '#/definitions/GetFundingTransactionError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          schema:
            $ref: '#/definitions/UnauthorizedError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '404':
          description: Transaction not found.
          x-errors:
          - code: transaction_not_found
            category: id
            message: Transaction not found
            params: ''
          schema:
            $ref: '#/definitions/NotFoundError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '429':
          description: Too many requests.
          x-errors:
          - code: too_many_requests
            category: base
            message: Too many requests have been made to the api. Please refer to the Developer Center for more information
            params: ''
          schema:
            $ref: '#/definitions/RateLimitError'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '503':
          description: Service is temporary unavailable.
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
definitions:
  RateLimitError:
    type: object
    description: Too many requests.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this validation/error.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  UnauthorizedError:
    type: object
    description: Authorization error.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
        enum:
        - auth_failed
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
    example:
      error_code: auth_failed
      error_messages:
        api_key:
        - code: invalid_supplied_credentials
          message: Authentication failed with the supplied credentials
          params: {}
  SenderInformation:
    description: The sender information
    properties:
      sender_account_number:
        description: The sender account number
        type: string
      sender_address:
        description: The unstructured sender address
        type: string
      sender_bic:
        description: The sender bic
        type: string
      sender_country:
        description: The two letter sender country
        type: string
      sender_iban:
        description: The sender iban
        type: string
      sender_id:
        description: The sender id
        type: string
      sender_name:
        description: The sender name
        type: string
      sender_routing_code:
        description: The sender routing code
        type: string
    example:
      sender_account_number: 8119645406
      sender_address: Some street
      sender_bic: null
      sender_country: GB
      sender_iban: null
      sender_id: 5c675fa4-fdf0-4ee6-b5bb-156b36765433
      sender_name: Test sender
      sender_routing_code: null
    type: object
  NotFoundError:
    type: object
    description: Resource not found.
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  FundingAccount:
    type: object
    description: FundingAccount.
    required:
    - id
    - account_id
    - account_number
    - account_number_type
    - account_holder_name
    - bank_name
    - bank_address
    - bank_country
    - currency
    - payment_type
    - routing_code
    - routing_code_type
    - created_at
    - updated_at
    additionalProperties: false
    properties:
      id:
        type: string
        description: The SSI's unique UUID.
      account_id:
        type: string
        description: The account ID the SSI is attached to. If money is paid to the account details, this account will be credited.
      account_number:
        type: string
        description: The account number to use when adding funds to the account.
      account_number_type:
        type: string
        description: The type of account number provided (e.g. account number of IBAN).
        enum:
        - account_number
        - iban
      account_holder_name:
        type: string
        description: The name of the account used to make a payment.
      bank_name:
        type: string
        description: The name of the bank the account is held with.
      bank_address:
        type: string
        description: The address of the bank the account is held with.
      bank_country:
        type: string
        description: The 2 digit ISO country code where the bank is based.
      currency:
        type: string
        description: The currency that should be sent to these account details.
      payment_type:
        type: string
        description: The type of payment that can be made into the account details provided. Regular - a local scheme such as Faster Payments in the UK. Priority - a priority payment e.g. FEDwire or Swift.
        enum:
        - any
        - priority
        - regular
      routing_code:
        type: string
        description: The particular routing code for this account number.
      routing_code_type:
        type: string
        description: The type of routing number.
        enum:
        - routing_code
        - giro_routing_code
        - ach_routing_number
        - fast_routing_code
        - sort_code
        - wire_routing_number
        - bic_swift
        - meps_routing_code
      created_at:
        type: string
        description: The date-time the SSI was added to the account.
        format: date-time
      updated_at:
        type: string
        description: The date-time the SSI was last updated on the account.
        format: date-time
    example:
      id: b7981972-8e29-485b-8a4a-9643fc9ae4ea
      account_id: 8d98bdc8-e8e3-47dc-bd08-3dd0f4f7ea7b
      account_number: GB61TCCL00997950423807
      account_number_type: IBAN
      account_holder_name: Jon Doe
      bank_name: The Currency Cloud
      bank_address: 12 Steward Street, The Steward Building, London, E1 6FQ, GB
      bank_country: UK
      currency: EUR
      payment_type: regular
      routing_code: TCCLGB31
      routing_code_type: bic_swift
      created_at: '2018-05-14T14:18:30+00:00'
      updated_at: '2018-05-14T14:18:30+00:00'
  GetFundingTransactionError:
    description: 'Client error information for the Get Funding Transaction endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255
  FundingTransaction:
    description: The transaction information.
    properties:
      id:
        description: The Related Entity UUID (related_entity_id) for the transaction.
        type: string
      amount:
        description: The transaction amount.
        type: string
      currency:
        description: The three-letter currency code.
        type: string
      rail:
        description: The transaction rail.
        type: string
      additional_information:
        description: Any additional information.
        type: string
      receiving_account_routing_code:
        description: The routing code.
        type: string
      value_date:
        description: The value date in ISO-8601 format.
        format: date-time
        type: string
      receiving_account_number:
        description: The transaction receiving account number.
        type: string
      receiving_account_iban:
        description: The transaction receiving account IBAN.
        type: string
      created_at:
        description: The created at date in ISO-8601 format.
        format: date-time
        type: string
      updated_at:
        description: The last time the transaction was updated in ISO-8601 format.
        format: date-time
        type: string
      completed_at:
        description: The completed date in ISO-8601 format.
        format: date-time
        type: string
      sender:
        $ref: '#/definitions/SenderInformation'
    example:
      additional_information: ABCD20231016143117
      amount: 1.11
      completed_at: 2022-12-03 10:15:30+00:00
      created_at: 2022-12-03 10:15:30+00:00
      currency: USD
      id: 4924919a-6c28-11ee-a3e3-63774946bad2
      rail: SEPA
      receiving_account_iban: null
      receiving_account_number: 32847346
      receiving_account_routing_code: 123456789
      updated_at: 2022-12-03 10:15:30+00:00
      value_date: 2022-12-03 10:00:00+00:00
      sender:
        sender_account_number: 8119645406
        sender_address: Some street
        sender_bic: null
        sender_country: GB
        sender_iban: null
        sender_id: 5c675fa4-fdf0-4ee6-b5bb-156b36765433
        sender_name: Test sender
        sender_routing_code: null
    type: object
  Pagination:
    type: object
    description: Pagination.
    properties:
      total_entries:
        type: integer
      total_pages:
        type: integer
      current_page:
        type: integer
      per_page:
        type: integer
        description: Number of results per page.
      previous_page:
        type: integer
      next_page:
        type: integer
      order:
        type: string
        description: The field name by which the results are sorted.
      order_asc_desc:
        type: string
        enum:
        - asc
        - desc
        default: asc
        description: Whether results are sorted in ascending or descending order.
    example:
      total_entries: 1
      total_pages: 1
      current_page: 1
      per_page: 25
      previous_page: -1
      next_page: 2
      order: created_at
      order_asc_desc: asc
  FindFundingAccountsError:
    type: object
    description: 'Client error information for the Find Funding Accounts endpoint.

      '
    required:
    - error_code
    - error_messages
    properties:
      error_code:
        type: string
        description: A high-level error code for the whole request.
      error_messages:
        type: object
        description: Detailed error information for individual input parameters that failed validation. Object keys are the names of the invalid input parameters. Each parameter may have one or more reasons why it failed.
        additionalProperties:
          type: array
          items:
            type: object
            description: An object that represents one of the reasons why the input parameter failed.
            required:
            - code
            - message
            properties:
              code:
                type: string
                description: A unique code that identifies this error. It can be used for translations.
              message:
                type: string
                description: An explanation of the error in English.
              params:
                type: object
                default: {}
                description: Relevant validation rules that failed. This can be used for translations.
                example:
                  minlength: 1
                  maxlength: 255