/v2/payments/{id}

POST

Update a payment. On success, returns the updated payment entity.

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

Required
NameInTypeDescriptionEnum
X-Auth-Token header string Authentication token.
id path string Payment UUID.
Optional
NameInTypeDescriptionEnum
with_deleted query boolean Include deleted payments.
currency formData string Currency in which the payment is being made. Three-digit currency code.
beneficiary_id formData string Beneficiary UUID.
amount formData string Payment amount.
payment_date formData string Instructed date of payment. Any valid ISO 8601 format, eg. "2020-12-31".
reason formData string User-generated reason for payment. Freeform text.
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
regular
reference formData string User-generated reference code.
conversion_id formData string Conversion UUID.
payer_entity_type formData string Legal entity. company
individual
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
drivers_license
social_security_number
green_card
passport
visa
matricula_consular
registro_federal_de_contribuyentes
credential_de_elector
social_insurance_number
citizenship_papers
drivers_license_canadian
existing_credit_card_details
employer_identification_number
national_id
others
incorporation_number
payer_identification_value formData string A unique reference code for the identification document, such as a passport number.
payer_details_source formData string Source for payer details: the "account" or "payer" record. account
payer
ultimate_beneficiary_name formData string The name of the ultimate beneficiary if different.
purpose_code formData string Payment Purpose Code (Mandatory for all INR payments).
on_behalf_of formData string A contact UUID for the sub-acccount you're acting on behalf of.
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
shared
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/{id}

Response

{
    "id": "dbec7699-6508-479e-b1cf-d4fbe4bed798",
    "amount": "10.00",
    "beneficiary_id": "5824f6a3-a5a7-4c3e-acf2-5b1ed2939811",
    "currency": "GBP",
    "reference": "This is a updated test reference.",
    "reason": "This is a updated 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:50+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 currency_type_is_wrong XYZ is not a valid ISO 4217 currency code
invalid_currency You cannot make payments with this currency
id_is_not_valid_uuid id should be in UUID format
beneficiary_id_is_not_valid_uuid beneficiary_id should be in UUID format
invalid_beneficiary_id Unknown beneficiary_id
invalid_beneficiary_currency You cannot assign this Beneficiary to the Payment as it is the incorrect currency
amount_type_is_wrong amount should be of numeric type { "type" => "numeric" }
payment_above_limit 3000.00 EUR exceeds the maximum amount of 2500.00 EUR for a local payment. { "amount" => 3000.0, "ccy" => "EUR", "limit" => 2500.0 }
invalid_amount_for_order The payment amount is more than the value of the order
payment_type_not_in_range payment_type should be in range: priority, regular
invalid_conversion_id Conversion could not be found.
conversion_id_is_not_valid_uuid conversion_id should be in UUID format
invalid_payment_date The payment date is invalid
payment_date_is_in_invalid_format payment_date should be in ISO 8601 format
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) { "maxlength" => 255 }
payment_can_not_be_edited Sorry this Payment has already been processed and you are unable to Edit it
extra_dependent_params Parameters payer_entity_type, payer_company_name, payer_first_name, payer_last_name, payer_address, payer_country, payer_postcode, payer_state_or_province, payer_date_of_birth, payer_identification_type, payer_identification_value can't be provided in the same request with 'payer_details_source' with value 'account'
payer_entity_type_not_in_range payer_entity_type should be in range: individual, company { "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
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
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
payment_not_found Payment was not found for this id
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" }
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" }
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.
Yes
No

Start your borderless payments journey today

GET STARTED