Skip to navigation
Express Instant Payments

Validating the beneficiary account details

View as Markdown

NOTE: This API will be deprecated soon. Existing users will continue to be supported for at least one year (starting November 1st, 2024) New services will be added. Please contact your Citi representative for more information.

To validate the identity of a beneficiary, create a request body using the account information and submit it to POST /beneficiaryvalidations.

You will receive a preliminary response containing a Unique End-to-End Transaction Reference (UETR). You can use this UETR to retrieve the identifying information associated with the account information you submitted.

Authentication

AuthorizationBearer

All CitiConnect APIs use the oAuth2 authentication scheme, which requires a bearer token to authenticate your API call. The Token URL includes the version of authentication used by this API. See the Citi Authentication API reference for information on requesting a token.

Headers

Idempotency-IdstringRequired<=128 characters

Your unique identification for a POST request

  • Maximum length is 128.
  • CitiConnect API responds with an error (HTTP status 4XX) if your POST request idempotency identification value is a duplicate across a recent history of idempotency identifications in Citi’s database.
  • If you don’t receive any response (HTTP status 2XX, 4XX or 5XX) from Citi to your POST request and you wish to retry, reinitiate your request with the same idempotency identification to prevent accidental duplicate payment.

Query parameters

client_idstringRequired
Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding

Request

This API allows the client to validate beneficiary details with the use of combination of fields
debtorobjectRequired
methodobjectRequired
end_to_end_idstringOptional1-35 characters

Client provided reference number.

  • For India IMPS and UPI, this field is mandatory and max length is 16
  • For US EWS,this field is not applicable
  • For UK,this field is not applicable
  • For IN PAN,this field is not applicable
  • For Pay2China, this field is not required
uetrstringOptionalformat: "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"

UUID v4 format unique end-to-end transaction reference

creditorobjectOptional

Response headers

request_idstringOptional
Citi's unique identification for your request

Response

Accepted
end_to_end_idstringOptional1-35 characters

Client provided reference number.

  • For India IMPS and UPI, this field is mandatory and max length is 16
  • For US EWS,this field is not applicable
  • For UK,this field is not applicable
  • For IN PAN,this field is not applicable
  • For Pay2China, this field is not applicable
uetrstringOptionalformat: "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"

UUID v4 format unique end-to-end transaction reference

debtorobjectOptional
creditorobjectOptional
methodobjectOptional
creation_date_timedatetimeOptional

Request Creation Date and Time in UTC generated by CitiConnect API UTC (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

statusobjectOptional

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
405
Method Not Allowed Error
409
Conflict Error
415
Unsupported Media Type Error
500
Internal Server Error