Developers
V1
V2

Request virtual account API

Requests a virtual account for payment collection from the customer.

Supported PGs

  • Settlebank
  • NICE Payments
  • KG INCIS
POST https://api.iamport.kr/vbanks

Requests a virtual account for payment collection from the customer.

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

Parameters

Body

merchant_uid*
String(40)

Order ID

amount*
Double

Amount

vbank_code*
String

Bank code

vbank_due*
Integer
Account expiration

UNIX TIMESTAMP

vbank_holder*
String(16)

Account holder

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

Query

pg_api_key
String

API Key

(Required for KG INICIS Only)

Responses

200: OK
Success

code *** **integer

Response code

0: success, Not 0: check the message

message *** ****string**

Response message

A non-zero code includes a message like โ€˜Invalid payment infoโ€™.

response (PaymentAnnotation, optional)

code *** **integer

Response code

0: success, Not 0: check the message

message *** ****string**

Response message

A non-zero code includes a message like โ€˜Invalid payment info.

imp_uid * string

iโ€™mport payment transaction UID

merchant_uid *** ****string**

Order ID

pay_method *** ****string**

Payment method code

channel *** ****string**

Payment environment code

  • pc**:** (authenticated) PC
  • mobile: (authenticated) mobile
  • api: recurring or non-authenticated

pg_provider *** ****string**

PG code


emb_pg_provider *** ****string**

Hub-type PG code

pg_tid * string

PG transaction ID

pg_id *** ****string**

PG MID

escrow boolean

Indicates an escrow payment

apply_num string

Credit card approval number

bank_code string

Bank code

bank_name string

Bank name


card_code string

Credit card code (KFTC Credit Card Codes: link )

card_name string

Credit card name

card_quota integer

Number of installments (0 means one-off)

card_number string

Masked credit card number


card_type string

Credit card type code

  • 0: credit
  • 1: check

vbank_code string

Virtual account bank code (refer to image below)


vbank_name string

Refund virtual account

vbank_holder string

Refund virtual account holder

vbank_date string

Refund virtual account expiration (UNIX timestamp)

vbank_issued_at string

Refund virtual account created at (UNIX timestamp)

name string

Product name

amount * integer

Order (payment) amount

cancel_amount integer

Cancelled amount

currency string

Currency

  • USD
  • KRW
  • EUR

buyer_name string

Customer name

buyer_email string

Customer email\

buyer_tel string

Customer phone

buyer_addr string

Customer address

buyer_postcode string

Customer zip code

custom_data string

echo data as JSON string

user_agent string

UserAgent of the device where payment is initiated

status *** ****string**

Payment status code

  • ready
  • paid
  • cancelled
  • failed

started_at * string

Payment started at (UNIX timestamp)

paid_at *** ****string**

Payment completed at (UNIX timestamp)\

failed_at *** ****string**

Payment failed at (UNIX timestamp)

cancelled_at *** ****string**

Payment cancelled at (UNIX timestamp)

fail_reason string

Reason for failure

cancel_reason string

Reason for cancellation

receipt_url string

Credit card receipt URL

**cash_receipt_issued **boolean

Option to automatically issue cash receipt

customer_uid string

customer_uid related to the payment transaction

customer_uid_usage string

customer_uid use code

  • payment.scheduled: scheduled payment
  • payment: payment
  • issue**: billing key issuance**

cancel_history (Array[PaymentCancelAnnotation], optional):

Cancellation/partial cancellation history

pg_tid *** **string

PG cancellation transaction ID

amount * integer

Cancelled amount

cancelled_at * string

Cancelled at (UNIX timestamp)

reason * string(256)

Reason for cancellation

receipt_url *** ****string(300)**

Cancellation receipt URL. Availability varies by PG.

401: Unauthorized
Missing or invalid access token
{
    // Response
}

Key request parameter description

vbank_code * String

Bank code

Bank codes by PG

pg * string

pg code

This is required when there are multiple API method, non-authenticated PG settings in the Admin console.

If there are multiple MID settings for the same PG, specify as:

{PG}.{PG Merchant ID}

If this is unspecified or set to an invalid value, the default PG is used.

  • 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 String

Deposit notification URL

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 json

Custom data

If set with an object, this is saved as JSON string.

pg_api_key String

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)

Response Model Schema

{
  "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"
  }
}