Inquire for the latest status of refund transations matching additional parameters. | Citi Docs Demo

Get the latest refund transactions statuses initiated through the refund initiation endpoint using matching criteria. Currently, you can get the latest transactions statuses up to 90 days from the refund initiation date. If the latest transactions statuses date is 90+ days, the endpoint responds with HTTP status 404 (not found).

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.

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

end_to_end_idstringOptionalformat: "^(?!\s*$).+"1-35 characters

The end to end ID included in the refund by the sender of the refund

original_payment_uetrstringOptionalformat: "^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$"

The unique ‘UETR’ reference assigned to the original incoming credit on your account for which a refund was initiated. If multiple refunds were initiated against an incoming credit, the response API will include all these refunds

creation_date_time_startdatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

Start of date time, generated by CitiConnect API, when CitiConnect API accepted a refund initiation after validation

creation_date_time_enddatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)

end of date time, generated by CitiConnect API, when CitiConnect API accepted a refund initiation after validation

instructed_amountdoubleOptional<=1000000000000000

refund amount

status_codeenumOptional

ISO 20022 transaction status code

Allowed values:

offsetintegerOptionalDefaults to 0

Payment status inquiry result page you want Citi to respond to you with

limitintegerOptional1-1000Defaults to 100

Limit you want Citi to apply to your payment status inquiry results

Maximum value is 1,000.

Response headers

request_idstringOptional

Citi's unique identification for your request

resultinteger

Number of transaction status matching your request

Response

Refund status

end_to_end_idstringformat: "^(?!\s*$).+"1-35 characters

Specifies a character string with a maximum length of 35 characters limited to character set X, that is, a-z A-Z / - ? : ( ) . , ‘ + .

If client_id + end_to_end_id combination is duplicate within 90 days, payment will be rejected
Thailand Max length 12
United State Max length 35
IN IMPS Max length 16
UK FPS Max length is 18
Brazil Max length is 35
IN UPI Max length 16
For US WIRE/ACH, Max length is 16 and allowed value is AlphaNumeric (A-Z and 0-9)
For SEPA and SEPA IDP Max length is 35
Japan Max length 35. It allows only upper alphabet characters A-Z and accepts special characters as follows . , () -

instructed_amountdouble0.01-1000000000000000

Instructed amount can be either full original transaction amount or partial amount

Thailand PromptPay - Maximum amount is 2000000.00
United States - Maximum amount is 1000000.00

instructed_currencyenum

ISO 4217 code for the transaction instructed amount currency

Allowed values:

original_paymentobject

Either populate uetr OR (end_to_end_id AND value_date) for the refund to be processed

instruction_idstringOptional1-35 characters

Instruction id on return payment

For Thailand PromptPay refunds.instruction_id field is not applicable
For Brazil refunds.instruction_id field is not applicable
For United States refunds.instruction_id field is optional
For SEPA refunds.instruction_id field is not applicable

refund_idstringOptionalformat: "^[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

creation_date_timedatetimeOptional

GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ)- Instant Payment (Debit) - Date time, generated by CitiConnect API, when CitiConnect API accepted a payment initiation after validation

Instant Payment (Credit) - Date time, either provided by the debtor bank or generated by Citi’s transaction processing application, when a transaction was created

network_idstringOptional1-128 characters

Transaction identification generated by the network (clearing)

For Thailand PromptPay refunds.network_id field is not applicable
For Brazil refunds.network_id field is optional
For United States refunds.network_id field is not applicable
For SEPA refunds.network_id field is not applicable

value_datedateOptional

Date in local time zone (e.g., EST for a United States RTP network transaction) when Citi’s transaction processing application starts processing a transaction

Format YYYY-MM-DD

additional_infostringOptional1-140 characters

Additional or remittance information

For Thailand PromptPay - Maximum length is 40
For United States refunds.additional_info field is not applicable
For Brazil refunds.additional_info field is optional
For SEPA refunds.additional_info field is not applicable

unstructured_remittance_infolist of stringsOptional

Unstructured remitance information

For TH refunds.unstructured_remittance_info field is not applicable
For US refunds.unstructured_remittance_info field is optional - Maximum length is 140 and single instance is allowed
For Brazil refunds.unstructured_remittance_info field is not applicable
For SEPA refunds.unstructured_remittance_info field is optional - Maximum length is 140 and single instance is allowed

return_reason_codeenumOptional

Reason code to initiate the refund

For TH refunds.return_reason_code field is not applicable
For US refunds.return_reason_code field is not applicable
For Brazil refunds.return_reason_code field is not applicable
For SEPA refunds.return_reason_code field is mandatory
For AU, applicable retun reason codes are AM05, AM09, BE05, CUST, FOCR, MD05, NARR
BE05 -Beneficiary does not recognize the remitter.
AC01 -Remitter sent the transaction to the wrong account.
AM02 -Transaction amount is higher than expected.
AM06 -Transaction amount is lower than expected.
AM03 -Transaction currency is incorrect.
AG01 -Transaction information is insufficient for reconciliation.
AM05 -Transaction is a duplicate.
MS01 -Other.
AM09 -Transaction amount is wrong.
CUST -Requested by customer.
FOCR -Following cancellation request.
MD05 -Collection not due.
NARR -Narrative from client

return_reason_descriptionstringOptional1-105 characters

Reason description to initiate the refund

For AU, return reason description is mandatory if return reason code is NARR

statusobjectOptional

reasonslist of objectsOptional

debtorobjectOptional

ultimate_debtorobjectOptional

Errors

400

Bad Request Error

401

Unauthorized Error

404

Not Found Error

405

Method Not Allowed Error

500

Internal Server Error