Currencycloud Payments API
Create, search, manage and action all of your domestic and international payments through this API.
OpenAPI Specification
openapi: 3.0.3
info:
title: api-onboarding Account Usage Payments API
version: v1
description: Create, search, manage and action all of your domestic and international payments through this API.
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: Payments
description: Create, search, manage and action all of your domestic and international payments through this API.
paths:
/payments/create:
post:
tags:
- Payments
x-api-group: pay
summary: Create Payment
description: Submits a payment. On success, returns the new payment record. Use the <a href="/api-reference/#get-payer-requirements">Get Payer Requirements</a> endpoint to find out what payer information needs to be provided.<br><br> Clients who are implementing Strong Customer Authentication (SCA) for payments should refer to our <a href="../guides/integration-guides/sca_sponsored_api_payments">integration guide</a>.
operationId: CreatePayment
consumes:
- multipart/form-data
produces:
- application/json
parameters:
- name: X-Auth-Token
in: header
required: true
type: string
description: Authentication token
minLength: 32
- name: x-sca-id
in: header
required: false
type: string
description: UUID to correlate to the SCA request generated when Validate Payment was called.
format: uuid
- name: x-sca-token
in: header
required: false
type: string
description: The OTP received following the Validate Payment request when SCA was required.
pattern: ^\d{6}$
- name: currency
in: formData
required: true
type: string
description: Currency in which payment is made. Three-letter ISO currency code.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: beneficiary_id
in: formData
required: true
type: string
description: Beneficiary UUID
format: uuid
- name: amount
in: formData
required: true
type: string
description: Amount
pattern: ^\d+(\.\d{1,3})?$
- name: reason
in: formData
required: true
type: string
description: User-generated reason for payment - freeform text.
minLength: 1
maxLength: 255
- name: reference
in: formData
required: true
type: string
description: User-generated reference code.
minLength: 1
maxLength: 255
- name: unique_request_id
in: formData
required: true
type: string
description: User-generated idempotency key.
minLength: 1
maxLength: 255
- name: payment_date
in: formData
required: false
type: string
description: Instructed date of payment - on this date we will attempt to debit funds on the account and submit the payment to the scheme. If the payment cannot be submitted before the cut-off (i.e. due to lack of funding), we will re-attempt on the next working day. Defaults to the earliest possible date if not passed as parameter. Any valid ISO 8601 format, e.g. "2023-12-31.
format: date
- name: payment_type
in: formData
required: false
type: string
enum:
- priority
- regular
description: 'Currencycloud supports two types of payments: "priority", made using the Swift network; and "regular", made using the local bank network.'
- name: conversion_id
in: formData
required: false
type: string
description: Conversion UUID
format: uuid
- name: payer_entity_type
in: formData
required: false
type: string
enum:
- company
- individual
description: Legal entity
- name: payer_company_name
in: formData
required: false
type: string
description: Required if "payer_entity_type" is "company".
minLength: 1
maxLength: 255
- name: payer_first_name
in: formData
required: false
type: string
description: Required if "payer_entity_type" is "individual".
minLength: 1
maxLength: 255
- name: payer_last_name
in: formData
required: false
type: string
description: Required if "payer_entity_type" is "individual". Cannot contain any numbers or company signifiers.
minLength: 1
maxLength: 255
- name: payer_city
in: formData
required: false
type: string
description: City name, should not consist of only numbers.
minLength: 1
maxLength: 255
- name: payer_address
in: formData
required: false
type: string
description: First line of address.
minLength: 1
maxLength: 255
- name: payer_postcode
in: formData
required: false
type: string
description: Postal code
minLength: 1
maxLength: 255
- name: payer_state_or_province
in: formData
required: false
type: string
description: State or province.
minLength: 1
maxLength: 255
- name: payer_country
in: formData
required: false
type: string
description: Two-letter ISO country code.
format: iso3166-1-alpha-2
pattern: ^[A-Z]{2}$
- name: payer_date_of_birth
in: formData
required: false
type: string
description: If "payer_entity_type" is "company", this is the company registration date. If "payer_entity_type" is "individual", this is date of birth. ISO 8601 format YYYY-MM-DD.
format: date
- name: payer_identification_type
in: formData
required: false
type: string
enum:
- citizenship_papers
- credential_de_elector
- drivers_license
- drivers_license_canadian
- employer_identification_number
- existing_credit_card_details
- green_card
- incorporation_number
- matricula_consular
- national_id
- none
- others
- passport
- registro_federal_de_contribuyentes
- social_insurance_number
- social_security_number
- visa
description: A legal document that verifies the identity of the payer. Required documentation will vary depending on the nationality or registered address of the payer.
- name: payer_identification_value
in: formData
required: false
type: string
description: A unique reference code for the identification document, such as a passport number.
minLength: 1
maxLength: 255
- name: ultimate_beneficiary_name
in: formData
required: false
type: string
description: The name of the ultimate beneficiary if different.
minLength: 1
maxLength: 255
- name: purpose_code
in: formData
required: false
type: string
description: <a href="https://support.currencycloud.com/hc/en-gb/articles/360017430000-Payment-Purpose-Codes">Payment Purpose Code</a> (Mandatory for all local INR and MYR payments, Swift CNY payments, and Swift payments in any currency to banks in Bahrain or the United Arab Emirates).
minLength: 1
maxLength: 255
- name: on_behalf_of
in: formData
required: false
type: string
description: A contact UUID for the sub-account you're acting on behalf of. Payer details parameters should not be sent if using on_behalf_of, they will be populated using the details from the sub-account.
format: uuid
- name: charge_type
in: formData
required: false
type: string
enum:
- ours
- shared
description: Payment Charges Setting value (only applicable to Swift payments). If this is left empty, the account's default value is used. Do not specify for regular (local) payments.
- name: fee_amount
in: formData
required: false
type: string
description: Fee amount
pattern: ^\d+(\.\d{1,3})?$
- name: fee_currency
in: formData
required: false
type: string
description: Currency fee is paid in.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: invoice_number
in: formData
required: false
type: string
description: The invoice number related to the payment. Necessary when making business-related INR payments, check our <a href="https://support.currencycloud.com/hc/en-gb/articles/360017430000-Payment-Purpose-Codes">support article</a> to see if this applies to your purpose code. Can be up to 30 characters. Mandatory if supplying `invoice_date`.<br> For NOK payments, this field can optionally be used to provide the KID (Kundle ID). If supplied, the KID should be 2-25 digits.
pattern: ^[a-zA-Z0-9]{1,30}$
- name: invoice_date
in: formData
required: false
type: string
description: The date of the invoice related to the payment. Necessary when making business-related INR payments, check our <a href="https://support.currencycloud.com/hc/en-gb/articles/360017430000-Payment-Purpose-Codes">support article</a> to see if this applies to your purpose code. ISO 8601 format YYYY-MM-DD. Mandatory if supplying `invoice_number`.
format: date
- name: payer_ultimate_account_number
in: formData
required: false
type: string
maxLength: 35
description: The payer's payment account number.
responses:
'200':
description: Success.
schema:
$ref: '#/definitions/Payment'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: invalid_type
category: type
message: Invalid Payment type
params: ''
- code: currency_length_is_invalid
category: currency
message: currency should be 3 character(s) long
params: ''
- code: currency_is_required
category: currency
message: currency is required
params: ''
- code: invalid_currency
category: currency
message: You cannot make payments with this currency
params: ''
- code: beneficiary_id_is_not_valid_uuid
category: beneficiary_id
message: beneficiary_id should be in UUID format
params: ''
- code: beneficiary_id_is_required
category: beneficiary_id
message: beneficiary_id is required
params: ''
- code: beneficiary_date_of_birth_type_is_wrong
category: beneficiary_date_of_birth
message: beneficiary_date_of_birth should be of date type
params: '{ "type" => "date" }'
- code: beneficiary_date_of_birth_is_incorrect
category: beneficiary_date_of_birth
message: beneficiary_date_of_birth is incorrect
params: ''
- code: beneficiary_date_of_birth_is_earlier
category: beneficiary_date_of_birth
message: beneficiary_date_of_birth should be later
params: ''
- code: beneficiary_date_of_birth_is_after
category: beneficiary_date_of_birth
message: beneficiary_date_of_birth should be earlier
params: ''
- code: invalid_beneficiary_id
category: beneficiary_id
message: Unknown beneficiary_id
params: ''
- code: payment_above_limit
category: amount
message: ${amount} ${currency} exceeds the maximum amount of ${limit} ${currency} for a local payment
params: ''
- code: payer_entity_type_not_in_range
category: payer_entity_type
message: 'payer_entity_type should be in range: individual, company'
params: ''
- code: payer_details_are_missing
category: payer_entity_type
message: 'Following payer details are missing: payer_entity_type, payer_company_name, payer_first_name, payer_last_name, payer_city, payer_address, payer_state_or_province, payer_postcode, payer_country, payer_date_of_birth, payer_identification_type, payer_identification_value, payer_ultimate_account_number'
params: '{"missing_details" => "payer_entity_type, payer_company_name, payer_first_name, payer_last_name, payer_city, payer_address, payer_state_or_province, payer_postcode, payer_country, payer_date_of_birth, payer_identification_type, payer_identification_value, payer_ultimate_account_number"}'
- code: payer_entity_type_is_missing
category: payer_entity_type
message: Payer entity type is missing
params: ''
- code: payer_company_name_is_missing
category: payer_company_name
message: Payer company name is missing
params: ''
- code: payer_first_name_is_missing
category: payer_first_name
message: Payer first name is missing
params: ''
- code: payer_last_name_is_missing
category: payer_last_name
message: Payer last name is missing
params: ''
- code: payer_city_is_missing
category: payer_city
message: Payer city is missing
params: ''
- code: unsupported_payer_country_code
category: payer_country_code
message: Payer country is not supported
params: ''
- code: payer_state_or_province_is_missing
category: payer_state_or_province
message: Payer state or province is missing
params: ''
- code: payer_postcode_is_missing
category: payer_postcode
message: Payer postcode is missing
params: ''
- code: payer_date_of_birth_type_is_wrong
category: payer_date_of_birth
message: payer_date_of_birth should be of date type
params: '{ "type" => "date" }'
- code: payer_date_of_birth_is_incorrect
category: payer_date_of_birth
message: payer_date_of_birth is incorrect
params: ''
- code: payer_date_of_birth_is_earlier
category: payer_date_of_birth
message: payer_date_of_birth should be later
params: ''
- code: payer_date_of_birth_is_after
category: payer_date_of_birth
message: payer_date_of_birth should be earlier
params: ''
- code: identification_type_is_missing
category: payer_identification_type
message: identification_type is missing
params: ''
- code: identification_type_is_invalid
category: payer_identification_type
message: identification_type is invalid
params: ''
- code: identification_value_is_missing
category: payer_identification_value
message: identification_value is missing
params: ''
- code: identification_value_is_invalid
category: payer_identification_value
message: identification_value is invalid
params: ''
- code: invalid_conversion_id
category: conversion_id
message: Conversion could not be found
params: ''
- code: conversion_is_already_settled
category: conversion_id
message: The conversion is already settled
params: ''
- code: invalid_payment_date
category: payment_date
message: The payment date is invalid
params: ''
- code: payment_date_is_too_early
category: payment_date
message: The payment date cannot be sooner than the conversion date
params: ''
- code: reference_is_too_long
category: reference
message: reference can not be longer than 255 character(s)
params: ''
- code: charge_type_not_available
category: charge_type
message: Not available charge_type has been provided
params: '{ "charge_type" => "shared, ours" }'
- code: invalid_charge_type
category: charge_type
message: Invalid banking_charges supplied, must be in range [ours, shared]
params: ''
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
- code: on_behalf_of_charge_type_not_available
category: on_behalf_of
message: Not available charge_type has been provided for on_behalf_of
params: '{ "charge_type" => "shared, ours" }'
- code: duplicate_request
category: duplicate_request
message: The unique_request_id provided for this payment has already been used, please provide a new unique_request_id to successfully submit this payment
params: ''
- code: fee_amount_type_is_wrong
category: fee_amount
message: fee_amount should be of numeric type
params: '{ "type" => "numeric" }'
- code: fee_currency_is_in_invalid_format
category: fee_currency
message: fee_currency is not a valid ISO 4217 currency code
params: '{ "type" => "currency" }'
- code: unsupported_beneficiary_country_code
category: beneficiary_country_code
message: Beneficiary country is not supported
params: ''
- code: unsupported_account
category: account
message: The account is currently not permitted to create payments.
params: ''
- code: invalid_extra_parameters
category: base
message: Invalid extra parameters extra_parameter
params: '{ "parameters" => "extra_parameter" }'
- code: invalid_fee_amount_format
category: fee_amount
message: ${FEE_CURRENCY} only supports up to ${CURRENCY_NUMBER_OF_DECIMAL_PLACES} decimal places
params: ''
- code: payer_details_not_allowed
category: payer_details
message: This account is not allowed to pass payer details
params: ''
- code: unique_request_id_is_required
category: unique_request_id_is_required
message: unique_request_id is required
params: ''
- code: invoice_number_parameter_invalid
category: invoice_number
message: Invoice number can only contain alphanumeric characters and must be 30 characters or less
- code: invoice_number_missing
category: invoice_number
message: Invoice number is missing for provided invoice date $invoiceDate
- code: invalid_invoice_date
category: invoice_date
message: Invoice date must follow YYYY-MM-DD format
- code: invoice_date_missing
category: invoice_date
message: Invoice date is missing for provided invoice number $invoiceNumber
- code: incorrect_purpose_code
category: purpose_code
message: Purpose code is invalid
- code: field_contains_invalid_characters
category: base
message: Field contains invalid characters
params: '{ ${field_name}: ${character_range} }'
- code: field_is_too_long
category: base
message: The information provided for this request exceeds our field length limits
params: '{ ${field_name}: ${max_field_length} }'
- code: request_contains_blocked_fields
category: base
message: This request contains fields that are not permitted for this route
params: '{ "blocked fields": [Fields that are not permitted for this route] }'
schema:
$ref: '#/definitions/CreatePaymentError'
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.
/payments/find:
get:
tags:
- Payments
x-api-group: pay
summary: Find Payments
description: Searches for payment records.
operationId: FindPayments
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: currency
in: query
required: false
type: string
description: Currency in which payment was made. Three-letter ISO currency code.
format: iso-4217
pattern: ^[A-Z]{3}$
- name: amount
in: query
required: false
type: string
description: Exact amount
pattern: ^\d+(\.\d{1,3})?$
- name: amount_from
in: query
required: false
type: string
description: Minimum amount
pattern: ^\d+(\.\d{1,3})?$
- name: amount_to
in: query
required: false
type: string
description: Maximum amount
pattern: ^\d+(\.\d{1,3})?$
- name: status
in: query
required: false
type: string
enum:
- awaiting_authorisation
- authorised
- completed
- deleted
- failed
- new
- ready_to_send
- released
- submitted
- suspended
description: Payment status
- name: reason
in: query
required: false
type: string
description: User-generated reason for payment. Freeform text.
minLength: 1
maxLength: 255
- name: payment_date_from
in: query
required: false
type: string
format: date
description: Earliest instructed payment date. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: payment_date_to
in: query
required: false
type: string
format: date
description: Latest instructed payment date. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: transferred_at_from
in: query
required: false
type: string
format: date-time
description: Earliest date of payment processing. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: transferred_at_to
in: query
required: false
type: string
format: date-time
description: Latest date of payment processing. Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: created_at_from
in: query
required: false
type: string
format: date-time
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: created_at_to
in: query
required: false
type: string
format: date-time
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: updated_at_from
in: query
required: false
type: string
format: date-time
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: updated_at_to
in: query
required: false
type: string
format: date-time
description: Any valid ISO 8601 format, e.g. "2023-12-31T23:59:59+00:00".
- name: beneficiary_id
in: query
required: false
type: string
description: Beneficiary UUID
format: uuid
- name: conversion_id
in: query
required: false
type: string
description: Conversion UUID
format: uuid
- name: with_deleted
in: query
required: false
type: boolean
default: false
description: Include deleted payments.
- name: payment_group_id
in: query
required: false
type: string
description: Payment group.
minLength: 1
maxLength: 255
- name: unique_request_id
in: query
required: false
type: string
description: User-generated idempotency key.
minLength: 1
maxLength: 255
- name: scope
in: query
required: false
type: string
enum:
- all
- clients
- own
default: own
description: '"Own" account, "clients" sub-accounts, or "all" accounts.'
- name: bulk_upload_id
in: query
required: false
type: string
description: Bulk upload reference code.
minLength: 1
maxLength: 255
- 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
description: Any field name to change the sort order.
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: charge_type
in: query
required: false
type: string
enum:
- ours
- shared
description: Payment Charges Setting value (only applicable to Swift payments). Limits the search results to payments of the specified <a href="https://support.currencycloud.com/hc/en-gb/articles/360017430820-Selecting-payment-charges-for-SWIFT-payments-FAQ">charge type</a>.
- name: review_status
in: query
required: false
type: string
enum:
- in_review
- passed
- rejected
description: Compliance review status.
responses:
'200':
description: Success.
schema:
type: object
properties:
payments:
type: array
items:
$ref: '#/definitions/Payment'
pagination:
$ref: '#/definitions/Pagination'
headers:
X-Request-Id:
type: string
description: A unique reference for the request.
'400':
description: Client error.
x-errors:
- code: invalid_currency
category: id
message: currency has invalid format
params: ''
- code: charge_type_not_available
category: charge_type
message: Not available charge_type has been provided
params: '{ "charge_type" => "shared, ours" }'
- code: invalid_charge_type
category: charge_type
message: Invalid banking_charges supplied, must be in range [ours, shared]
params: ''
- code: on_behalf_of_self
category: on_behalf_of
message: You cannot act on behalf of your own Contact
params: ''
- code: contact_not_found
category: on_behalf_of
message: Contact was not found for this id
params: ''
- code: on_behalf_of_charge_type_not_available
category: on_behalf_of
message: Not available charge_type has been provided for on_behalf_of
params: '{ "charge_type" => "shared, ours" }'
- code: status_not_in_range
category: status
message: 'status should be in range: new, ready_to_send, completed, failed, released, suspended, awaiting_authorisation, submitted, authorised, deleted"'
params: '{ "range" => "new, ready_to_send, completed, failed, released, suspended, awaiting_authorisation, submitted, authorised, deleted" }'
- code: review_status_not_in_range
category: review_status
message: 'review_status should be in range: passed, in_review, rejected'
params: '{ "range" => "passed, in_review, rejected" }'
- code: invalid_extra_parameters
category: base
message: Invalid extra parameters extra_parameter
params: '{ "parameters" => "extra_parameter" }'
schema:
$ref: '#/definitions/FindPaymentsError'
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.
# --- truncated at 32 KB (165 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/currencycloud/refs/heads/main/openapi/currencycloud-payments-api-openapi.yml