자동결제

계좌 빌링키(이체)

계좌 자동이체 등록 흐름을 두 단계로 살펴봐요.

계좌 자동이체를 위한 빌링키를 발급받아요. 카드가 아닌 은행 계좌로 정기 결제를 할 때 사용해요.

핵심 요약

  • 계좌 빌링키는 카드 빌링키와 달리 발급 요청과 인증 확정이 분리돼요.
  • 1단계 응답이 status === 41 이면 아직 확정 대기 상태예요. 2단계 publish 호출까지 끝나야 빌링키를 저장해야 해요.
  • 계좌 정보는 저장하면 안 되고, 발급된 billing_key 와 표시용 정보만 저장해야 해요.
  • 현재 지원 범위가 제한적이므로 운영 전 PG 지원 여부를 먼저 확인해요.
지원 PG사

나이스페이먼츠만 지원해요.

발급 흐름

카드 빌링키와 달리, 계좌 빌링키는 2단계 과정​​이 필요해요.

순서 발신 수신 내용
백엔드 BOOTPAY API automatic-transfer / 발급 요청
BOOTPAY API 고객 ARS / 본인인증 진행
고객 BOOTPAY API 인증 완료
BOOTPAY API 백엔드 status === 41 / 확정 대기
백엔드 BOOTPAY API publish 호출
BOOTPAY API 백엔드 billing_key 발급 완료
백엔드 서비스 DB billing_key 저장
status 의미 다음 동작
41 ARS/인증 완료, 확정 대기 2단계 publish 호출
1 빌링키 발급 완료 billing_key 저장 후 사용

1단계: 발급 요청

POSThttps://api.bootpay.co.kr/v2/request/subscribe/automatic-transferBasic Auth

요청 파라미터

파라미터 타입 필수 설명
pg String 필수 PG사 코드
order_name String 필수 주문명
subscription_id String 필수 가맹점 고유 구독 번호
auth_type String 필수 인증 방식 (기본값: ARS)
username String 필수 고객 이름
bank_name String 필수 은행명
bank_account String 필수 계좌번호
identity_no String 필수 생년월일 6자리 또는 사업자등록번호 10자리
phone String 필수 고객 전화번호
price Number 선택 결제 금액
import { Bootpay } from '@bootpay/backend-js'

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

try {
    const response = await Bootpay.requestSubscribeAutomaticTransferBillingKey({
        pg: 'nicepay',
        order_name: '자동이체 등록',
        subscription_id: 'transfer_' + Date.now(),
        auth_type: 'ARS',
        username: '홍길동',
        bank_name: '국민은행',
        bank_account: '12345678901234',
        identity_no: '900101',
        phone: '01012345678'
    })
    // status === 41이면 2단계로 진행
    console.log(response)
} catch (e) {
    console.log(e)
}javascript

2단계: 인증 확정 (Publish)

1단계 응답에서 status === 41(ARS 인증 완료)이면 receipt_id를 사용하여 확정 요청을 보내야 해요.

POSThttps://api.bootpay.co.kr/v2/request/subscribe/automatic-transfer/publishBasic Auth

요청 파라미터

파라미터 타입 필수 설명
receipt_id String 필수 1단계에서 받은 영수증 ID
try {
    const result = await Bootpay.publishAutomaticTransferBillingKey(
        '[ receipt_id ]'
    )
    // billing_key를 데이터베이스에 저장
    console.log(result)
} catch (e) {
    console.log(e)
}javascript

에러 코드

공통 에러

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

코드 메시지 대처 방법
SUBSCRIBE_AT_BLANK_NOT_FOUND (2350) 은행 코드/은행명이 올바르지 않다 bank_name을 올바른 은행명으로 입력해요
SUBSCRIBE_AT_USERNAME_BLANK (2351) 은행 예금주명을 입력한다 username 값을 입력해요
SUBSCRIBE_AT_BANK_ACCOUNT_BLANK (2352) 은행 계좌번호를 입력한다 bank_account 값을 입력해요
SUBSCRIBE_AT_IDENTITY_NO_BLANK (2353) 생년월일/사업자등록번호를 입력한다 identity_no 값을 입력해요
SUBSCRIBE_AT_PHONE_BLANK (2354) 휴대폰 번호를 입력한다 phone 값을 입력해요
SUBSCRIBE_AT_BANK_CODE_BLANK (2356) 은행코드가 올바르지 않거나 비어있다 올바른 은행코드를 입력해요

다음 단계