/v2/beneficiaries/validate

POST

Validate a new beneficiary's bank details, without actually creating a record of the beneficiary. On success, returns an object that represents the entity that would be created if the beneficiary were saved.

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
NameInTypeDescriptionEnumItemsDefault
X-Auth-Token header string Authentication token.
bank_country formData string Two-letter code for the country in which the beneficiary's bank account is held.
currency formData string Currency in which money is held in the beneficiary's bank account. Three-digit currency code.
Optional
NameInTypeDescriptionEnumItemsDefault
beneficiary_address formData string First line of address.
beneficiary_country formData string Two-letter country code. If the beneficiary is a company, the country in which the company is registered. If the beneficiary is an individual, a country in which the beneficiary holds nationality.
account_number formData string Bank account number.
routing_code_type_1 formData string Local payment routing system. sort_code
aba
bsb_code
institution_no
bank_code
branch_code
clabe
cnaps
routing_code_value_1 formData string Routing code for "routing_code_type_1".
routing_code_type_2 formData string Local payment routing system. sort_code
aba
bsb_code
institution_no
bank_code
branch_code
clabe
cnaps
routing_code_value_2 formData string Routing code for "routing_code_type_2".
bic_swift formData string BIC/SWIFT code.
iban formData string IBAN code.
bank_address formData string First line of address.
bank_name formData string Bank name.
bank_account_type formData string Bank account type. checkings
savings
beneficiary_entity_type formData string Legal entity. individual
company
beneficiary_company_name formData string Required if "beneficiary_entity_type" is "company".
beneficiary_first_name formData string Required if "beneficiary_entity_type" is "individual".
beneficiary_last_name formData string Required if "beneficiary_entity_type" is "individual".
beneficiary_city formData string City.
beneficiary_postcode formData string Postal code.
beneficiary_state_or_province formData string State or province.
beneficiary_date_of_birth formData string If "beneficiary_entity_type" is "company", date of registration. If "beneficiary_entity_type" is "individual", date of birth. ISO 8601 format YYYY-MM-DD.
beneficiary_identification_type formData string A legal document that verifies the identity of the beneficiary. Required documentation will vary depending on the country in which the beneficiary's bank account is held. none
drivers_license
social_security_number
green_card
passport
visa
matricula_consular
registro_federal_de_contribuyentes
clave_unica_de_registro_de_poblacion
credential_de_elector
social_insurance_number
citizenship_papers
drivers_license_canadian
existing_credit_card_details
employer_identification_number
national_id
incorporation_number
others
beneficiary_identification_value formData string A unique reference code for the identification document, such as a passport number.
payment_types[] formData array Currencycloud supports two types of payments: "priority", made using the SWIFT network; and "regular", made using the local bank network. string
Array
 regular
on_behalf_of formData string A contact UUID for the sub-acccount you're acting on behalf of. 
curl -X POST  --header "X-Auth-Token: XXXX-XXXXX-XXXX"  https://devapi.currencycloud.com/v2/beneficiaries/validate

Response

{
    "payment_types": [
        "regular"
    ],
    "bank_country": "GB",
    "bank_name": "TEST BANK NAME",
    "bank_account_type": null,
    "currency": "GBP",
    "account_number": "32847346",
    "routing_code_type_1": "sort_code",
    "beneficiary_address": [],
    "beneficiary_country": null,
    "beneficiary_entity_type": null,
    "beneficiary_company_name": null,
    "beneficiary_first_name": null,
    "beneficiary_last_name": null,
    "beneficiary_city": null,
    "beneficiary_postcode": null,
    "beneficiary_state_or_province": null,
    "beneficiary_date_of_birth": null,
    "beneficiary_identification_type": null,
    "beneficiary_identification_value": null,
    "routing_code_value_1": "101193",
    "routing_code_type_2": null,
    "routing_code_value_2": null,
    "bic_swift": null,
    "iban": null,
    "bank_address": [
        "TEST BANK ADDRESS",
        " NOT USING EXTERNAL SERVICE",
        " DEVELOPMENT ENVIRONMENT."
    ]
}
Error Codes
HTTP Status Code Description Params
400 beneficiary_country_is_required beneficiary_country is required
beneficiary_country_is_in_invalid_format beneficiary_country is in invalid format
beneficiary_entity_type_not_in_range beneficiary_entity_type should be in range: individual, company { "range" => "individual, company" }
beneficiary_entity_type_is_missing Beneficiary entity type is missing
beneficiary_company_name_is_missing Beneficiary company name is missing
beneficiary_first_name_is_missing Beneficiary first name is missing
beneficiary_last_name_is_missing Beneficiary last name is missing
beneficiary_city_is_missing Beneficiary city is missing
beneficiary_state_or_province_is_missing Beneficiary state or province is missing
beneficiary_state_or_province_is_not_supported Beneficiary state or province is not supported
beneficiary_postcode_is_missing Beneficiary postcode is missing
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
account_number_is_too_short account_number can not be shorter than 1 character(s) { "minlength" => 1 }
account_number_is_too_long account_number can not be longer than 50 character(s) { "maxlength" => 50 }
account_number_is_missing Account number is missing
account_number_is_invalid Account number is in invalid format
routing_code_value_1_is_too_short routing_code_value_1 can not be shorter than 1 character(s) { "minlength" => 1 }
routing_code_value_1_is_too_long routing_code_value_1 can not be longer than 50 character(s) { "maxlength" => 50 }
routing_code_value_2_is_too_short routing_code_value_2 can not be shorter than 1 character(s) { "minlength" => 1 }
routing_code_value_2_is_too_long routing_code_value_2 can not be longer than 50 character(s) { "maxlength" => 50 }
iban_is_too_short iban can not be shorter than 1 character(s) { "minlength" => 1 }
iban_is_too_long iban can not be longer than 34 character(s) { "maxlength" => 34 }
iban_is_missing IBAN is missing
iban_is_invalid IBAN is in invalid format
bic_swift_is_too_short bic_swift can not be shorter than 1 character(s) { "minlength" => 1 }
bic_swift_is_too_long bic_swift can not be longer than 11 character(s) { "maxlength" => 11 }
bic_swift_is_missing BIC/SWIFT is missing
bic_swift_is_invalid BIC/SWIFT is in invalid format
bank_address_is_missing Bank address is missing
bank_address_is_too_short bank_address can not be shorter than 1 character(s) { "minlength" => 1 }
bank_address_is_too_long bank_address can not be longer than 100 character(s) { "maxlength" => 100 }
bank_name_is_too_short bank_name can not be shorter than 1 character(s) { "minlength" => 1 }
bank_name_is_too_long bank_name can not be longer than 100 character(s) { "maxlength" => 100 }
bank_name_is_missing Bank name is missing
bank_name_is_invalid Bank name is in invalid format
bank_account_type_not_in_range bank_account_type should be in range: checking, savings { "range" => "checking, savings" }
bank_account_type_is_missing Beneficiary bank account type is missing
routing_code_type_1_not_in_range routing_code_type_1 should be in range: sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps { "range" => "sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps" }
routing_code_type_2_not_in_range routing_code_type_2 should be in range: sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps { "range => "sort_code, bsb_code, institution_no, bank_code, branch_code, aba, clabe, cnaps" }
bank_country_is_required bank_country is required
bank_country_is_in_invalid_format bank_country is in invalid format
bank_country_is_not_supported bank_country is not supported
currency_is_required currency is required
currency_is_in_invalid_format currency is in invalid format
currency_code_is_invalid You can not use this currency with beneficiaries
unique_value_parameters Following parameters should not have same values: routing_code_type_1, routing_code_type_2 { "parameters" => "routing_code_type_1, routing_code_type_2" }
beneficiary_create_failed Beneficiary was not created
beneficiary_details_are_missing Following beneficiary details are missing: beneficiary_company_name { "missing_details" => ["beneficiary_company_name"] }
payment_types_not_in_range payment_types should be in range: priority, regular { "range" => "priority, regular" }
sort_code_is_missing Sort code is missing
sort_code_is_invalid Sort code is in invalid format
aba_is_missing ABA is missing
aba_is_invalid ABA is in invalid format
bsb_code_is_missing BSB code is missing
bsb_code_is_invalid BSB code is in invalid format
branch_code_is_missing Branch code is missing
branch_code_is_invalid Branch code is in invalid format
institution_no_is_missing Institution no is missing
institution_no_is_invalid Institution no is in invalid format
bank_code_is_missing Bank code is missing
bank_code_is_invalid Bank code is in invalid format
clabe_is_missing CLABE is missing
clabe_is_invalid CLABE is in invalid format
beneficiary_update_failed Beneficiary was not updated
on_behalf_of_self You cannot act on behalf of your own Contact
contact_not_found Contact was not found for this id
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