빌링키 조회 | Bootpay 결제 매뉴얼

유효한 빌링키인지 조회해요. 빌링키가 유효하지 않으면 결제를 요청할 수 없으며, 처음부터 다시 발급받아야 해요.

핵심 요약

최초 발급 직후에는 receipt_id로 조회해 billing_key를 확인해요.
이미 저장된 빌링키의 상태를 확인할 때는 billing_key로 조회해요.
조회 응답의 카드/계좌 정보는 사용자 화면 표시용으로만 저장해야 해요.
유효하지 않은 빌링키는 재사용하지 말고 다시 발급받아요.

조회 기준

상황	조회 키	다음 단계
프론트엔드 발급 직후	`receipt_id`	`billing_key`를 DB에 저장
저장된 빌링키 상태 확인	`billing_key`	결제 요청 가능 여부 판단
카드 변경 후 새 빌링키 확인	새 발급 `receipt_id`	기존 빌링키 `revoked`, 새 빌링키 `active`

receipt_id로 조회

빌링키 발급 시 받은 영수증 ID로 조회해요.

GEThttps://api.bootpay.co.kr/v2/subscribe/billing_key/:receipt_idBasic Auth

파라미터	타입	필수	설명
`receipt_id`	String	필수	빌링키 발급 시 받은 영수증 ID (URL 파라미터)

billing_key로 조회

이미 발급받은 빌링키로 조회해요.

GEThttps://api.bootpay.co.kr/v2/billing_key/:billing_keyBasic Auth

파라미터	타입	필수	설명
`billing_key`	String	필수	부트페이에서 부여한 빌링키 (URL 파라미터)

최초 발급 시에는 billing_key 값을 알 수 없으므로, receipt_id로 조회해야 해요.

코드 예제

import { Bootpay } from '@bootpay/backend-js'

Bootpay.setConfiguration({
    client_key: '[ Client Key ]',
    secret_key: '[ Secret Key ]'
})

try {
    const response = await Bootpay.lookupSubscribeBillingKey(
        '[ receipt_id ]'
    )
    // billing_key를 데이터베이스에 저장
    console.log(response)
} catch (e) {
    console.log(e)
}javascript

from bootpay_backend import BootpayBackend

bootpay = BootpayBackend('APPLICATION_ID', 'PRIVATE_KEY')

response = bootpay.lookup_subscribe_billing_key('[ receipt_id ]')
print(response)python

use Bootpay\ServerPhp\BootpayApi;

BootpayApi::setConfiguration('APPLICATION_ID', 'PRIVATE_KEY');
$response = BootpayApi::lookupSubscribeBillingKey('[ receipt_id ]');
print_r($response);php

import kr.co.bootpay.pg.Bootpay;

Bootpay bootpay = new Bootpay("APPLICATION_ID", "PRIVATE_KEY");
var response = bootpay.lookupBillingKey("[ receipt_id ]");
System.out.println(response);java

bootpay = Bootpay::Api.new(application_id: 'APPLICATION_ID', private_key: 'PRIVATE_KEY')
response = bootpay.request(
  method: :get,
  uri: 'subscribe/billing_key/[ receipt_id ]'
)
puts response.dataruby

import "github.com/bootpay/backend-go/v2"

api := bootpay.NewAPI("APPLICATION_ID", "PRIVATE_KEY", nil, "")
response, err := api.LookupBillingKey("[ receipt_id ]")
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)go

using Bootpay;

var bootpay = new BootpayApi("APPLICATION_ID", "PRIVATE_KEY");
var response = await bootpay.LookupBillingKey("[ receipt_id ]");
Console.WriteLine(response);csharp

응답

빌링키 조회 결과는 status로 발급 상태를 확인해요. status: "11"이면 빌링키 발급이 완료된 상태예요.

{
  "receipt_id": "6261104e1fc19202e6f9420e",
  "published_at": "2025-01-15T14:32:00+09:00",
  "status_locale": "빌링키발급완료",
  "status": "11",
  "billing_key": "615d00f0197c300036b4fef5",
  "billing_data": {
    "card_company": "하나카드",
    "card_no": "5570-****-****-1074",
    "card_company_code": "046",
    "card_type": 0,
    "card_hash": "f5b2a..."
  },
  "billing_expired_at": "2099-12-31T23:59:59+09:00"
}json

응답 파라미터

파라미터	타입	설명
published_at	Date	빌링키 발급 시간 (ISO 8601)
status_locale	String	빌링키 발급 상태 한글 ("빌링키발급완료")
status	String	빌링키 발급 상태 ("11" = 완료)
billing_key	String	빌링키 — 반드시 데이터베이스에 저장
billing_data	Object	빌링키와 연결된 카드/계좌 정보
billing_data.card_company	String	카드사명 (자동카드결제)
billing_data.card_no	String	마스킹된 카드번호 (자동카드결제)
billing_data.card_company_code	String	PG사 정의 카드사 코드 (자동카드결제)
billing_data.card_type	Number	카드 종류 (0: 신용카드, 1: 체크카드)
billing_data.card_hash	String	카드 고유 HASH (KCP만 전달)
billing_data.bank_code	String	은행코드 3자리 (자동계좌이체)
billing_data.bank_name	String	은행명 (자동계좌이체)
billing_data.bank_account	String	마스킹된 계좌번호 (자동계좌이체)
billing_data.username	String	계좌주명 (자동계좌이체)
billing_expired_at	Date	빌링키 만료일 (ISO 8601)

에러 코드

인증·권한 관련 에러는 에러 코드표를 참고해요.

코드	메시지	대처 방법
`SUBSCRIBE_BK_NOT_FOUND` (2309)	빌링키 발급 내역을 찾지 못했다	receipt_id 또는 billing_key가 올바른지 확인해요
`SUBSCRIBE_NOT_SUCCESS` (2308)	빌링키 발급이 완료된 건이 아니다	빌링키 발급이 정상 완료되었는지 확인해요
`RC_NOT_SUBSCRIBE` (2057)	정기결제 요청 정보가 아니다	정기결제 관련 영수증인지 확인해요

다음 단계

빌링키가 유효하면 결제를 요청해요 → 빌링키 결제 요청
미래 결제를 맡기려면 → 예약결제
더 이상 쓰지 않는 빌링키라면 → 빌링키 삭제