Currencycloud Funding API

openapi: 3.2.0
info:
  description: The Currencycloud API is a robust, predictable, easy-to-use API for converting money between currencies and making payments around the world. Dynamically register sub-accounts to provide white labeled money transfer services to your own customers.
  version: 2.43.0
  title: Currencycloud Funding API
  termsOfService: https://www.currencycloud.com/terms-and-conditions/
  contact:
    name: support
    email: support@currencycloud.com
servers:
- url: https://devapi.currencycloud.com/v2
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
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: payment_type
        in: query
        required: false
        description: The type of SSI to be returned, priority (Swift) or regular (local). A null value returns all payment types.
        schema:
          type: string
          enum:
          - priority
          - regular
      - name: currency
        in: query
        required: true
        description: The currency of the account details required, ISO 4217 standard.
        schema:
          type: string
          format: iso-4217
          pattern: ^[A-Z]{3}$
      - name: account_id
        in: query
        required: false
        description: UUID of a specific sub-account you want to see the SSIs for.
        schema:
          type: string
          format: uuid
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      - name: page
        in: query
        required: false
        description: Page number
        schema:
          type: integer
          pattern: ^\d+$
      - name: per_page
        in: query
        required: false
        description: Number of results per page.
        schema:
          type: integer
          pattern: ^\d+$
      - name: order
        in: query
        required: false
        description: Any field name to change the sort order.
        schema:
          type: string
          maxLength: 255
          minLength: 1
      - name: order_asc_desc
        in: query
        required: false
        description: Sort records in ascending or descending order.
        schema:
          type: string
          enum:
          - asc
          - desc
          default: asc
      responses:
        '200':
          description: Success.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                properties:
                  funding_accounts:
                    type: array
                    items:
                      $ref: '#/components/schemas/FundingAccount'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindFundingAccountsError'
        '401':
          description: Unauthorized
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '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:
              description: A unique reference for the request.
              schema:
                type: string
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable.
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
  /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
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: The Related Entity UUID (related_entity_id) for the transaction.
        schema:
          type: string
          format: uuid
      - name: on_behalf_of
        in: query
        required: false
        description: A contact UUID for the sub-account you're acting on behalf of.
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: Success
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FundingTransaction'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetFundingTransactionError'
        '401':
          description: Unauthorized.
          x-errors:
          - code: invalid_supplied_credentials
            category: username
            message: Authentication failed with the supplied credentials
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
        '404':
          description: Transaction not found.
          x-errors:
          - code: transaction_not_found
            category: id
            message: Transaction not found
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '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: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
        '500':
          description: Internal server error
          x-errors:
          - code: internal_server_error
            category: base
            message: Internal server error
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        '503':
          description: Service is temporary unavailable.
          x-errors:
          - code: service_unavailable
            category: base
            message: Service is temporarily unavailable
            params: ''
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
        default:
          description: Unexpected error.
          headers:
            X-Request-Id:
              description: A unique reference for the request.
              schema:
                type: string
components:
  schemas:
    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
    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: {}
    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: '#/components/schemas/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
    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
    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
    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
    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'
externalDocs:
  description: API overview
  url: https://www.currencycloud.com/developers/