결제 예약하기

빌링키로 결제를 예약해요. 예약 요청 시, 예약 성공 여부가 응답돼요. 이후 실제 결제는 예약된 시간에 자동으로 진행돼요. 결제 결과는 웹훅을 통해 전달돼요.

예약된 시간에 결제가 진행되고 결과가 웹훅으로 전달되므로, 각 결제가 어떤 예약에 대한 것인지 구분하기 위해 예약 요청에 대한 응답값은 데이터베이스에 저장해야 해요.

결제 예약 요청

Server

다음과 같이 빌링키로 결제를 예약할 수 있습니다.

POST

https://api.bootpay.co.kr/v2/subscribe/payment/reserve

요청 파라미터

pricenumber
최종 결제 금액입니다. 0보다 커야 합니다.
tax_freenumber
결제할 최종 금액 중 비과세 금액에 해당합니다. price 값과 같거나 작아야 합니다. 비과세 또는 복합과세 설정이 사전에 완료되어 있어야 합니다. 이 설정은 PG사에서 진행합니다. 복합과세 설정에 대해서는 PG사에 문의하시기 바랍니다.
billing_key필수string
부트페이에서 부여하는 빌링키로 고유한 값을 가집니다. 이 값은 데이터베이스에 반드시 저장되어야 합니다.
order_idstring
가맹점에서 관리하는 고유 주문번호 입니다.
order_namestring
상품명, 주문명 입니다.
metadatahash
결제 요청 시 해당 값을 보내면, 결제가 완료되거나 취소될 때 돌려받을 수 있습니다. orderId 만으로 주문을 구분하기 어려운 상황에서 처리하기 위한 필드입니다.
예시: { "callbackParam1" : "value12", "callbackParam2" : "value34", "callbackParam3" : "value56", "callbackParam4" : "value78"}
extrahash
Extra 모델을 통해 추가 데이터를 입력할 수 있습니다.
user페이앱은 구매자 전화번호 필수hash
구매자 정보를 입력합니다.
items페이코 필수array<hash>
상품 정보를 입력합니다.
card_quotastring
구매자가 선택한 카드 할부 개월 수입니다.
범위: 00, 02, 03, 04, 05, 06, 07, 08 등
card_interest일부 PG만 제공string
카드 무이자 할부 개월 수입니다.
예시: 00
reserve_execute_atdate
예약결제를 실행할 시간
* UTC 시간을 사용할 경우 ex) 2024-06-01 12:00:00 UTC (한국시간 기준 2024-06-01 21:00:00에 결제 진행)
* TIMEZONE을 사용할 경우 ex) 2024-06-01T21:00:00 +0900 (한국시간 기준 2024-06-01 21:00:00에 결제 진행)
feedback_urlstring
웹훅을 받을 주소를 입력할 수 있습니다. 값이 없을 경우 부트페이 관리자에 설정된 URL로 전송됩니다.
content_typestring
웹훅을 받을 데이터 타입을 입력할 수 있습니다. application/json 또는 application/x-www-form-urlencoded 를 선택하여 입력합니다. 값이 없을 경우 부트페이 관리자에 설정된 값으로 전송됩니다.

응답 결과

Server

예약이 성공하면 다음과 같은 응답을 받습니다.

응답 파라미터

reserve_idstring
부트페이가 발급한 예약 번호입니다.
reserve_execute_atdate
예약결제를 실행할 시간
* UTC 시간을 사용할 경우 ex) 2024-06-01 12:00:00 UTC (한국시간 기준 2024-06-01 21:00:00에 결제 진행)
* TIMEZONE을 사용할 경우 ex) 2024-06-01T21:00:00 +0900 (한국시간 기준 2024-06-01 21:00:00에 결제 진행)

결제 실행 결과

Server

결제 예약이 성공적으로 완료되면, 예약된 시간에 결제가 진행됩니다. 결제 결과는 웹훅을 통해 전달됩니다.

결제 예약 요청시feedback_url과content_type에 입력된 값으로 웹훅이 전송됩니다. 만약 빈 값을 보냈다면, 부트페이 관리자에 설정된 값으로 전송됩니다. 부트페이 관리자에 설정된 값도 없는 경우, 웹훅은 전달되지 않습니다.

웹훅 데이터 포맷은 결제 조회 응답 결과와 동일합니다.

웹훅 파라미터

receipt_idstring
부트페이에서 부여하는 영수증 ID로 고유한 값을 가집니다. 결제 요청 시 생성되며, confirm, done, error 이벤트 및 관리자 페이지의 결제내역에서 확인할 수 있습니다. 데이터베이스에 반드시 저장해야 합니다.
order_idstring
결제 요청 시 가맹점에서 보낸 주문 ID입니다. 중복 결제를 방지하기 위해 사용될 수 있습니다.
pricenumber
결제 요청 및 승인된 금액입니다.
tax_freenumber
비과세 요청 및 승인된 금액입니다. 전체 price 중 비과세 금액만 지정합니다.
cancelled_pricenumber
결제 취소된 금액입니다. 최초 결제 완료 시에는 0원으로 표시됩니다.
cancelled_tax_freenumber
비과세 취소된 금액입니다. 최초 결제 완료 시에는 0원으로 표시됩니다.
order_namestring
결제 요청 시 전달된 판매 상품명입니다.
company_namestring
부트페이에 등록된 가맹점명입니다.
gateway_urlstring
PG로 요청된 부트페이 URL입니다. 이 값은 부트페이 내부적으로 사용되며, PG사에 referer로 전달됩니다.
metadatahash
결제 요청 시 전달된 메타데이터입니다. 전송된 데이터는 그대로 반환됩니다.
sandboxboolean
true는 테스트 결제 모드, false는 실제 결제 모드입니다.
pgstring
결제가 완료된 PG사의 이름입니다.
methodstring
결제에 사용된 결제 수단의 이름입니다.
method_symbolstring
결제 수단의 영문 심볼입니다.
method_originstring
결제 완료 시 원본 결제 수단명입니다.
ex) 카드자동결제는 method_origin이 카드자동, method가 카드로 표시됩니다.
method_origin_symbolstring
원본 결제 수단의 영문 심볼입니다.
currencystring
결제 완료 시 사용된 통화입니다. 예: KRW는 원화, USD는 달러입니다.
purchased_atdate
결제 완료 시간입니다. * PG에서 제공하는 데이터입니다.
cancelled_atdate
결제 취소 시간입니다. * PG에서 제공하는 데이터입니다.
requested_atdate
결제가 최초 요청된 시간입니다. ISO 8601형식으로 제공됩니다. * 부트페이 서버 시간 기준입니다.
receipt_urlstring
PG사 또는 부트페이에서 제공하는 영수증 URL입니다.
statusnumber
현재 결제 상태입니다.
- -61
  현금영수증 발행 취소가 실패한 상태입니다.
- -60
  현금영수증 발행이 실패한 상태입니다.
- -40
  자동결제 빌링키 발급이 실패한 상태입니다.
- -11
  자동결제 빌링키 발급이 취소된 상태입니다.
- -4
  결제 요청이 실패된 상태입니다.
- -2
  결제 승인 실패로 오류가 발생된 상태입니다.
- 0
  결제가 최초로 생성되어 요청이 대기 중인 상태입니다.
- 1
  결제가 완료된 상태입니다. 부분취소가 된 상태에서 전체금액이 취소되지 않았다면, 결제완료 상태입니다.
- 2
  결제 승인 중인 상태입니다. 분리 옵션으로 프론트엔드 또는 서버 승인 전의 상태입니다.
- 4
  PG로 결제 승인이 요청된 상태이며, 부트페이 내부에서 사용되는 값입니다.
- 5
  가상계좌 발급 및 입금 대기 상태입니다.
- 11
  자동결제를 위한 빌링키 발급이 완료된 상태입니다.
- 12
  본인 인증이 완료된 상태입니다.
- 20
  결제 취소가 된 상태입니다. 결제된 금액이 전액 취소되면 결제 취소 상태가 됩니다.
- 40
  자동결제를 위한 빌링키 발급 준비 상태입니다.
- 41
  자동결제 빌링키 발급 이전 상태입니다. 생체인증, 비밀번호, 위젯 시나리오에서 서버승인 전 상태이기도 합니다.
- 42
  자동결제를 위한 빌링키 발급 성공 상태입니다.
- 50
  본인 인증 시작 준비 상태입니다.
- 60
  현금영수증을 별도 발행 시, 현금영수증 발행이 완료된 상태입니다.
- 61
  현금영수증 별도 발행 시, 현금영수증 발행이 취소된 상태입니다.
escrow_datahash
에스크로 결제 정보입니다. 에스크로 결제가 아닐 경우 이 값은 없습니다.
- statusnumber
  에스크로 진행 상태입니다.
- escrow_status_localestring
  에스크로 진행 상태를 요청 언어로 표시된 값입니다.
- shipping_started_atdate
  배송 시작 시간입니다.
- receipt_confirmed_atdate
  구매자가 배송을 확인하고 구매 승인한 시간입니다.
card_datahash
카드 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- card_approve_nostring
  카드사에서 전달하는 승인 번호입니다.
- card_nostring
  결제 승인 시 마스킹 처리된 카드 번호입니다.
- card_quotastring
  구매자가 선택한 카드 할부 개월 수입니다.
  범위: 00, 02, 03, 04, 05, 06, 07, 08 등
- card_company_codestring
  PG사에서 정의한 카드사 코드입니다.
- card_companystring
  결제 완료된 카드사의 이름입니다.
- card_interest일부 PG만 제공string
  카드 무이자 할부 개월 수입니다.
- card_type일부 PG만 제공string
  결제 완료된 카드의 종류입니다.
  0: 신용카드
  1: 체크카드
- receipt_url다날, 나이스페이만 제공string
  PG에서 제공하는 카드 영수증 URL입니다.
- card_owner_type일부 PG만 제공string
  카드 소유자 유형입니다.
  1: 개인카드
  2: 법인카드
  3: 해외카드
- point일부 PG만 제공number
  결제 시 사용된 카드사 포인트 금액입니다.
- cancelled_point일부 PG만 제공number
  결제 취소된 누적 포인트입니다.
- coupon일부 PG만 제공number
  결제 시 사용된 카드사 쿠폰 금액입니다.
- cancelled_coupon일부 PG만 제공number
  결제 취소된 누적 쿠폰 금액입니다.
- cancel_tid일부 PG만 제공string
  결제 취소 시 PG사에서 발급한 고유 식별 ID입니다.
phone_datahash
휴대폰 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- auth_no일부 PG만 제공string
  휴대폰 소액결제 승인 번호입니다.
- phone일부 PG만 제공string
  소액결제된 휴대폰 번호입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
bank_datahash
실시간 계좌이체 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- bank_codestring
  공통 은행 코드입니다.
- bank_namestring
  계좌이체가 진행된 은행 이름입니다.
- bank_account일부 PG만 제공string
  계좌이체된 계좌 번호입니다.
- bank_usernamestring
  계좌이체된 계좌의 계좌주 이름입니다.
- cash_receipt_typestring
  계좌이체 시 발행된 현금영수증 유형입니다.
  0 : 소득공제
  1 : 지출증빙
- cash_receipt_nostring
  발행된 현금영수증 번호입니다.
- cash_receipt_tidstring
  PG사에서 발급한 고유 현금영수증 TID입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
- cash_receipt_url나이스페이 제공string
  PG에서 제공하는 현금영수증 발행 URL입니다.
vbank_datahash
가상계좌 발급 또는 결제 완료 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
- bank_namestring
  가상계좌가 발급된 은행 이름입니다.
- bank_accountstring
  입금해야 할 가상계좌 번호입니다.
- bank_usernamestring
  가상계좌의 계좌주 이름입니다. 보통 가맹점명이나 PG사 대표 이름으로 노출됩니다.
- expired_atdate
  가상계좌 입금 기한입니다. 이 시간 이후에는 계좌번호로 입금이 불가능합니다.
- sender_name일부 PG만 제공string
  입금 완료 후 입금자명으로 통지됩니다.
- cash_receipt_typestring
  계좌이체 시 발행한 현금영수증 유형입니다.
  0 : 소득공제
  1 : 지출증빙
- cash_receipt_nostring
  발행된 현금영수증 번호입니다.
- cash_receipt_tidstring
  PG사에서 발급한 고유 현금영수증 TID입니다.
- receipt_url나이스페이 제공string
  PG에서 제공하는 영수증 URL입니다.
- cash_receipt_url나이스페이 제공string
  PG에서 제공하는 현금영수증 발행 URL입니다.
kakao_money_data카카오페이 카드결제 시 card_data로 전달됩니다hash
카카오머니 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
naver_point_data네이버페이 카드결제 시 card_data로 전달됩니다hash
네이버페이 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
payco_point_data페이코 카드결제 시 card_data로 전달됩니다hash
페이코 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.
toss_point_data토스 카드결제 시 card_data로 전달됩니다hash
토스 포인트 결제 시 전달되는 데이터입니다.
- tidstring
  PG에서 발급한 결제 고유 식별 ID입니다. 문의 시 이 값을 사용하세요.

백엔드

결제 예약

import { Bootpay } from '@bootpay/backend-js' Bootpay.setConfiguration({    application_id: '[ REST API용 Application ID ]',    private_key: '[ Private KEy ]'}) try {    await Bootpay.getAccessToken()    const response = await Bootpay.subscribePaymentReserve({        billing_key: '62b3d166cf9f6d001bd20d59',        order_name: '테스트 결제',        order_id: (new Date()).getTime(),        price: 1000,        reserve_execute_at: new Date((new Date()).getTime() + 5000)    })    console.log(response)} catch (e) {    console.log(e)}