> This page is for Enterprise. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://citi-demo.ferndocs.com/enterprise/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/enterprise/_mcp/server. # Inquire for the latest status of a transaction using refund_id. GET https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/{refund_id} "Get the latest refund transaction status initiated through the refund initiation endpoint. Currently, you can get the latest transaction status up to 90 days from the refund initiation date. If the latest transaction status date is 90+ days, the endpoint responds with HTTP status 404 (not found)" Reference: https://citi-demo.ferndocs.com/enterprise/enterprises/api-reference/payment-services/instant-payments/express-instant-payments/get-refund ## Authentication - `Authorization` header (bearer token, required) — 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. ## Servers - `https://b2b.api.icg.citi.com/citiconnect/prod` (production gateway url, default) - `https://sandbox.b2b.api.icg.citi.com/citiconnect/sb` (sbox url ) ## Request ### Path parameters - `refund_id` (string, required) — Unique Refund reference Id, generated during refund initiation and provided to you in the synchronous response to your refund POST request ### Query parameters - `client_id` (string, required) — Your unique identification, same as the identification you use for OAuth token generation, Citi shared with you during your CitiConnect API onboarding ## Response ### 200 OK - `end_to_end_id` (string, required) — 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_amount` (double, required) — 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_currency` (enum, required) — ISO 4217 code for the transaction instructed amount currency - Allowed values: `THB`, `BRL`, `USD`, `EUR`, `AUD` - `original_payment` (Original-Payment, required) — Either populate uetr OR (end_to_end_id AND value_date) for the refund to be processed - `instruction_id` (string, optional) — 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_id` (string, optional) — UUID v4 format unique end-to-end transaction reference - `creation_date_time` (datetime, optional) — 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_id` (string, optional) — 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_date` (date, optional) — 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_info` (string, optional) — 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_info` (list of string, optional) — 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_code` (enum, optional) — 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 - Allowed values: `BE05`, `AC01`, `AM02`, `AM03`, `AM05`, `AM06`, `AG01`, `MS01`, `AM09`, `CUST`, `FOCR`, `MD05`, `NARR` - `return_reason_description` (string, optional) — Reason description to initiate the refund - For AU, return reason description is mandatory if return reason code is NARR - `status` (Refund-Status, optional) - `reasons` (list of Reason, optional) - `debtor` (Debtor-Refund, optional) - `ultimate_debtor` (Ultimate-Debtor-Refund, optional) ## Errors ### 400 Bad Request Error Bad Request - `ref_id` (string, optional) — Unique ID for the Transaction - `error_details` (list of Error-Detail, optional) ### 401 Unauthorized Error Unauthorized - `ref_id` (string, optional) — Unique ID for the Transaction - `error_details` (list of Error-Detail, optional) ### 404 Not Found Error Not Found - `ref_id` (string, optional) — Unique ID for the Transaction - `error_details` (list of Error-Detail, optional) ### 405 Method Not Allowed Error Method Not Allowed - `ref_id` (string, optional) — Unique ID for the Transaction - `error_details` (list of Error-Detail, optional) ### 500 Internal Server Error Internal Server Error - `ref_id` (string, optional) — Unique ID for the Transaction - `error_details` (list of Error-Detail, optional) ## Types ### Original-Payment Either populate uetr OR (end_to_end_id AND value_date) for the refund to be processed - `end_to_end_id` (string, optional) — 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 . , () - - `uetr` (string, optional) — UUID v4 format unique end-to-end transaction reference - `value_date` (date, optional) — Format YYYY-MM-DD 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 - `instructed_amount` (double, optional) — Instructed amount - Thailand PromptPay - Maximum amount is 2000000.00 - United States - Maximum amount is 1000000.00 - SEPA - Maximum amount is 1000000.00 - `instructed_currency` (enum, optional) — ISO 4217 code for the transaction instructed amount currency - Allowed values: `THB`, `USD`, `BRL`, `EUR` ### Refund-Status - `date_time` (datetime, required) — GMT (ISO 8601 YYYY-MM-DDTHH:MM:SS.sssZ) - Date time of transaction status - `code` (enum, required) — ISO 20022 transaction status code - Allowed values: `ACCC`, `ACTC`, `RJCT` - `description` (string, required) — Status code description - ACTC - Accepted - ACCC - Completed - RJCT - Rejected - `type` (enum, optional) — Refund Status P - Partial Refund F - Full Refund - Allowed values: `P`, `F` ### Reason - `code` (string, optional) — Reason codes (e.g., AM03,AM02,AC02,CH03,CH04,CH20,CH21,BE23,NARR and etc.) - refer to validation_code_description excel file for complete list of response codes and descriptions - `description` (string, optional) — Reason code description (e.g., - AM03 -Method instructed currency is invalid (not in ISO 4217 format or value) - AM02 -Instructed amount is not ≥ 0.01 & ≤ 2,000,000.00. - AC02 -Debtor account is invalid - CH03 -Value date is in the future - CH04 -Value date is in the past - CH20 -Value-added tax (VAT) amount format is invalid - CH21 -Bill identification 1 is mandatory for a bill payment,Bill identification 2 and 3 are conditional for a bill payment - BE23 -Creditor mobile number (proxy identification) format is invalid - NARR -Creditor name maximum length is 50 ) - refer to validation_code_description excel file for complete list of response codes and descriptions - `non_iso_code` (string, optional) — Reason local Clearing codes (e.g.0000,0080,0081,0082,0083,0084,1100 and etc.).Additional status code received from the local clearing which does not follow ISO standards but will on some occasions provide additional insights. Codes will vary by country (where applicable) and will be published on our developer portal - For UK it is an optional field with max length 4 - For SEPA IDP it is an optional field - For US, this field is optional - For SEPA, it is an optional field ### Debtor-Refund - `name` (string, optional) — Name of Debtor to be passed for Refund payment - For United States debtor.name field is mandatory for decision code IPAY and PECR - For Thailand debtor.name field is not applicable - For Brazil debtor.name field is not applicable - For SEPA debtor.name field is not applicable - `street_name` (string, optional) — Street Name of Debtor to be passed for Refund payment - For United States debtor.street_name field is optional - For Thailand debtor.street_name field is not applicable - For Brazil debtor.street_name field is not applicable - For SEPA debtor.street_name field is not applicable - `building_number` (string, optional) — Building number of Debtor to be passed for Refund payment - For United States debtor.building_number field is optional - For Thailand debtor.building_number field is not applicable - For Brazil debtor.building_number field is not applicable - For SEPA debtor.building_number field is not applicable - `postal_code` (string, optional) — Postal code of Debtor to be passed for Refund payment - For United States debtor.postal_code field is optional - For Thailand debtor.postal_code field is not applicable - For Brazil debtor.postal_code field is not applicable - For SEPA debtor.postal_code field is not applicable - `city` (string, optional) — City of Debtor to be passed for Refund payment - For United States debtor.city field is optional - For Thailand debtor.city field is not applicable - For Brazil debtor.city field is not applicable - For SEPA debtor.city field is not applicable - `state` (string, optional) — State of Debtor to be passed for Refund payment - For United States debtor.state field is optional - For Thailand debtor.state field is not applicable - For Brazil debtor.state field is not applicable - For SEPA debtor.state field is not applicable - `country` (string, optional) — Country of Debtor to be passed for Refund payment - For United States debtor.country field is optional - For Thailand debtor.country field is not applicable - For Brazil debtor.country field is not applicable - For SEPA debtor.country field is not applicable - `address_lines` (list of string, optional) — Debtor Address lines which is array of 7 lines and each line has maximum 70 characters which is to be passed for Refund payment - For United States debtor.address_lines field is optional - For Thailand debtor.address_lines field is not applicable - For Brazil debtor.address_lines field is not applicable - For SEPA debtor.address_lines field is not applicable ### Ultimate-Debtor-Refund - `name` (string, optional) — Name of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.name field is optional - For Thailand ultimatedebtor.name field is not applicable - For Brazil ultimatedebtor.name field is not applicable - For SEPA ultimate_debtor.name field is not applicable - `street_name` (string, optional) — Street Name of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.street_name field is optional - For Thailand ultimatedebtor.street_name field is not applicable - For Brazil ultimatedebtor.street_name field is not applicable - For SEPA ultimate_debtor.street_name field is not applicable - `building_number` (string, optional) — Building number of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.building_number field is optional - For Thailand ultimatedebtor.building_number field is not applicable - For Brazil ultimatedebtor.building_number field is not applicable - For SEPA ultimate_debtor.building_number field is not applicable - `postal_code` (string, optional) — Postal code of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.postal_code field is optional - For Thailand ultimatedebtor.postal_code field is not applicable - For Brazil ultimatedebtor.postal_code field is not applicable - For SEPA ultimate_debtor.postal_code field is not applicable - `city` (string, optional) — City of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.city field is optional - For Thailand ultimatedebtor.city field is not applicable - For Brazil ultimatedebtor.city field is not applicable - For SEPA ultimate_debtor.city field is not applicable - `state` (string, optional) — State of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.state field is optional - For Thailand ultimatedebtor.state field is not applicable - For Brazil ultimatedebtor.state field is not applicable - For SEPA ultimate_debtor.state field is not applicable - `country` (string, optional) — Country of Ultimate Debtor to be passed for Refund payment - For United States ultimate_debtor.country field is optional - For Thailand ultimatedebtor.country field is not applicable - For Brazil ultimatedebtor.country field is not applicable - For SEPA ultimate_debtor.country field is not applicable - `address_lines` (list of string, optional) — Ultimate Debtor Address lines which is array of 7 lines and each line has maximum 70 characters which is to be passed for Refund payment - For United States ultimate_debtor.address_lines field is optional - For Thailand ultimatedebtor.address_lines field is not applicable - For Brazil ultimatedebtor.address_lines field is not applicable - For SEPA ultimate_debtor.address_lines field is not applicable ### Error-Detail - `issue` (string, optional) — more details about the issue - `action` (string, optional) — corrective action to be taken to resolve above issue - `code` (string, optional) — unique code representing the issue ## Examples ### Refund Status - Completed **Response** ```json { "end_to_end_id": "r/434SKtUcdGQ", "instructed_amount": 29876.98, "instructed_currency": "THB", "original_payment": { "end_to_end_id": "r/434SKtUcdGQ", "uetr": "4f09214d-296c-494b-8e9c-810bf1d9fc93", "value_date": "2022-09-13", "instructed_amount": 29876.98, "instructed_currency": "THB" }, "refund_id": "4f09214d-296c-494b-8e9c-810bf1d9fc93", "creation_date_time": "2022-09-13T08:23:49.112Z", "value_date": "2022-09-13", "status": { "date_time": "2022-09-13T08:23:49.112Z", "code": "ACCC", "description": "Completed", "type": "F" } } ``` **SDK Code** ```python Refund Status - Completed import requests url = "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a" querystring = {"client_id":"6d3cf821-db6d-496d-bec0-064a362e9c31"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Refund Status - Completed const url = 'https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Refund Status - Completed package main import ( "fmt" "net/http" "io" ) func main() { url := "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Refund Status - Completed require 'uri' require 'net/http' url = URI("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Refund Status - Completed import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31") .header("Authorization", "Bearer ") .asString(); ``` ```php Refund Status - Completed request('GET', 'https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Refund Status - Completed using RestSharp; var client = new RestClient("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Refund Status - Completed import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Refund Status - Rejected **Response** ```json { "end_to_end_id": "r/434SKtUcdGQ", "instructed_amount": 29900.98, "instructed_currency": "THB", "original_payment": { "end_to_end_id": "r/434SKtUcdGQ", "uetr": "4f09214d-296c-494b-8e9c-810bf1d9fc93", "value_date": "2022-09-13", "instructed_amount": 29876.98, "instructed_currency": "THB" }, "refund_id": "4f09214d-296c-494b-8e9c-810bf1d9fc93", "creation_date_time": "2022-09-13T08:23:49.112Z", "value_date": "2022-09-13", "status": { "date_time": "2022-09-13T08:23:49.112Z", "code": "RJCT", "description": "Rejected", "type": "P" }, "reasons": [ { "code": "AM02", "description": "Transaction instructed refund amount is > total payment amount" } ] } ``` **SDK Code** ```python Refund Status - Rejected import requests url = "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a" querystring = {"client_id":"6d3cf821-db6d-496d-bec0-064a362e9c31"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Refund Status - Rejected const url = 'https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Refund Status - Rejected package main import ( "fmt" "net/http" "io" ) func main() { url := "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Refund Status - Rejected require 'uri' require 'net/http' url = URI("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Refund Status - Rejected import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31") .header("Authorization", "Bearer ") .asString(); ``` ```php Refund Status - Rejected request('GET', 'https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Refund Status - Rejected using RestSharp; var client = new RestClient("https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Refund Status - Rejected import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://b2b.api.icg.citi.com/citiconnect/prod/paymentservices/v1/refunds/0c4fb98b-d77a-4468-96bb-0c88b3b8f75a?client_id=6d3cf821-db6d-496d-bec0-064a362e9c31")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```