Currencycloud Reference API

openapi: 3.2.0
info:
  title: api-onboarding Account Usage Reference API
  version: v1
  description: Easy access to view important data relevant to your Currencycloud account including beneficiary details, conversion dates, available currencies, payer required details, payment dates and settlement details.
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: Reference
  description: Easy access to view important data relevant to your Currencycloud account including beneficiary details, conversion dates, available currencies, payer required details, payment dates and settlement details.
paths:
  /reference/bank_details/find:
    post:
      tags:
      - Reference
      x-api-group: manage
      summary: Find Bank Details
      description: Returns the related bank details for the given account reference.
      operationId: FinfBankDetailsPost
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: identifier_type
        in: formData
        required: true
        type: string
        enum:
        - aba
        - bic_swift
        - bsb_code
        - cnaps
        - iban
        - ifsc
        - routing_number
        - sort_code
        description: The type of code used to identify the account (e.g. IBAN).
      - name: identifier_value
        in: formData
        required: true
        type: string
        description: The value of the account identifier specified in identifier_type (e.g. the IBAN code).
        minLength: 1
        maxLength: 255
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/BankDetails'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: identifier_type_is_required
            category: identifier_type
            message: identifier_type is required
            params: ''
          - code: identifier_type_not_in_range
            category: identifier_type
            message: 'identifier_type should be in range: iban, bic_swift, sort_code, aba, bsb_code, routing_number, cnaps, ifsc'
            params: '{ "range" => "iban, bic_swift, sort_code, aba, bsb_code, routing_number, cnaps, ifsc" }'
          - code: identifier_value_is_required
            category: identifier_value
            message: identifier_value is required
            params: ''
          - code: identifier_value_is_empty
            category: identifier_value
            message: identifier_value should not be empty
            params: '{ "type" => "not_empty_string" }'
          - code: invalid_iban
            category: base
            message: IBAN is invalid
            params: ''
          - code: invalid_bic
            category: base
            message: BIC_Swift is invalid
            params: ''
          - code: invalid_aba
            category: base
            message: ABA is invalid
            params: ''
          - code: invalid_sort_code
            category: base
            message: SORT_CODE is invalid
            params: ''
          - code: invalid_bsb
            category: base
            message: BSB_CODE is invalid
            params: ''
          - code: invalid_routing_number
            category: base
            message: ROUTING_NUMBER is invalid
            params: ''
          - code: invalid_cnaps
            category: base
            message: CNAPS is invalid
            params: ''
          - code: cannot_retrieve_bank_data
            category: base
            message: Bank Details service is temporarily unavailable
            params: ''
          schema:
            $ref: '#/definitions/GetBankDetailsError'
          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.
        '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 s
            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.
  /reference/beneficiary_required_details:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Beneficiary Requirements
      description: Returns the information that is required to make payments to beneficiaries in specified currencies and countries.
      operationId: GetBeneficiaryRequirements
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: currency
        in: query
        required: true
        type: string
        description: Currency in which money is held in the beneficiary's bank account. Three-letter ISO currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: bank_account_country
        in: query
        required: true
        type: string
        description: Two-letter ISO country code.
        format: iso3166-1-alpha-2
        pattern: ^[A-Z]{2}$
      - 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: beneficiary_country
        in: query
        required: true
        type: string
        description: Two-letter ISO country code. If the beneficiary is a company, this is the country in which the company is registered. If the beneficiary is an individual, this is the country in which they are based.
        format: iso3166-1-alpha-2
        pattern: ^[A-Z]{2}$
      responses:
        '200':
          description: Success.
          schema:
            type: object
            properties:
              details:
                type: array
                items:
                  $ref: '#/definitions/BeneficiaryRequirements'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: bank_account_country_is_in_invalid_format
            category: bank_account_country
            message: Bank account country is not a valid ISO 3166-1 Alpha-2 country code
            params: ''
          - code: currency_is_in_invalid_format
            category: currency
            message: Currency is not a valid ISO 4217 currency code
            params: ''
          - code: beneficiary_country_is_in_invalid_format
            category: beneficiary_country
            message: Beneficiary country is not a valid ISO 3166-1 Alpha-2 country code
            params: ''
          schema:
            $ref: '#/definitions/GetBeneficiaryRequirementsError'
          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.
          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.
  /reference/conversion_dates:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Conversion Dates
      description: Provides a list of upcoming non-trading dates, such as weekends or public holidays, for a specified currency pair. Common use cases include situations where this information needs to be provided, or for planning upcoming conversion bookings. <br><br> Many currencies are triangulated; this means that holidays affecting the intermediary currency, as well as the sale and purchase currencies, will impact transactions. Find out more at our <a href="https://support.currencycloud.com/hc/en-gb/articles/5223342659484-Currency-Triangulation">support article.</a>
      operationId: GetConversionDates
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: conversion_pair
        in: query
        required: true
        type: string
        description: Concatenated string of the currency codes for the two currencies involved, e.g. "USDEUR".
        pattern: ^[A-Z]{6}$
      - name: start_date
        in: query
        required: false
        type: string
        format: date
        description: Start date of conversion. ISO 8601 format YYYY-MM-DD.
      - 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/ConversionDates'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: conversion_pair_is_required
            category: conversion_pair
            message: conversion_pair is required
            params: ''
          - code: invalid_conversion_pair
            category: conversion_pair
            message: The conversion pair specified was invalid
            params: ''
          - code: conversion_pair_is_too_short
            category: conversion_pair
            message: conversion_pair can not be shorter than 6 character(s)
            params: '{ "minlength" => 6 }'
          - code: conversion_pair_is_too_long
            category: conversion_pair
            message: conversion_pair can not be longer than 6 character(s)
            params: '{ "maxlength" => 6 }'
          - code: start_date_is_too_far_in_future
            category: start_date
            message: Date is too far in the future (more than 1 year)
            params: '{ "maxdate" => "2015-04-04T00:00:00Z", "period" => "1 year" }'
          - code: start_date_is_in_invalid_format
            category: start_date
            message: start_date should be in ISO 8601 format
            params: '{ "type" => "date" }'
          - code: contact_not_found
            category: on_behalf_of
            message: Contact was not found for this id
            params: ''
          - code: on_behalf_of_self
            category: on_behalf_of
            message: You can not act on behalf of your own Contact
            params: ''
          schema:
            $ref: '#/definitions/GetConversionDatesError'
          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.
          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.
  /reference/currencies:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Available Currencies
      description: Gets a list of all currencies that can be traded on the Currencycloud platform.
      operationId: GetAvailableCurrencies
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/AvailableCurrencies'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          schema:
            $ref: '#/definitions/GetAvailableCurrenciesError'
          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.
          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.
  /reference/payer_required_details:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Payer Requirements
      description: Returns the payer information you need to provide to create a payment. Requirements vary depending on the location of the payer, the type of payment to be made (priority or regular), and other factors.
      operationId: GetPayerRequirements
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: payer_country
        in: query
        required: true
        type: string
        description: Two-letter ISO country code.
        format: iso3166-1-alpha-2
        pattern: ^[A-Z]{2}$
      - name: payer_entity_type
        in: query
        required: false
        type: string
        enum:
        - company
        - individual
        description: Legal entity type - company or individual.
      - name: payment_type
        in: query
        required: false
        type: string
        enum:
        - priority
        - regular
        description: 'Currencycloud supports two types of payments: "priority" (Swift), made using the Swift network; and "regular" (local), made using the local bank network.'
      - name: currency
        in: query
        required: false
        type: string
        description: Three-letter ISO 4217 currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/PayerRequirements'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: payer_country_is_required
            category: payer_country
            message: payer_country is required
            params: ''
          - code: payer_country_is_in_invalid_format
            category: payer_country
            message: payer_country is not a valid ISO 3166-1 Alpha-2 country code
            params: '{ "type" => "country_code" }'
          - code: payment_type_not_in_range
            category: payment_type
            message: 'payment_type should be in range: priority, regular'
            params: '{ "range" => "priority, regular" }'
          - code: payer_entity_type_not_in_range
            category: payer_entity_type
            message: 'payer_entity_type should be in range: company, individual'
            params: '{ "range" => "company, individual" }'
          - code: currency_is_in_invalid_format
            category: currency
            message: currency is not a valid ISO 4217 currency code
            params: ''
          schema:
            $ref: '#/definitions/GetPayerRequirementsError'
          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.
          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.
  /reference/payment_dates:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Payment Dates
      description: Gets a list of invalid payment dates for a given currency covering a two months period from the start_date specified. A payment date is when a payment will be executed by Currencycloud. Payments cannot be made on some days, for example when banks are closed.
      operationId: GetPaymentDates
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: currency
        in: query
        required: true
        type: string
        description: Currency in which payment made. Three-letter ISO currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: start_date
        in: query
        required: false
        type: string
        format: date
        description: Payment start date, defaults to today's date. ISO 8601 format YYYY-MM-DD.
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/PaymentDates'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - 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: ''
          - code: start_date_is_too_far_in_future
            category: start_date
            message: Date is too far in the future (more than 1 year)
            params: '{ "maxdate" => "2015-04-04T00:00:00Z", "period" => "1 year" }'
          - code: start_date_is_in_invalid_format
            category: start_date
            message: start_date should be in ISO 8601 format
            params: '{ "type" => "datetime" }'
          schema:
            $ref: '#/definitions/GetPaymentDatesError'
          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.
          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.
  /reference/payment_fee_rules:
    get:
      tags:
      - Reference
      x-api-group: manage
      summary: Get Payment Fee Rules
      description: Gets the <a href="https://support.currencycloud.com/hc/en-gb/articles/360017471459-Applying-fees-to-individual-payments-FAQ">payment fee</a> information set up for the account / payment type provided.
      operationId: GetPaymentFeeRules
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: account_id
        in: query
        required: false
        type: string
        description: Account UUID
        format: uuid
      - name: payment_type
        in: query
        required: false
        type: string
        enum:
        - priority
        - regular
        description: Payment type value. Limits the search results to payments of the specified payment type - 'priority'(Swift) or 'regular'(local).
      - name: charge_type
        in: query
        required: false
        type: string
        enum:
        - ours
        - shared
        description: Payment charge value. Limits the search results to payments of the specified <a href="https://support.currencycloud.com/hc/en-gb/articles/360017430820-Selecting-payment-charges-for-SWIFT-payments-FAQ">charge type</a> - 'ours' or 'shared'.
      responses:
        '200':
          description: Success.
          schema:
            type: object
            properties:
              payment_fee_rules:
                type: array
                items:
                  $ref: '#/definitions/PaymentFeeRule'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: account_id_is_not_valid_uuid
            category: account_id
            message: account_id should be in UUID format
            params: ''
          - code: charge_type_not_in_range
            category: charge_type
            message: 'charge_type should be in range: shared, ours'
            params: '{ "charge_type" => "shared, ours" }'
          - code: payment_type_not_in_range
            category: payment_type
            message: 'payment_type should be in range: priority, regular'
            params: '{ "payment_type" => "priority, regular" }'
          schema:
            $ref: '#/definitions/GetPaymentFeeRulesError'
          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.
          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

# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-reference-api-openapi.yml