Currencycloud Payments API

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