# Request virtual account API

### Requests a virtual account for payment collection from the customer.

Supported PGs

* Settlebank
* NICE Payments
* KG INCIS

## Requests a virtual account for payment collection from the customer.

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

You can create a virtual account for a desired bank and account holder name. (Requires a separate PG contract)

#### Query Parameters

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

#### Request Body

| Name                                            | Type        | Description                                                                                                       |
| ----------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| merchant\_uid<mark style="color:red;">\*</mark> | String(40)  | <mark style="color:red;">**Order ID**</mark>                                                                      |
| amount<mark style="color:red;">\*</mark>        | Double      | <mark style="color:red;">**Amount**</mark>                                                                        |
| vbank\_code<mark style="color:red;">\*</mark>   | String      | <mark style="color:red;">**Bank code**</mark>                                                                     |
| vbank\_due<mark style="color:red;">\*</mark>    | Integer     | <p><mark style="color:red;"><strong>Account expiration</strong></mark></p><p><strong>UNIX TIMESTAMP</strong> </p> |
| vbank\_holder<mark style="color:red;">\*</mark> | String(16)  | <mark style="color:red;">**Account holder**</mark>                                                                |
| name                                            | String(40)  | **Order name**                                                                                                    |
| buyer\_name                                     | String(16)  | **Customer name**                                                                                                 |
| buyer\_email                                    | String(64)  | **Customer email**                                                                                                |
| buyer\_tel                                      | String(16)  | **Customer phone**                                                                                                |
| buyer\_addr                                     | String(128) | **Customer address**                                                                                              |
| buyer\_postcode                                 | String(8)   | **Customer zip code**                                                                                             |
| pg                                              | String      | **PG code**                                                                                                       |
| notice\_url                                     | String      | **Notification URL**                                                                                              |
| custom\_data                                    | Array       | **Custom data**                                                                                                   |

{% 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" %}
**`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="401: Unauthorized Missing or invalid access token" %}

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

{% endtab %}
{% endtabs %}

### Key request parameter description

> **`vbank_code`**<mark style="color:red;">**`*`**</mark><mark style="color:green;">**`String`**</mark>
>
> **Bank code**&#x20;
>
> [**Bank codes by PG**](https://portone.gitbook.io/docs-en/tips/bank-codes-by-pg)

> **`pg`**  <mark style="color:red;">**\***</mark>  <mark style="color:green;">**string**</mark>
>
> **pg code**
>
> This is required when there are multiple API method, non-authenticated PG settings in the Admin console.&#x20;
>
> If there are <mark style="color:red;">**multiple MID**</mark> settings for the same PG, specify as:
>
> **{PG}.{PG Merchant ID}**&#x20;
>
> If this is unspecified or set to an invalid value, the default PG is used.&#x20;
>
> * If there are 2 PG settings, NICE Payments and JTNet, specify as **nice** or **jtnet**.
> * If you have multiple MIDs from NICE Payments, specify as **nice.MID1** or **nice.MID2**.

> **`notice_url`**<mark style="color:green;">**`String`**</mark>
>
> **Deposit notification URL**&#x20;
>
> When a payment is deposited into a virtual account, if this URL is not specified, the notification URL setting in the Admin console is used.

> **`custom_data`` `**<mark style="color:blue;">**`json`**</mark>
>
> **Custom data**&#x20;
>
> If set with an object, this is saved as JSON string.

> **`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/createVbank**](https://api.iamport.kr/#!/vbanks/createVbank)
{% endhint %}