Make a payment. On success, returns the new payment record.

The API responses shown below are static. If you want to try out the API please login, or register for an API key

API parameters

X-Auth-Token header string Authentication token.
currency formData string Currency in which payment is made. Three-digit currency code.
beneficiary_id formData string Beneficiary UUID.
amount formData string Amount.
reason formData string User-generated reason for payment. Freeform text.
reference formData string User-generated reference code.
payment_date formData string 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. "2020-12-31.
payment_type formData string Currencycloud supports two types of payments: "priority", made using the SWIFT network; and "regular", made using the local bank network. priority
conversion_id formData string Conversion UUID.
payer_entity_type formData string Legal entity. company
payer_company_name formData string Required if "payer_entity_type" is "company".
payer_first_name formData string Required if "payer_entity_type" is "individual".
payer_last_name formData string Required if "payer_entity_type" is "individual".
payer_city formData string City.
payer_address formData string First line of address.
payer_postcode formData string Postal code.
payer_state_or_province formData string State or province.
payer_country formData string Two-letter country code.
payer_date_of_birth formData string If "payer_entity_type" is "company", company registration date. If "payer_entity_type" is "individual", date of birth. ISO 8601 format YYYY-MM-DD.
payer_identification_type formData string A legal document that verifies the identity of the payer. Required documentation will vary depending on the nationality or registered address of the payer. none
payer_identification_value formData string A unique reference code for the identification document, such as a passport number.
unique_request_id formData string User-generated idempotency key.
ultimate_beneficiary_name formData string The name of the ultimate beneficiary if different.
purpose_code formData string Payment Purpose Code (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). Visit our Help Center for more information.
on_behalf_of formData string A contact UUID for the sub-acccount 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.
charge_type formData string Payment Charges Setting value (only applicable to SWIFT payments). If empty - then account's default value is used. Do not specify for regular (local) payments. ours
fee_amount formData string Fee amount.
fee_currency formData string Currency fee is paid in.
curl -X POST  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/payments/create


    "id": "dbec7699-6508-479e-b1cf-d4fbe4bed798",
    "amount": "10.00",
    "beneficiary_id": "5824f6a3-a5a7-4c3e-acf2-5b1ed2939811",
    "currency": "GBP",
    "reference": "This is a test reference.",
    "reason": "This is a test payment.",
    "status": "ready_to_send",
    "creator_contact_id": "a66ca63f-e668-47af-8bb9-74363240d781",
    "payment_type": "regular",
    "payment_date": "2022-01-31",
    "transferred_at": "",
    "authorisation_steps_required": "0",
    "last_updater_contact_id": "a66ca63f-e668-47af-8bb9-74363240d781",
    "short_reference": "220131-R2M0R4791",
    "conversion_id": null,
    "failure_reason": "",
    "payer_id": "79a8e858-4610-4ac7-a8a6-4bb4aa6a7b66",
    "payer_details_source": "account",
    "created_at": "2022-01-31T14:30:46+00:00",
    "updated_at": "2022-01-31T14:30:46+00:00",
    "payment_group_id": null,
    "unique_request_id": null,
    "failure_returned_amount": "0.00",
    "ultimate_beneficiary_name": null,
    "purpose_code": null,
    "charge_type": null,
    "fee_amount": null,
    "fee_currency": null
Error Codes
HTTP Status Code Description Params
400 invalid_type Invalid Payment type
currency_length_is_invalid currency should be 3 character(s) long
currency_is_required currency is required
invalid_currency You cannot make payments with this currency
beneficiary_id_is_not_valid_uuid beneficiary_id should be in UUID format
beneficiary_id_is_required beneficiary_id is required
beneficiary_date_of_birth_type_is_wrong beneficiary_date_of_birth should be of date type { "type" => "date" }
beneficiary_date_of_birth_is_incorrect beneficiary_date_of_birth is incorrect
beneficiary_date_of_birth_is_earlier beneficiary_date_of_birth should be later
beneficiary_date_of_birth_is_after beneficiary_date_of_birth should be earlier
invalid_beneficiary_id Unknown beneficiary_id
payment_above_limit 3000.00 EUR exceeds the maximum amount of 2500.00 EUR for a local payment.
payer_entity_type_not_in_range payer_entity_type should be in range: individual, company
payer_entity_type_is_missing Payer entity type is missing
payer_company_name_is_missing Payer company name is missing
payer_first_name_is_missing Payer first name is missing
payer_last_name_is_missing Payer last name is missing
payer_city_is_missing Payer city is missing
unsupported_payer_country_code Payer country is not supported
payer_state_or_province_is_missing Payer state or province is missing
payer_postcode_is_missing Payer postcode is missing
payer_date_of_birth_type_is_wrong payer_date_of_birth should be of date type { "type" => "date" }
payer_date_of_birth_is_incorrect payer_date_of_birth is incorrect
payer_date_of_birth_is_earlier payer_date_of_birth should be later
payer_date_of_birth_is_after payer_date_of_birth should be earlier
identification_type_is_missing identification_type is missing
identification_type_is_invalid identification_type is invalid
identification_value_is_missing identification_value is missing
identification_value_is_invalid identification_value is invalid
invalid_conversion_id Conversion could not be found
conversion_is_already_settled The conversion is already settled
invalid_payment_date The payment date is invalid
payment_date_is_too_early The payment date cannot be sooner than the conversion date
reference_is_too_long reference can not be longer than 255 character(s)
charge_type_not_available Not available charge_type has been provided { "charge_type" => "shared, ours" }
invalid_charge_type Invalid banking_charges supplied, must be in range [ours, shared]
on_behalf_of_self You cannot act on behalf of your own Contact
contact_not_found Contact was not found for this id
on_behalf_of_charge_type_not_available Not available charge_type has been provided for on_behalf_of { "charge_type" => "shared, ours" }
duplicate_request The unique_request_id provided for this payment has already been used, please provide a new unique_request_id to successfully submit this payment
fee_amount_type_is_wrong fee_amount should be of numeric type { "type" => "numeric" }
fee_currency_is_in_invalid_format fee_currency is not a valid ISO 4217 currency code { "type" => "currency" }
unsupported_beneficiary_country_code Beneficiary country is not supported
unsupported_account The account is currently not permitted to create payments.
401 invalid_supplied_credentials Authentication failed with the supplied credentials
429 too_many_requests Too many requests have been made to the api. Please refer to the Developer Center for more information
500 internal_server_error Internal server error
503 service_unavailable Service is temporary unavailable
Was this post helpful?
Let us know if you liked the post. That’s the only way we can improve.