가상계좌 발급 API

가상계좌번호를 발급하여 고객이 입금할수 있도록 합니다.

Previous가상계좌 관련 API Next가상계좌 발급취소 API

Last updated 2 years ago

Was this helpful?

가상계좌 발급 API

가상계좌번호를 발급하여 고객이 입금할수 있도록 합니다.

Deprecated

이 문서는 더 이상 관리되지 않습니다.

를 이용해주세요.

가상계좌번호를 발급할수 있습니다.

해당 API 는 아래 PG사를 이용하는 경우에만 사용 가능합니다.

핵토파이낸셜(구 세틀뱅크)
나이스페이먼츠
KG이니시스
토스페이먼츠 - 신모듈
KSPAY

가상계좌 번호를 발급합니다.

POST https://api.iamport.kr/vbanks

희망하시는 은행, 예금주명으로 입금이 가능한 가상계좌를 생성할 수 있습니다.(별도로 PG계약 필요)

Query Parameters

Name

Type

Description

pg_api_key

String

API Key

(이니시스 전용)

Request Body

Name

Type

Description

merchant_uid*

String(40)

주문번호

amount*

Double

발급금액

vbank_code*

String

은행구분코드

vbank_due*

Integer

가상계좌 입금기한

**UNIX TIMESTAMP **

vbank_holder*

String(16)

가상계좌 예금주명

name

String(40)

주문명

buyer_name

String(16)

주문자명

buyer_email

String(64)

주문자 E-mail 주소

buyer_tel

String(16)

주문자 전화번호

buyer_addr

String(128)

주문자 주소

buyer_postcode

String(8)

주문자 우편번호

String

PG사 구분코드

notice_url

String

입금통보 URL

custom_data

Array

에코항목

vat_amount

integer

부가세(기본값: null)

나이스페이먼츠에서만 사용 가능

vbank_key

String

계좌 고유 키 고정식 가상계좌를 발급받기 위한 고객과 매칭시킨 계좌 고유 키

(토스페이먼츠 - 신모듈의 경우 필수값임)

(사용을 위해 PG사와 협의 필요)

code * integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message * string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

response (PaymentAnnotation, optional)

code * integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message * string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

imp_uid * string

포트원 결제 고유 UID

merchant_uid * string

주문번호

pay_method * string

결제수단 구분코드

channel * string

결제환경 구분코드

pc : (인증방식)PC결제
mobile:(인증방식)모바일결제
api:정기결제 또는 비인증 결제

pg_provider * string

PG사 구분코드

emb_pg_provider * string

허브형결제 PG사 구분코드

pg_tid * string

pg사 거래번호

pg_id * string

PG사 MID

escrow boolean

에스크로 결제여부

apply_num string

신용카드 승인번호

bank_code string

bank_name string

은행 명칭

card_code string

card_name string

카드사명

card_quota integer

할부개월 수(0이면 일시불)

card_number string

마스킹 카드번호

card_type string

카드 구분코드

0 : 신용카드
1 : 체크카드

vbank_code string

가상계좌 은행 표준코드(하단이미지 참고)

vbank_name string

입금받을 가상계좌 은행명

vbank_holder string

입금받을 가상계좌 예금주

vbank_date string

입금받을 가상계좌 마감기한 (UNIX timestamp)

vbank_issued_at string

가상계좌 생성 시각 (UNIX timestamp)

name string

제품명

amount * integer

주문(결제)금액

cancel_amount integer

결제취소금액

currency string

통화구분코드

buyer_name string

주문자명

buyer_email string

주문자 Email주소\

buyer_tel string

주문자 전화번호

buyer_addr string

주문자 주소

buyer_postcode string

주문자 우편번호

custom_data string

echo data

JSON string으로 전달

user_agent string

UserAgent

결제를 시작한 단말기 정

status * string

결제상태 구분코드

ready
paid
cancelled
failed

started_at * string

결제시작시점 (UNIX timestamp)

paid_at * string

결제완료시점 (UNIX timestamp)\

failed_at * string

결제실패시점 (UNIX timestamp)

cancelled_at * string

결제취소시점 (UNIX timestamp)

fail_reason string

결제실패 사유

cancel_reason string

결제취소 사유

receipt_url string

신용카드 매출전표 확인 URL

cash_receipt_issued boolean

현금영수증 자동발급 여부

customer_uid string

해당 결제처리에 사용된 customer_uid

customer_uid_usage string

customer_uid 사용 구분코드

issue : 빌링키 발급
payment : 결제
payment.scheduled : 예약결제

cancel_history (Array[PaymentCancelAnnotation], optional):

취소/부분취소 내역

cancel_history array []

pg_tid * string

PG사 승인취소번호

amount * integer

취소 금액

cancelled_at * string

결제취소된 시각 UNIX timestamp

reason * string

결제취소 사유

receipt_url * string

취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음

{
    // Response
}

주요 요청 파라미터 상세 설명

vbank_code * string
**은행구분코드 **

pg * string
pg 구분코드
관리자콘솔 API 방식 비인증 PG설정이 2개 이상인 경우 필수적으로 기재해야 하는 항목입니다.
동일 PG사에 두개의 MID 를 설정한 경우 아래 양식으로 기재 합니다.
{PG사}.{PG상점아이디}
나이스페이먼츠, JTNet 2가지 PG설정이 되어있다면, pg 파라미터로 nice 또는 jtnet로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능

notice_url string
**입금통보 URL **
가상계좌 입금시 입금통지받을 URL 선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용

custom_data json
에코항목
결제정보와 함께 저장할 custom_data. 객체로 전달되는 경우 JSON 문자열로 저장

pg_api_key string
API Key
이니시스의 가맹점 콘솔에서 확인하셔야 하는 API Key 값으로 가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다.
(이니시스 전용이며, 이니시스의 경우 필수값 Query parameter임)

vbank_keystring
고정식 가상계좌를 발급받기 위한 고객과 매칭시킨 계좌 고유 키
(토스페이먼츠 - 신모듈의 경우 필수값임) (사용을 위해 PG사와 협의 필요)

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

Previous가상계좌 관련 API Next가상계좌 발급취소 API

Last updated 2 years ago

Was this helpful?

Deprecated

이 문서는 더 이상 관리되지 않습니다.

를 이용해주세요.

가상계좌번호를 발급할수 있습니다.

해당 API 는 아래 PG사를 이용하는 경우에만 사용 가능합니다.

핵토파이낸셜(구 세틀뱅크)
나이스페이먼츠
KG이니시스
토스페이먼츠 - 신모듈
KSPAY

가상계좌 번호를 발급합니다.

POST https://api.iamport.kr/vbanks

희망하시는 은행, 예금주명으로 입금이 가능한 가상계좌를 생성할 수 있습니다.(별도로 PG계약 필요)

Query Parameters

Name

Type

Description

pg_api_key

String

API Key

(이니시스 전용)

Request Body

Name

Type

Description

merchant_uid*

String(40)

주문번호

amount*

Double

발급금액

vbank_code*

String

은행구분코드

vbank_due*

Integer

가상계좌 입금기한

**UNIX TIMESTAMP **

vbank_holder*

String(16)

가상계좌 예금주명

name

String(40)

주문명

buyer_name

String(16)

주문자명

buyer_email

String(64)

주문자 E-mail 주소

buyer_tel

String(16)

주문자 전화번호

buyer_addr

String(128)

주문자 주소

buyer_postcode

String(8)

주문자 우편번호

String

PG사 구분코드

notice_url

String

입금통보 URL

custom_data

Array

에코항목

vat_amount

integer

부가세(기본값: null)

나이스페이먼츠에서만 사용 가능

vbank_key

String

계좌 고유 키 고정식 가상계좌를 발급받기 위한 고객과 매칭시킨 계좌 고유 키

(토스페이먼츠 - 신모듈의 경우 필수값임)

(사용을 위해 PG사와 협의 필요)

code * integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message * string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

response (PaymentAnnotation, optional)

code * integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message * string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

imp_uid * string

포트원 결제 고유 UID

merchant_uid * string

주문번호

pay_method * string

결제수단 구분코드

channel * string

결제환경 구분코드

pc : (인증방식)PC결제
mobile:(인증방식)모바일결제
api:정기결제 또는 비인증 결제

pg_provider * string

PG사 구분코드

emb_pg_provider * string

허브형결제 PG사 구분코드

pg_tid * string

pg사 거래번호

pg_id * string

PG사 MID

escrow boolean

에스크로 결제여부

apply_num string

신용카드 승인번호

bank_code string

은행 표준코드

bank_name string

은행 명칭

card_code string

카드사 코드번호(금융결제원 표준코드번호 : )

card_name string

카드사명

card_quota integer

할부개월 수(0이면 일시불)

card_number string

마스킹 카드번호

card_type string

카드 구분코드

0 : 신용카드
1 : 체크카드

vbank_code string

가상계좌 은행 표준코드(하단이미지 참고)

vbank_name string

입금받을 가상계좌 은행명

vbank_holder string

입금받을 가상계좌 예금주

vbank_date string

입금받을 가상계좌 마감기한 (UNIX timestamp)

vbank_issued_at string

가상계좌 생성 시각 (UNIX timestamp)

name string

제품명

amount * integer

주문(결제)금액

cancel_amount integer

결제취소금액

currency string

통화구분코드

buyer_name string

주문자명

buyer_email string

주문자 Email주소\

buyer_tel string

주문자 전화번호

buyer_addr string

주문자 주소

buyer_postcode string

주문자 우편번호

custom_data string

echo data

JSON string으로 전달

user_agent string

UserAgent

결제를 시작한 단말기 정

status * string

결제상태 구분코드

ready
paid
cancelled
failed

started_at * string

결제시작시점 (UNIX timestamp)

paid_at * string

결제완료시점 (UNIX timestamp)\

failed_at * string

결제실패시점 (UNIX timestamp)

cancelled_at * string

결제취소시점 (UNIX timestamp)

fail_reason string

결제실패 사유

cancel_reason string

결제취소 사유

receipt_url string

신용카드 매출전표 확인 URL

cash_receipt_issued boolean

현금영수증 자동발급 여부

customer_uid string

해당 결제처리에 사용된 customer_uid

customer_uid_usage string

customer_uid 사용 구분코드

issue : 빌링키 발급
payment : 결제
payment.scheduled : 예약결제

cancel_history (Array[PaymentCancelAnnotation], optional):

취소/부분취소 내역

cancel_history array []

pg_tid * string

PG사 승인취소번호

amount * integer

취소 금액

cancelled_at * string

결제취소된 시각 UNIX timestamp

reason * string

결제취소 사유

receipt_url * string

취소에 대한 매출전표 확인 URL. PG사에 따라 제공되지 않는 경우도 있음

{
    // Response
}

주요 요청 파라미터 상세 설명

vbank_code * string
**은행구분코드 **
참조

pg * string
pg 구분코드
관리자콘솔 API 방식 비인증 PG설정이 2개 이상인 경우 필수적으로 기재해야 하는 항목입니다.
동일 PG사에 두개의 MID 를 설정한 경우 아래 양식으로 기재 합니다.
{PG사}.{PG상점아이디}
나이스페이먼츠, JTNet 2가지 PG설정이 되어있다면, pg 파라미터로 nice 또는 jtnet로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능

notice_url string
**입금통보 URL **
가상계좌 입금시 입금통지받을 URL 선언되지 않으면 포트원 관리자 페이지에 정의된 Notification URL값을 사용

custom_data json
에코항목
결제정보와 함께 저장할 custom_data. 객체로 전달되는 경우 JSON 문자열로 저장

pg_api_key string
API Key
이니시스의 가맹점 콘솔에서 확인하셔야 하는 API Key 값으로 가상계좌 발급 및 말소 신청에 사용됩니다. 누락하거나 잘못된 키 입력 시 hashData 불일치 오류가 발생합니다.
(이니시스 전용이며, 이니시스의 경우 필수값 Query parameter임)

vbank_keystring
고정식 가상계좌를 발급받기 위한 고객과 매칭시킨 계좌 고유 키
(토스페이먼츠 - 신모듈의 경우 필수값임) (사용을 위해 PG사와 협의 필요)

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