# Cancel virtual account API

### Cancels a virtual account before payment is deposited.

<details>

<summary><strong>Supported PGs</strong></summary>

* **KG INCIS**
* **NHN KCP**
* **TOSS Payments**
* **Nice Payments**
* **KICC**
* **Settle Bank**
* **Smartro**

</details>

## Cancels a virtual account before payment is deposited.

<mark style="color:red;">`DELETE`</mark> `https://api.iamport.kr/vbanks/{imp_uid}`

You can cancel a virtual account before deposit to prevent the buyer from depositing by mistake. **imp\_uid** must be specified. (Since there can be multiple virtual accounts pending payment deposit for a single merchant\_uid, you can only cancel a virtual account based on the imp\_uid)

#### Path Parameters

| Name                                       | Type   | Description                                                |
| ------------------------------------------ | ------ | ---------------------------------------------------------- |
| imp\_uid<mark style="color:red;">\*</mark> | String | <mark style="color:red;">**i'mport transaction ID**</mark> |

#### Query Parameters

| Name         | Type   | Description                                                                          |
| ------------ | ------ | ------------------------------------------------------------------------------------ |
| pg\_api\_key | String | <p><strong>API Key</strong></p><p><strong>(Required for KG INICIS Only)</strong></p> |

{% tabs %}
{% tab title="200: OK Success" %}
{% 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;">**(PaymentAnnotation, optional)**</mark>
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="PaymentAnnotation" %}
**`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.

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

**i'mport payment transaction UID**

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

**Order ID**

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

**Payment method code**

&#x20;

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

**Payment environment code**

* p&#x63;**:** (authenticated) PC
* mobile: (authenticated) mobile
* api: recurring or non-authenticated

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

**PG code**

***

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

**Hub-type PG code**

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

**PG transaction ID**

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

**PG MID**

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

**Indicates an escrow payment**

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

**Credit card approval number**

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

**Bank code**

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

**Bank name**

***

**`card_code`**   <mark style="color:green;">**string**</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**</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**</mark>

**Masked credit card number**

***

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

**Credit card type code**

* 0: credit
* 1: check

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

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

***

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

**Refund virtual account**

**`vbank_holder`**  <mark style="color:green;">**string**</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**</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**</mark>

**Currency**

* USD
* KRW
* EUR

***

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

**Customer name**

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

**Customer  email**<br>

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

**Customer phone**

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

**Customer address**

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

**Customer zip code**

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

**echo data as JSON string**

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

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

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

**Payment status code**

* ready
* paid
* cancelled
* failed

**`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**</mark>

**Reason for failure**

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

**Reason for cancellation**

**`receipt_url`**  <mark style="color:green;">**string**</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**</mark>

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

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

**customer\_uid use code**

* payment.scheduled: scheduled payment
* payment: payment
* issu&#x65;**: billing key issuance**

**`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 %}

{% tab title="400: Bad Request Missing imp\_uid" %}

```javascript
{
    // Response
}
```

{% endtab %}

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

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="404: Not Found Invalid imp\_uid" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### Key request parameter description

> **`pg_api_key`` `**<mark style="color:green;">**`String`**</mark>
>
> **API Key**
>
> This is the API Key from the KG INICIS Merchant console and is used for virtual account issuance and cancellation. A hashData mismatch error occurs if you specify a missing or invalid key.
>
> (**Required for KG INICIS only**)

<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/#!/vbanks/revokeVbank**](https://api.iamport.kr/#!/vbanks/revokeVbank)
{% 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/virtual-account-api/cancel-virtual-account-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.