Skip to navigation
Payments

Payment Cancellation

View as Markdown

This API specification document provides descriptions of the request and response parameters for JSON content.

The FI cancellation API lets you stop or recall payment requests against FI payments in payment insight. It supports custom JSON & ISO XML (camt.056.001.09) format. Initiating an FI Cancellation API using the CitiConnect API requires a well-defined POST request where you can specify the endpoint URL to call the API. Additionally, you need to specify the values for input parameters in the body of your JSON/XML document. Finally, you will encrypt the payload, place it in your request and send it via your application.

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

AuthorizationstringRequired
The OAuth Token prefixed with "Bearer" and space in between.
request_typestringRequired

Operation name. The possible value for this header is STOP_REQUEST.

Query parameters

client_idstringRequired

This is your unique identifier shared during your CitiConnect API onboarding. This is the same client_id used for OAuth token generation

Request

Describes the request body.
reasonstringRequired<=4 characters

This is the four digits cancellation code (Example - DUPL) which is specified by the customer to request to cancel the transaction.

uetrstringOptionalformat: "uuid"1-32 characters

Unique End-to-end Transaction Reference (UETR) relating to a payment has been identified as being associated with a Request for Cancellation. It should follow UUID version 4 format. UETR or citi_reference with interbank_settlement_date or end_to_end_id / instruction_id with interbank_settlement_date is mandatory.

citi_referencestringOptional<=32 characters

This parameter specifies the product processor reference number for the transaction that needs to be cancelled or recalled. UETR or citi_reference with interbank_settlement_date or end_to_end_id / instruction_id with interbank_settlement_date is mandatory.

end_to_end_idstringOptional<=16 characters

This is a unique end-to-end reference number that identifies a transaction that needs to be cancelled. UETR or citi_reference with interbank_settlement_date or end_to_end_id / instruction_id with interbank_settlement_date is mandatory.

instruction_idstringOptional<=16 characters

This is a unique end-to-end instruction id that identifies a transaction that needs to be cancelled. UETR or citi_reference with interbank_settlement_date or end_to_end_id / instruction_id with interbank_settlement_date is mandatory.

interbank_settlement_datedateOptional

This parameter specifies the value date (yyyy-MM-dd) of the original transaction that needs to be cancelled or recalled (the date on which funds were credited to the account).

reason_descriptionstringOptional<=150 characters
Further details on the request reason. Required for CUST and MS03 reason codes applicable to Stop services.

Response

OK > Success response

transaction_statusobjectOptional

Errors

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