> 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/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/_mcp/server.

# Payment Cancellation

POST https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops
Content-Type: application/json

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.

Reference: https://citi-demo.ferndocs.com/enterprises/api-reference/payment-services/payments/fi-payment-services/fi-cancellation-api

## 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://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3` (production gateway URL, default)
- `https://tts.apib2b.citi.com/citiconnect/sb/paymentservices/v3` (sandbox URL)

## Request

### Query parameters

- `client_id` (string, required) — This is your unique identifier shared during your CitiConnect API onboarding. This is the same `client_id` used for OAuth token generation

### Headers

- `Authorization` (string, required) — The OAuth Token prefixed with "Bearer" and space in between.
- `request_type` (string, required) — Operation name. The possible value for this header is STOP_REQUEST.

### Body (application/json)

This endpoint expects a fi_cancellation_request.

- `reason` (string, required) — This is the four digits cancellation code (Example - DUPL) which is specified by the customer to request to cancel the transaction.
- `uetr` (string, optional) — 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_reference` (string, optional) — 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_id` (string, optional) — 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_id` (string, optional) — 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_date` (date, optional) — 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_description` (string, optional) — Further details on the request reason. Required for CUST and MS03 reason codes applicable to Stop services.

## Response

### 200

OK > Success response

- `transaction_status` (transaction_status_detail, optional)

## Errors

### 400 Bad Request Error

BAD REQUEST

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

### 401 Unauthorized Error

UNAUTHORIZED

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

### 404 Not Found Error

NOT FOUND

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

### 405 Method Not Allowed Error

METHOD NOT ALLOWED

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

### 415 Unsupported Media Type Error

FORBIDDEN

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

### 500 Internal Server Error

INTERNAL SERVER ERROR

- `status` (string, optional) — This parameter indicates the status of the reconfirm/reject or cancel/recall request with set of values. for example- FAILED.
- `http_code` (integer, optional) — Indicates http status code to specify http response. status
- `errors` (list of ErrorDetail, optional) — Indicates actual error details with issues and corresponding actions to resolve the issue.

## Types

### transaction_status_detail

- `status` (string, optional) — This parameter indicates the status of the cancel/recall request with set of values. for example - ACCP for Accepted or RJCT for Rejected.
- `type` (string, optional) — This parameter provides additional information of the transaction when it is rejected/accepted.

### ErrorDetail

- `issue` (string, optional) — More details about the issue.
- `action` (string, optional) — Corrective action to be taken to resolve above issue.

## Examples

**Request**

```json
{
  "reason": "string"
}
```

**Response**

```json
{
  "transaction_status": {
    "status": "ACCP",
    "type": "Your request has been registered. We will notify you once the transaction is stopped/recalled."
  }
}
```

**SDK Code**

```python response
import requests

url = "https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops"

querystring = {"client_id":"client_id"}

payload = { "reason": "string" }
headers = {
    "Authorization": "Bearer <token>",
    "request_type": "request_type",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, params=querystring)

print(response.json())
```

```javascript response
const url = 'https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id';
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <token>',
    request_type: 'request_type',
    'Content-Type': 'application/json'
  },
  body: '{"reason":"string"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go response
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id"

	payload := strings.NewReader("{\n  \"reason\": \"string\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("request_type", "request_type")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby response
require 'uri'
require 'net/http'

url = URI("https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["request_type"] = 'request_type'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"reason\": \"string\"\n}"

response = http.request(request)
puts response.read_body
```

```java response
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id")
  .header("Authorization", "Bearer <token>")
  .header("request_type", "request_type")
  .header("Content-Type", "application/json")
  .body("{\n  \"reason\": \"string\"\n}")
  .asString();
```

```php response
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id', [
  'body' => '{
  "reason": "string"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'request_type' => 'request_type',
  ],
]);

echo $response->getBody();
```

```csharp response
using RestSharp;

var client = new RestClient("https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("request_type", "request_type");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"reason\": \"string\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift response
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "request_type": "request_type",
  "Content-Type": "application/json"
]
let parameters = ["reason": "string"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://tts.apib2b.citi.com/citiconnect/prod/paymentservices/v3/payments/stops?client_id=client_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```