> For the complete documentation index, see [llms.txt](https://docs.papayaglobal.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.papayaglobal.com/api-reference/payment-management/cancel-payment-instruction.md).

# Cancel Payment

Cancels an existing payment instruction. Only payments in PENDING or FAILED status can be cancelled.

<mark style="color:green;">**`POST`**</mark> /payments/payments/cancel

**Body parameters - Request**

<table data-full-width="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th><th>Required</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>The payment request ID to be cancelled</td><td> Yes</td></tr><tr><td>cancel_reason</td><td>string</td><td>A reason for the cancellation</td><td></td></tr></tbody></table>

**Body parameters -** **Response**

<table data-full-width="false"><thead><tr><th>Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Unique payment identifier</td></tr><tr><td>correlation_id</td><td>string</td><td>External tracking identifier</td></tr><tr><td>purpose</td><td>string</td><td>4-letter ISO-20022 payment purpose code</td></tr><tr><td>source.type / source.id</td><td>string</td><td>Entity type and ID that originated the payment</td></tr><tr><td>target.type / target.id</td><td>string</td><td>Entity type and ID of the payment recipient</td></tr><tr><td>info.status</td><td>boolean</td><td>Payment status</td></tr><tr><td>info.funding</td><td>object</td><td>Funding currency and amount</td></tr><tr><td>info.credit</td><td>object</td><td>Credited currency and amount</td></tr><tr><td>info.error</td><td>object</td><td>Error details if applicable</td></tr><tr><td>amount.type</td><td>string</td><td>LAND or SEND — whether amount represents credited or debited funds</td></tr><tr><td>amount.amount</td><td>number</td><td>Payment value</td></tr><tr><td>amount.currency</td><td>string</td><td>3-letter ISO currency code</td></tr><tr><td>execution.date</td><td>DateTime</td><td>Scheduled payment execution date</td></tr><tr><td>final.is_final</td><td>boolean</td><td>Indicates whether the amount is final</td></tr><tr><td>attachments</td><td>array</td><td>List of attached documents</td></tr><tr><td>approved</td><td>boolean</td><td>Whether the payment was approved prior to cancellation</td></tr><tr><td>user_tags</td><td>object</td><td>Custom key/value tags associated with the payment</td></tr></tbody></table>

**Request Example**

```json
POST /payments/payments
{
    "id": "b5f5433f-1ede-4623-9e3e-9282b13b7e8b",
    "cancel_reason": "Beneficiary has pending to update bank details."
}
```

**Response Examples**

{% tabs %}
{% tab title="200 - OK Success" %}

```json
{
    "id": "507013::e0132a41-aadc-4eb9-bb9a-3341e542333e::b5f5433f-1ede-4623-9e3e-9282b13b7e8b",
    "correlation_id": "b5f5433f-1ede-4623-9e3e-9282b13b7e8b",
    "purpose": "OTHR",
    "source": {
      "id": "92f8232f-8481-4631-a6d0-cb4a35cce294",
      "type": "group"
    },
    "target": {
      "type": "contact",
      "id": "e0132a41-aadc-4eb9-bb9a-3341e542333e"
    },
    "info": {
      "funding": {
        "currency": "INR",
        "amount": 9876.00000
      },
      "status": "CANCELLED",
      "error": {},
      "credit": {
        "currency": "GBP",
        "amount": 78.73002
      }
    },
    "amount": {
      "type": "LAND",
      "amount": 9876.00,
      "currency": "INR"
    },
    "execution": {
      "date": "2026-03-30T01:00:00Z"
    },
    "final": {
      "is_final": true
    },
    "attachments": [],
    "approved": true,
    "user_tags": {
      "Business": "B2B",
      "Country": "Poland"
    }
  }
```

{% endtab %}

{% tab title="400 - Bad Request" %}

```json
 {
    "error": "bad_request",
    "description": "Schema validation failed: Validation errors: {\"org_id\":\"265030\"}",
    "error_code": 400
  }
```

{% endtab %}

{% tab title="404 - Not Found" %}

```json
 {
    "error": "bad_request",
    "description": "Schema validation failed: Validation errors: {\"org_id\":\"265030\"}",
    "error_code": 400
  }
```

{% endtab %}

{% tab title=" 409 - Conflict" %}

```json
{
    "error": "Cancel Failed",
    "description": "Cancel Failed",
    "error_code": 409
  }
```

{% endtab %}
{% endtabs %}

&#x20;