# Cancel Payment API
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/cancel-payment-api/index.md

Alert: If you are a Customer contracted with MTS EU or MTS UK, please proceed to [Cancel Payment API Specifications for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-cancel-payment-api/index.md) and [Cancel Payment API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-cancel-payment-api/index.md) respectively to ensure compliance with the relevant jurisdiction based Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Services Directive (PSD2).

## Environment Domains {#environment-domains}

* Sandbox/MTF
* Production

```Sandbox/MTF
https://sandbox.api.mastercard.com/send/v1/partners/{partner-id}/crossborder/{payment-id}/cancel
```

```Production
https://api.mastercard.com/send/v1/partners/{partner-id}/crossborder/{payment-id}/cancel
```

Note: **Sandbox** and **MTF** environments share the same url but are differentiated by partner id.

You can use this API to cancel a request for a transaction that is in PENDING status.
Any payment with a payment status as "Pending" and Pending Stage as "Insufficient Balance" can be cancelled.
Additionally, for cash-out and some mobile money providers, the payment with status "Pending" can be cancelled irrespective of the Pending stage of that payment.

## API {#api}

[Open Specification](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-swagger.yaml)

Alternatively, here is a tabular view of the request/ response parameter:
[Cancel_Payment_Specifications.pdf](https://static.developer.mastercard.com/content/cross-border-services/uploads/Cancel_Payment_Specifications.pdf) (349KB)   


API Reference: `GET /send/v1/partners/{partner-id}/crossborder/{payment-id}/cancel`

* **Formats supported** : XML/ JSON   
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :   
  content-type : Format of the inbound content being submitted. example: application/json   
  content-length: Length of the inbound content body in octets.   
  Accept: Format of the expected response must be provided in this header field. Example - application/json

## API Convention {#api-convention}

Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.

## Payload Encryption {#payload-encryption}

All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by  
Mastercard.   

For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md)

## Sandbox Testing {#sandbox-testing}

You can make API calls to the Sandbox server from an API tool, your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required Authorization Header.
Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID.  
Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID.   
For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to a specific Customer; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, Customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Customer.

### Sandbox Test cases {#sandbox-test-cases}

The Sandbox server returns simulated, static responses. You can use the following test cases to produce specific responses.

| Status  |                                 Test Case                                  |                                              Action                                               |
|---------|----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Success | Cancel Payment Response is "Success" indicating the Request was delivered. | Send a Cancel Payment populating the transaction reference ID or payment ID of a pending payment. |

**Note** : For test scenarios to make a Payment API call, please look at the **Sandbox Test cases** section [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/payment-api/index.md).
A payment can be cancelled only if the payment transaction is in **pending** status.

## Sample Requests {#sample-requests}

* XML
* JSON

```XML
<?xml version="1.0" encoding="utf-8" ?>
<cancelpaymentrequest>  
</cancelpaymentrequest>
```

```JSON
{
   "cancelpaymentrequest": ""
}
```

## Sample Responses {#sample-responses}

* XML
* JSON

```XML
<?xml version="1.0" encoding="utf-8" ?>
<cancelpayment>
        <status>SUCCESS</status>  
</cancelpayment>
```

```JSON
{
   "cancelpayment": {
      "status": "SUCCESS"
   }
}
```

## Error Codes {#error-codes}

Please refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md).

For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).