Currencycloud Transfers API

openapi: 3.0.3
info:
  title: api-onboarding Account Usage Transfers API
  version: v1
  description: Search, retrieve and create a transfer of funds between your Currencycloud account and associated sub-accounts.
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: Transfers
  description: Search, retrieve and create a transfer of funds between your Currencycloud account and associated sub-accounts.
paths:
  /transfers/create:
    post:
      tags:
      - Transfers
      x-api-group: pay
      summary: Create Transfer
      description: Transfers funds from one account to another. No currency conversion is performed, so the sending and receiving accounts must hold money in the same currency.
      operationId: CreateTransfer
      consumes:
      - multipart/form-data
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - name: source_account_id
        in: formData
        required: true
        type: string
        description: Account UUID of the paying account.
        format: uuid
      - name: destination_account_id
        in: formData
        required: true
        type: string
        description: Account UUID of the receiving account.
        format: uuid
      - name: currency
        in: formData
        required: true
        type: string
        description: Three-letter ISO currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: amount
        in: formData
        required: true
        type: number
        description: Amount
        pattern: ^\d+(\.\d{1,3})?$
      - name: reason
        in: formData
        required: false
        type: string
        description: User-generated reason for transfer, freeform text.
        minLength: 1
        maxLength: 255
      - name: unique_request_id
        in: formData
        required: false
        type: string
        description: User-generated idempotency key. The value must be 100 characters or fewer.
        minLength: 1
        maxLength: 255
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Transfer'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: account_not_found
            category: account_id
            message: Account was not found for this id
            params: ''
          - code: amount_is_too_big
            category: amount
            message: Amount cannot be greater than 10000000000
            params: ''
          - code: amount_type_is_wrong
            category: amount
            message: Amount should be of numeric_greater_than_zero type
            params: ''
          - code: cash_workflow_unknown
            category: account_id
            message: Could not retrieve cash workflow for account {account_id}
            params: ''
          - code: cash_workflow_unknown
            category: account_id
            message: Could not retrieve cash workflow for account {account_id}
            params: ''
          - code: cross_hub_transfer_not_permitted
            category: unique_request_id
            message: The accounts would require a transfer between two hub banks which is not permitted
            params: ''
          - code: currency_is_in_invalid_format
            category: currency
            message: '{currency} currency is not a valid ISO 4217 currency code'
            params: ''
          - code: currency_is_not_supported
            category: currency
            message: '{currency} currency is restricted'
            params: ''
          - code: destination_account_disabled
            category: null
            message: The transfer was not created successfully because the destination account is disabled. Ensure that both source and destination accounts are enabled before making a transfer.
            params: ''
          - code: destination_account_id_is_not_valid_uuid
            category: account_id
            message: destination_account_id should be in UUID format
            params: ''
          - code: destination_bank_account_verified_error
            category: account_id
            message: Destination bank account is not verified. Ensure that both source and destination bank accounts are verified before making a transfer.
            params: ''
          - code: duplicate_unique_request_id
            category: unique_request_id
            message: The unique_request_id provided for this transfer has already been used, please provide a new one to successfully submit this transfer
            params: ''
          - code: invalid_amount_format
            category: amount
            message: '{currency} does not support any decimal places'
            params: ''
          - code: invalid_amount_format
            category: amount
            message: '{currency} only supports up to 1 decimal place'
            params: ''
          - code: invalid_amount_format
            category: amount
            message: '{currency} only supports up to %d decimal places'
            params: ''
          - code: invalid_extra_parameters
            category: invalid_extra_parameters
            message: Invalid extra parameters:{parameter}
            params: '{ "parameters" => "extra_parameter" }'
          - code: not_allowed_currency
            category: currency
            message: You cannot perform this operation in {currency} currency
            params: ''
          - code: reason_too_long
            category: reason
            message: Reason longer than 255 symbols
            params: ''
          - code: same_source_and_destination_accounts
            category: account_id
            message: Source and Destination accounts cannot be the same
            params: ''
          - code: source_account_disabled
            category: account_id
            message: The transfer was not created successfully because the source account is disabled. Ensure that both source and destination accounts are enabled before making a transfer.
            params: ''
          - code: source_account_id_is_not_valid_uuid
            category: source_account_id
            message: source_account_id should be in UUID format
            params: ''
          - code: source_bank_account_verified_error
            category: source_account_id
            message: Source bank account is not verified. Ensure that both source and destination bank accounts are verified before making a transfer.
            params: ''
          - code: transfer_not_permitted
            category: account_id
            message: The transfer is not permitted between the source and destination accounts defined.
            params: ''
          - code: unique_request_id_too_long
            category: unique_request_id
            message: The unique_request_id provided is longer than 100 characters, please provide a shorter one
            params: ''
          schema:
            $ref: '#/definitions/CreateTransferError'
          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.
  /transfers/{id}:
    get:
      tags:
      - Transfers
      x-api-group: pay
      summary: Get Transfer
      description: Returns the money transfer record with the given ID.
      operationId: GetTransfer
      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: Transfer UUID, this was returned when the transfer was created.
        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/Transfer'
          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: null
            message: id should be in UUID format
            params: ''
          - code: invalid_extra_parameters
            category: extra_parameter
            message: Invalid extra parameters:'{parameter}'
            params: '{ "parameters" => "extra_parameter" }'
          - code: transfer_not_found
            category: null
            message: Transfer was not found for this ID
            params: ''
          schema:
            $ref: '#/definitions/GetTransferError'
          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.
          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.
  /transfers/find:
    get:
      tags:
      - Transfers
      x-api-group: pay
      summary: Find Transfers
      description: Searches for transfer records that meet the given criteria.
      operationId: FindTransfers
      produces:
      - application/json
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        type: string
        description: Authentication token
        minLength: 32
      - 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: short_reference
        in: query
        required: false
        type: string
        description: Short reference code.
        minLength: 1
        maxLength: 25
      - name: source_account_id
        in: query
        required: false
        type: string
        description: Account UUID of the paying account.
        format: uuid
      - name: destination_account_id
        in: query
        required: false
        type: string
        description: Account UUID of the receiving account.
        format: uuid
      - name: status
        in: query
        required: false
        type: string
        enum:
        - cancelled
        - completed
        - pending
        description: Transfer status
      - name: currency
        in: query
        required: false
        type: string
        description: Three-letter ISO currency code.
        format: iso-4217
        pattern: ^[A-Z]{3}$
      - name: amount_from
        in: query
        required: false
        type: number
        description: Minimum amount
        pattern: ^\d+(\.\d{1,3})?$
      - name: amount_to
        in: query
        required: false
        type: number
        description: Maximum amount
        pattern: ^\d+(\.\d{1,3})?$
      - name: created_at_from
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: created_at_to
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: updated_at_from
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: updated_at_to
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: completed_at_from
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: completed_at_to
        in: query
        required: false
        type: string
        format: date-time
        description: Any valid ISO 8601 format, no older than two years e.g. "2024-12-31T23:59:59Z".
      - name: creator_contact_id
        in: query
        required: false
        type: string
        description: Contact UUID of transfer instructor.
        format: uuid
      - name: creator_account_id
        in: query
        required: false
        type: string
        description: Account UUID of transfer instructor.
        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
        default: created_at
        description: The field name to sort by - "created_at", "updated_at" or "completed_at". Defaults to "created_at" if not specified..<br>
        enum:
        - created_at
        - updated_at
        - completed_at
        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.
      - name: unique_request_id
        in: query
        required: false
        type: string
        description: User-generated idempotency key.
        minLength: 1
        maxLength: 255
      responses:
        '200':
          description: Success.
          schema:
            type: object
            properties:
              transfers:
                type: array
                items:
                  $ref: '#/definitions/Transfer'
              pagination:
                $ref: '#/definitions/Pagination'
          headers:
            X-Request-Id:
              type: string
              description: A unique reference for the request.
        '400':
          description: Client error.
          x-errors:
          - code: amount_from_type_is_wrong
            category: amount_from
            message: amount_from should be of numeric type
            params: ''
          - code: amount_to_type_is_wrong
            category: amount_to
            message: amount_to should be of numeric type
            params: ''
          - code: completed_at_from_is_in_invalid_format
            category: completed_at_from
            message: completed_at_from should be in ISO 8601 format
            params: ''
          - code: completed_at_from_is_too_old
            category: completed_at_from
            message: completed_at_from is set to a date too far back
            params: ''
          - code: completed_at_to_is_in_invalid_format
            category: completed_at_to
            message: completed_at_from should be in ISO 8601 format
            params: ''
          - code: created_at_from_is_in_invalid_format
            category: created_at_from
            message: created_at_from should be in ISO 8601 format
            params: ''
          - code: created_at_from_is_too_old
            category: created_at_from
            message: created_at_from is set to a date too far back
            params: ''
          - code: created_at_to_is_in_invalid_format
            category: created_at_to
            message: created_at_from should be in ISO 8601 format
            params: ''
          - code: destination_account_id_is_not_valid_uuid
            category: destination_account_id
            message: destination_account_id should be in UUID format
            params: ''
          - code: invalid_extra_parameters
            category: extra_parameter
            message: Invalid extra parameters:'{parameter}'
            params: '{ "parameters" => "extra_parameter" }'
          - code: page_is_too_small
            category: page
            message: page can not be smaller than 1
            params: ''
          - code: page_type_is_wrong
            category: page
            message: page should be of integer type
            params: ''
          - code: per_page_is_too_big
            category: per_page
            message: per_page can not be bigger than %i
            params: ''
          - code: per_page_is_too_small
            category: per_page
            message: per_page can not be smaller than 1
            params: ''
          - code: per_page_type_is_wrong
            category: per_page
            message: per_page should be of integer type
            params: ''
          - code: source_account_id_is_not_valid_uuid
            category: source_account_id
            message: source_account_id should be in UUID format
            params: ''
          - code: status_not_in_range
            category: status
            message: 'status should be in range: pending, completed, cancelled'
            params: ''
          - code: updated_at_from_is_in_invalid_format
            category: updated_at_from
            message: updated_at_from should be in ISO 8601 format
            params: ''
          - code: updated_at_from_is_too_old
            category: updated_at_from
            message: updated_at_from is set to a date too far back
            params: ''
          - code: updated_at_to_is_in_invalid_format
            category: updated_at_to
            message: updated_at_from should be in ISO 8601 format
            params: ''
          schema:
            $ref: '#/definitions/FindTransfersError'
          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.
  /transfers/{id}/cancel:
    post:
      tags:
      - Transfers
      x-api-group: pay
      summary: Cancel Transfer
      description: Requests that a transfer be cancelled.
      operationId: CancelTransfer
      consumes:
      - multipart/form-data
      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: ID of the transfer to be cancelled.
        format: uuid
      responses:
        '200':
          description: Success.
          schema:
            $ref: '#/definitions/Transfer'
          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: account_id
            message: id should be in UUID format
            params: ''
          - code: invalid_extra_parameters
            category: invalid_extra_parameters
            message: Invalid extra parameters:'{parameter}'
            params: '{ "parameters" => "extra_parameter" }'
          - code: transfer_cannot_be_cancelled
            category: short_reference
            message: Transfer {short_reference} cannot be cancelled
            params: ''
          - code: transfer_is_already_cancelled
            category: short_reference
            message: Transfer {short_reference} is already cancelled
            params: ''
          - code: transfer_is_already_completed
            category: short_reference
            message: Transfer {short_reference} cannot be cancelled since it is already completed
            params: ''
          - code: transfer_not_found
            category: id
            message: Transfer was not found for this ID
            params: ''
          schema:
            $ref: '#/definitions/CancelTransferError'
          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.
        '403':
          description: Forbidden.
          x-errors:
          - code: permission_denied
            message: You do not have permission 'transfer_write' to perform this operation
            params: ''
          schema:
            $ref: '#/definitions/ForbiddenError'
          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.
components:
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: X-Auth-Token
definitions:
  Transfer:
    type: object
    description: Transfer
    properties:
      id:
        type: string
        description: Transfer UUID
      short_reference:
        type: string
        description: Short reference code.
      source_account_id:
        type: string
        description: Account UUID of the paying account.
      destination_account_id:
        type: string
        description: Account UUID of the receiving account.
      currency:
        type: string
        description: Three-letter ISO currency code.
      amount:
        type: string
        description: Transfer amount
      status:
        type: string
        description: Status of the transfer - completed, pending or cancelled.
      created_at:
        type: string
        description: Date/time the transfer was created.
      updated_at:
        type: string
        description: Date/time the transfer was last updated.
      completed_at:
        type: string
        description: Date/time the transfer was completed.
      creator_account_id:
        type: string
        description: Account UUID of transfer instructor.
      creator_contact_id:
        type: string
        description: Contact UUID of transfer instructor.
      reason:
        type: string
        description: Reason for the transfer.
      unique_request_id:
        type: string
        description: The user-generated idempotency key given to the transfer.
    example:
      id: 993d63bd-e151-11e6-a5af-080027a79e8f
      short_reference: BT-20200118-VMSCBS
      source_account_id: a7117404-e150-11e6-a5af-080027a79e8f
      destination_account_id: 946f2d58-e150-11e6-a5af-080027a79e8f
      currency: GBP
      amount: '1250.00'
      status: completed
      created_at: '2023-01-18T14:08:34.000Z'
      updated_at: '2023-01-18T14:08:34.000Z'
      completed_at: '2023-01-18T14:08:34.000Z'
      creator_account_id: 30cb8632-e152-11e6-a5af-080027a79e8f
      creator_contact_id: 262e3d2a-e152-11e6-a5af-080027a79e8f
      reason: Director's fees for March
      unique_request_id: 1234567890abc
  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: st

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