빌링키 삭제 | Bootpay 결제 매뉴얼

더 이상 사용하지 않는 빌링키를 삭제해요. 삭제 후에는 해당 빌링키로 결제를 요청할 수 없어요.

핵심 요약

빌링키 삭제는 결제수단 토큰을 더 이상 사용하지 못하게 하는 작업이에요.
해지·탈퇴·카드 변경 시 내부 DB 상태도 revoked로 바꿔 청구 대상에서 제외해야 해요.
삭제 후에는 같은 빌링키로 빌링키 결제 요청이나 예약 등록을 할 수 없어요.
이미 등록된 예약결제가 있다면 삭제 전에 예약 조회와 예약 취소를 먼저 처리해야 해요.

삭제 전 점검 흐름

API 엔드포인트

DELETEhttps://api.bootpay.co.kr/v2/subscribe/billing_key/:billing_keyBasic Auth

/v2/subscribe/billing_key/:id는 메서드에 따라 :id에 넣는 값이 달라요. GET은 발급 시 받은 receipt_id를 넣고, DELETE는 발급된 billing_key를 넣어야 해요. 반대로 넣으면 SUBSCRIBE_BK_NOT_FOUND(2309) 또는 RC_NOT_FOUND(2000)가 나와요.

빌링키 삭제는 결제수단 토큰을 삭제하는 작업이고, 예약 취소는 미래 결제 예약을 제거하는 작업이에요. 빌링키를 삭제해도 이미 등록된 예약결제가 자동으로 취소된다고 가정하면 안 돼요. 예약결제까지 중단해야 한다면 먼저 예약 취소를 호출하고, 그 다음 빌링키를 삭제해요. 자세한 순서는 예약결제 운영 주의사항을 참고해요.

요청 파라미터

파라미터	타입	필수	설명
`billing_key`	String	필수	삭제할 빌링키 (URL 파라미터)

코드 예제

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

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

try {
    const response = await Bootpay.destroyBillingKey('[ billing_key ]')
    console.log(response)
} catch (e) {
    console.log(e)
}javascript

from bootpay_backend import BootpayBackend

bootpay = BootpayBackend(client_key='CLIENT_KEY', secret_key='SECRET_KEY')

response = bootpay.destroy_billing_key('[ billing_key ]')
print(response)python

use Bootpay\ServerPhp\BootpayApi;

BootpayApi::setClientKeyConfiguration('CLIENT_KEY', 'SECRET_KEY');
$response = BootpayApi::destroyBillingKey('[ billing_key ]');
print_r($response);php

import kr.co.bootpay.pg.Bootpay;

Bootpay bootpay = Bootpay.withClientKey("CLIENT_KEY", "SECRET_KEY");
var response = bootpay.destroyBillingKey("[ billing_key ]");
System.out.println(response);java

bootpay = Bootpay::Api.new(client_key: 'CLIENT_KEY', secret_key: 'SECRET_KEY')
response = bootpay.destroy_billing_key('[ billing_key ]')
puts responseruby

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

api := bootpay.NewAPIWithClientKey("CLIENT_KEY", "SECRET_KEY", nil, "")
response, err := api.DestroyBillingKey("[ billing_key ]")
if err != nil {
    log.Fatal(err)
}
fmt.Println(response)go

using Bootpay;

var bootpay = BootpayApi.WithClientKey("CLIENT_KEY", "SECRET_KEY");
var response = await bootpay.DestroyBillingKey("[ billing_key ]");
Console.WriteLine(response);csharp

응답

성공 응답

{
  "billing_key": "[ 취소된 billing key ]"
}json

에러 응답

에러 응답은 error_code, pg_error_code(PG가 내려준 코드가 있을 때만), message, payload(추가 정보가 있을 때만) 형태로 내려와요. 아래는 Basic 인증에 사용한 Private Key(Secret Key)가 맞지 않을 때의 예시예요.

{
  "error_code": "APP_SK_NOT_MATCHED",
  "message": "Private Key가 올바르지 않습니다. 부트페이 관리자에서 다시 확인해주시기 바랍니다."
}json

에러 코드

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

코드	메시지	대처 방법
`SUBSCRIBE_BK_NOT_FOUND` (2309)	빌링키 발급 내역을 찾지 못했다	billing_key가 올바른지 확인해요
`SUBSCRIBE_BK_EXPIRED` (2310)	빌링키 유효기간 만료	유효기간이 지났거나 이미 삭제된 빌링키예요. 삭제하면 빌링키가 사용불가(UNABLE) 상태가 되고, 이후 같은 빌링키로 다시 삭제를 호출하면 만료로 판정돼요. 새로 발급받아요

다음 단계

삭제 전 대기 중 예약이 있는지 확인하려면 → 예약 조회
대기 중 예약을 먼저 멈추려면 → 예약 취소
새 결제수단을 등록하려면 → 빌링키 발급