Currencycloud Transactions 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 Transactions 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: Transactions
  description: View balances and all pending and completed transactions in your Currencycloud account, as well as associated sub-account balances and transactions.
paths:
  /transactions/find:
    get:
      tags:
      - Transactions
      x-api-group: manage
      summary: Find Transactions
      description: Search for transactions.
      operationId: FindTransactions
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - 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: currency
        in: query
        required: false
        description: Three-letter ISO currency code.
        schema:
          type: string
          format: iso-4217
          pattern: ^[A-Z]{3}$
      - name: amount
        in: query
        required: false
        description: Amount the transaction is for.
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: amount_from
        in: query
        required: false
        description: Minimum amount
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: amount_to
        in: query
        required: false
        description: Maximum amount
        schema:
          type: string
          pattern: ^\d+(\.\d{1,3})?$
      - name: action
        in: query
        required: false
        description: The action that triggered the transaction.
        schema:
          type: string
          enum:
          - conversion
          - conversion_deposit
          - deposit_refund
          - funding
          - margin
          - manual_transaction
          - payment
          - payment_failure
          - payment_fee
          - payment_unrelease
          - transfer
      - name: related_entity_type
        in: query
        required: false
        description: The related entity that created the transaction.<br> For information, the related_entity_type for margin transactions is <b>'margin_transaction'</b>. While it isn't possible to search directly by this value, margin transactions can be filtered using the ‘action’ field and may be included in the response.
        schema:
          type: string
          enum:
          - conversion
          - deposit
          - inbound_funds
          - payment
          - transfer
      - name: related_entity_id
        in: query
        required: false
        description: UUID of the related entity.
        schema:
          type: string
          format: uuid
      - name: related_entity_short_reference
        in: query
        required: false
        description: Short reference code.
        schema:
          type: string
          maxLength: 25
          minLength: 1
      - name: status
        in: query
        required: false
        description: Transaction status.
        schema:
          type: string
          enum:
          - completed
          - deleted
          - pending
      - name: type
        in: query
        required: false
        description: Whether the transaction debits or credits the account balance.
        schema:
          type: string
          enum:
          - credit
          - debit
      - name: settles_at_from
        in: query
        required: false
        description: Earliest processing date. Any valid ISO 8601 format, e.g. "e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: settles_at_to
        in: query
        required: false
        description: Latest processing date. Any valid ISO 8601 format, e.g. "e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: created_at_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: created_at_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: updated_at_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: updated_at_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: completed_at_from
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: completed_at_to
        in: query
        required: false
        description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59Z".
        schema:
          type: string
          format: date-time
      - name: beneficiary_id
        in: query
        required: false
        description: Beneficiary UUID. Required if "related_entity_type" is "payment".
        schema:
          type: string
          format: uuid
      - name: currency_pair
        in: query
        required: false
        description: Concatenated string of the two currencies traded, e.g. "USDEUR". Required if "related_entity_type" is "conversion".
        schema:
          type: string
          pattern: ^[A-Z]{6}$
      - name: scope
        in: query
        required: false
        description: '"Own" account, "clients" sub-accounts, or "all" accounts.'
        schema:
          type: string
          enum:
          - all
          - clients
          - own
          default: own
      - 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: The field to sort by. Defaults to 'created_at' if not specified.<br><br> Please note that if you choose to order by 'completed_at', it's important to populate the query parameter 'status' with the value 'completed' in order to ensure that transactions are sequenced in the order they were processed. Without this, transactions that completed within the same second may not be ordered correctly.
        schema:
          type: string
          default: created_at
          maxLength: 255
          minLength: 1
      - name: order_asc_desc
        in: query
        required: false
        description: Sort results 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:
                  transactions:
                    type: array
                    items:
                      $ref: '#/components/schemas/Transaction'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
        '400':
          description: Client error.
          x-errors:
          - code: transaction_not_found
            category: id
            message: No Transaction found for 21b552e0-d97c-612d-2335-34203ab3f267
            params: ''
          - code: status_not_in_range
            category: status
            message: 'status should be in range: completed, pending, deleted'
            params: '{"range": "completed, pending, deleted" }'
          - code: amount_type_is_wrong
            category: amount
            message: amount should be of numeric type
            params: ''
          - 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: created_at_to_type_is_wrong
            category: created_as_to
            message: created_at_to should be of date type
            params: '{"type": "date"}'
          - code: completed_at_to_type_is_wrong
            category: completed_at_to
            message: completed_at_to should be of date type
            params: '{"type": "date"}'
          - code: related_entity_id_is_not_valid_uuid
            category: related_entity
            message: related_entity_id should be in UUID format
            params: ''
          - 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 cannot act on behalf of your own Contact
            params: ''
          - code: related_entity_type_not_in_range
            category: related_entity_type
            message: 'related_entity_type should be in range: conversion, payment, inbound_funds, deposit, transfer'
            params: '{ "range" => "conversion, payment, inbound_funds, deposit, transfer" }'
          - code: action_not_in_range
            category: action
            message: 'action should be in range: funding, conversion, payment, payment_failure, manual_transaction, transfer, conversion_deposit, deposit_refund, payment_unrelease, payment_fee, margin'
            params: '{ "range" => "funding, conversion, payment, payment_failure, manual_transaction,  transfer, conversion_deposit, deposit_refund, payment_unrelease, payment_fee, margin" }'
          - code: scope_not_in_range
            category: scope
            message: 'scope should be in range: own, all, clients'
            params: '{ "range" => "own, all, clients" }'
          headers:
            X-Request-Id:
              description: A unique reference for the request
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindTransactionsError'
        '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.
          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
  /transactions/{id}:
    get:
      tags:
      - Transactions
      x-api-group: manage
      summary: Get Transaction
      description: Gets a transaction record.
      operationId: GetTransaction
      parameters:
      - name: X-Auth-Token
        in: header
        required: true
        description: Authentication token
        schema:
          type: string
          minLength: 32
      - name: id
        in: path
        required: true
        description: Transaction UUID
        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/Transaction'
        '400':
          description: Client error.
          x-errors:
          - code: transaction_not_found
            category: id
            message: No Transaction found for 38f7ca23-8090-403b-bc4a-eb1ba2ac9f29
            params: '{"id": "38f7ca23-8090-403b-bc4a-eb1ba2ac9f29"}'
          - code: id_is_not_valid_uuid
            category: id
            message: id 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/GetTransactionError'
        '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.
          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:
    GetTransactionError:
      type: object
      description: 'Client error information for the Get 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
    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
    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
    FindTransactionsError:
      type: object
      description: 'Client error information for the Find Transactions 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
    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: {}
    Transaction:
      type: object
      description: Transaction.
      properties:
        id:
          type: string
          description: Transaction ID
        balance_id:
          type: string
          description: Balance ID
        account_id:
          type: string
          description: Account ID
        currency:
          type: string
          description: Three-letter ISO currency code.
        amount:
          type: string
          description: Transaction amount
        balance_amount:
          type: string
          description: Balance amount
        type:
          type: string
          description: Type (debit or credit).
          enum:
          - credit
          - debit
        action:
          type: string
          description: The action that triggered the transaction.
          enum:
          - conversion
          - conversion_deposit
          - deposit_refund
          - funding
          - margin
          - manual_transaction
          - payment
          - payment_failure
          - payment_fee
          - payment_unrelease
          - transfer
        related_entity_type:
          type: string
          description: The related entity type.
          enum:
          - balance_transfer
          - conversion
          - deposit
          - inbound_funds
          - margin_transaction
          - payment
        related_entity_id:
          type: string
        related_entity_short_reference:
          type: string
          description: Releated entity short reference.
        status:
          type: string
          description: Transaction status
          enum:
          - completed
          - deleted
          - pending
        reason:
          description: Reason
          type: string
        settles_at:
          description: Settlement date
          type: string
          format: date-time
        created_at:
          type: string
          description: Date the transaction record was created.
          format: date-time
        updated_at:
          type: string
          format: date-time
        completed_at:
          type: string
          description: Date the transaction record was last updated.
          format: date-time
      example:
        id: c5a990eb-d4d7-482f-bfb1-695261fb1e4d
        balance_id: c5f1f54e-d6d8-4140-8110-f5b99bbc80c3
        account_id: 7b9757a8-eee9-4572-86e6-77f4d711eaa6
        currency: USD
        amount: '1000.00'
        balance_amount: '2000.00'
        type: credit
        action: conversion
        related_entity_type: conversion
        related_entity_id: e93e322f-93aa-4d31-b050-449da723db0b
        related_entity_short_reference: 140416-GGJBNQ001
        status: completed
        reason: Reason for Transaction
        settles_at: '2023-12-31T23:59:59.000Z'
        created_at: '2023-12-31T23:59:59.000Z'
        updated_at: '2023-12-31T23:59:59.000Z'
        completed_at: '2023-12-31T23:59:59.000Z'
    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
externalDocs:
  description: API overview
  url: https://www.currencycloud.com/developers/