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.
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
Order ID
Amount
Bank code
UNIX TIMESTAMP
Account holder
Order name
Customer name
Customer email
Customer phone
Customer address
Customer zip code
PG code
Notification URL
Custom data
Query
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
pg
* stringpg 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
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"
}
}
Swagger Test Link