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..
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: 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: {} CreateTransferError: type: object description: Client error information for the Create Transfer 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 CancelTransferError: type: object description: 'Client error information for the Cancel Transfer 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 FindTransfersError: type: object description: 'Client error information for the Find Transfers 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 ForbiddenError: type: object description: Permission 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 on what permissions are missing so that the request could not be fulfilled additionalProperties: type: array items: type: object description: An object that represents the reasons why the request was not permitted. 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 GetTransferError: type: object description: 'Client error information for the Get Transfer 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 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