# Cancel payment API

### C**ancels a payment in full or partially regardless of the payment method and PG.**

## Cancels an approved payment.

<mark style="color:green;">`POST`</mark> `https://api.iamport.kr/payments/cancel`

Credit card/instant account transfer/mobile micropayment: cancellation is processed immediately.&#x20;

Virtual account: if you provide the refund account information, the refund information will be registered with PG and processed on the next business day. **(Requires virtual account special service contract)**

#### Request Body

| Name                                       | Type        | Description                                                                                                                             |
| ------------------------------------------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| imp\_uid<mark style="color:red;">\*</mark> | String(32)  | <mark style="color:red;">**ChaiPort transaction ID**</mark>                                                                             |
| reason                                     | String(256) | **Reason for cancellation**                                                                                                             |
| checksum                                   | Double      | Refundable amount                                                                                                                       |
| amount                                     | Double      | Amount to refund (**Full refund if null**)                                                                                              |
| merchant\_uid                              | String(40)  | **Order ID (Required if imp\_uid is null)**                                                                                             |
| tax\_free                                  | Double      | Tax free amount out of `amount` (**0 if null**)                                                                                         |
| refund\_bank                               | String(4)   | Refund account bank code (Refer to bank codes list below, required for **virtual account**  cancellation)                               |
| refund\_holder                             | String(16)  | **Refund account holder** (Required for **virtual account** cancellation)                                                               |
| refund\_account                            | String(16)  | Refund account number (Required for **virtual account** cancellation)                                                                   |
| refund\_tel                                | String(16)  | Refund account holder's phone number (Required for **virtual account** cancellation and <mark style="color:red;">**Smartro PG**</mark>) |

{% tabs %}
{% tab title="401: Unauthorized Missing or invalid access token" %}

{% endtab %}

{% tab title="200: OK Cancellation successful" %}
{% tabs %}
{% tab title="PaymentResponse" %}
**`code`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:purple;">**integer**</mark>

**Response code**

0: success, \
Not 0: check the message

**`message`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Response message**

A non-zero code includes a message like 'Invalid payment info.

**`response`** <mark style="color:red;">**(PagedPaymentAnnotation, optional)**</mark>
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PaymentAnnotation" %}
**`imp_uid`** <mark style="color:red;">\*</mark> <mark style="color:green;">**string(32)**</mark>

**i'mport payment transaction UID**

**`merchant_uid`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(40)**</mark>

**Order ID**

**`pay_method`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(20)**</mark>

**Payment method code**

**`channel`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(10)**</mark>

**Payment environment code**

&#x20;\['pc', 'mobile', 'api']

**`pg_provider`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(16)**</mark>

**PG code**

***

**`emb_pg_provider`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(16)**</mark>

**Hub-type PG code**

**`pg_tid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string(80)**</mark>

**PG transaction ID**

**`pg_id`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(80)**</mark>

**PG MID**

**`escrow`**   <mark style="color:orange;">**boolean**</mark>

**Indicates an escrow payment**

**`apply_num`**   <mark style="color:green;">**string(20)**</mark>

**Credit card approval number**

**`bank_code`**   <mark style="color:green;">**string(4)**</mark>

**Bank code**

**`bank_name`**   <mark style="color:green;">**string(20)**</mark>

**Bank name**

***

**`card_code`**   <mark style="color:green;">**string(3)**</mark>

**Credit card code (KFTC Credit Card Codes:** [<mark style="color:red;">**link**</mark>](https://chaifinance.notion.site/53589280bbc94fab938d93257d452216?v=eb405baf52134b3f90d438e3bf763630) )

**`card_name`**  <mark style="color:green;">**string(20)**</mark>

**Credit card name**

**`card_quota`**  <mark style="color:purple;">**integer**</mark>

**Number of installments (0 means one-off)**

**`card_number`** <mark style="color:green;">**string(20)**</mark>

**Masked credit card number**

***

**`card_type`**  <mark style="color:green;">**string(2)**</mark>

**Card type code**

**`vbank_code`**  <mark style="color:green;">**string(4)**</mark>

**Virtual account bank code (refer to image below)**

***

**`vbank_name`**  <mark style="color:green;">**string(20)**</mark>

**Refund virtual account**

**`vbank_holder`**  <mark style="color:green;">**string(16)**</mark>

**Refund virtual account holder**

**`vbank_date`**  <mark style="color:green;">**string**</mark>

**Refund virtual account expiration (UNIX timestamp)**

**`vbank_issued_at`**  <mark style="color:green;">**string**</mark>

**Refund virtual account created at (UNIX timestamp)**

**`name`**  <mark style="color:green;">**string(40)**</mark>

**Product name**

**`amount`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**Order (payment) amount**

**`cancel_amount`**  <mark style="color:purple;">**integer**</mark>

**Cancelled amount**

**`currency`**  <mark style="color:green;">**string(3)**</mark>

**Currency**

***

**`buyer_name`**  <mark style="color:green;">**string(16)**</mark>

**Customer name**

**`buyer_email`**  <mark style="color:green;">**string(64)**</mark>

**Customer  email**<br>

**`buyer_tel`**  <mark style="color:green;">**string(16)**</mark>

**Customer phone**

**`buyer_addr`**  <mark style="color:green;">**string(128)**</mark>

**Customer address**

**`buyer_postcode`**  <mark style="color:green;">**string(8)**</mark>

**Customer zip code**

**`custom_data`**  <mark style="color:green;">**string**</mark>

**echo data as JSON string**

**`user_agent`**  <mark style="color:green;">**string(256)**</mark>

**UserAgent of the device where payment is initiated**

**`status`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(20)**</mark>

**Payment status code**

**`started_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**Payment started at (UNIX timestamp)**

**`paid_at`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Payment completed at (UNIX timestamp)**<br>

**`failed_at`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Payment failed at (UNIX timestamp)**

**`cancelled_at`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Payment cancelled at (UNIX timestamp)**

**`fail_reason`** <mark style="color:green;">**string(256)**</mark>

**Reason for failure**

**`cancel_reason`**  <mark style="color:green;">**string(256)**</mark>

**Reason for cancellation**

**`receipt_url`**  <mark style="color:green;">**string(300)**</mark>

**Credit card receipt URL**

**`cash_receipt_issued` &#x20;**<mark style="color:orange;">**boolean**</mark>

**Option to automatically issue cash receipt**

**`customer_uid`**  <mark style="color:green;">**string(80)**</mark>

**customer\_uid related to the payment transaction**

**`customer_uid_usage`**  <mark style="color:green;">**string**</mark><mark style="color:green;">**(20)**</mark>

**customer\_uid use code**

\['issue', 'payment', 'payment.scheduled']

**`cancel_history`**  <mark style="color:red;">**(Array\[PaymentCancelAnnotation], optional):**</mark>

**`Cancellation/partial cancellation history`**
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PaymentCancelAnnotation" %}
**cancel\_history array \[]**

**`pg_tid`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**PG cancellation transaction ID**

**`amount`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**Cancelled amount**

**`cancelled_at`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

Cancelled at (UNIX timestamp)

**`reason`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string(256)**</mark>

**Reason for cancellation**

**`receipt_url`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string(300)**</mark>

**Cancellation receipt URL. Availability varies by PG.**
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### **Key parameters**

> **`imp_uid`  & `merchant_uid`**
>
> **At least one of these parameters must be specified.**

> **`checksum`**  <mark style="color:purple;">**integer**</mark>
>
> **Refundable amount**
>
> The `checksum` is used to check whether the refundable amount is the same between the API requester and the i'mport server. If they do not match, the refund request will fail. If the `checksum` is null, the verification is not performed.<br>

> **`amount`**  <mark style="color:red;">**\***</mark>**&#x20;&#x20;**<mark style="color:purple;">**integer**</mark>
>
> **Amount to cancel**
>
> If not specified, a full refund is requested.

<details>

<summary>Response Model Schema</summary>

```json
{
  "code": 0,
  "message": "string",
  "response": {
    "imp_uid": "string",
    "merchant_uid": "string",
    "pay_method": "string",
    "channel": "pc",
    "pg_provider": "string",
    "emb_pg_provider": "string",
    "pg_tid": "string",
    "pg_id": "string",
    "escrow": true,
    "apply_num": "string",
    "bank_code": "string",
    "bank_name": "string",
    "card_code": "string",
    "card_name": "string",
    "card_quota": 0,
    "card_number": "string",
    "card_type": "null",
    "vbank_code": "string",
    "vbank_name": "string",
    "vbank_num": "string",
    "vbank_holder": "string",
    "vbank_date": 0,
    "vbank_issued_at": 0,
    "name": "string",
    "amount": 0,
    "cancel_amount": 0,
    "currency": "string",
    "buyer_name": "string",
    "buyer_email": "string",
    "buyer_tel": "string",
    "buyer_addr": "string",
    "buyer_postcode": "string",
    "custom_data": "string",
    "user_agent": "string",
    "status": "ready",
    "started_at": 0,
    "paid_at": 0,
    "failed_at": 0,
    "cancelled_at": 0,
    "fail_reason": "string",
    "cancel_reason": "string",
    "receipt_url": "string",
    "cancel_history": [
      {
        "pg_tid": "string",
        "amount": 0,
        "cancelled_at": 0,
        "reason": "string",
        "receipt_url": "string"
      }
    ],
    "cancel_receipt_urls": [
      "string"
    ],
    "cash_receipt_issued": true,
    "customer_uid": "string",
    "customer_uid_usage": "issue"
  }
}
```

</details>

{% hint style="success" %}
**Swagger Test Link**

[**https://api.iamport.kr/#!/payments/cancelPayment**](https://api.iamport.kr/#!/payments/cancelPayment)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://portone.gitbook.io/docs-en/api/payment-api/cancel-payment-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.