Skip to navigation
Express Instant Payments

Initiate an outgoing instant refund credit transfer.

View as Markdown

Return an incoming payment transaction to the sender using either the “end_to_end_id” and “value_date”, or “UETR”. The response to a refund transaction is asynchronous, which is either through a GET Refund request or as a push notification via webhook.

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

Return an incoming payment transaction to the sender using either the “end_to_end_id” and “value_date”, or “UETR”. The response to a refund transaction is asynchronous, which is either through a GET Refund request or as a push notification via webhook.

end_to_end_idstringRequiredformat: "^(?!\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_amountdoubleRequired0.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_currencyenumRequired
ISO 4217 code for the transaction instructed amount currency
Allowed values:
original_paymentobjectRequired

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
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
debtorobjectOptional
ultimate_debtorobjectOptional

Response headers

request_idstringOptional
Citi's unique identification for your request

Response

Accepted
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
409
Conflict Error
415
Unsupported Media Type Error
500
Internal Server Error