계좌 자동이체를 위한 빌링키를 발급받아요. 카드가 아닌 은행 계좌로 정기 결제를 할 때 사용해요.
핵심 요약
- 계좌 빌링키는 카드 빌링키와 달리 발급 요청과 인증 확정이 분리돼요.
- 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단계: 발급 요청
POST
https://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# Python 서버 SDK에는 자동이체 빌링키 발급 헬퍼가 없어요.
# 이 API는 REST API로 직접 호출해요.pythonuse Bootpay\ServerPhp\BootpayApi;
BootpayApi::setConfiguration('APPLICATION_ID', 'PRIVATE_KEY');
$response = BootpayApi::requestSubscribeAutomaticTransferBillingKey([
'pg' => 'nicepay',
'order_name' => '자동이체 등록',
'subscription_id' => 'transfer_' . time(),
'auth_type' => 'ARS',
'username' => '홍길동',
'bank_name' => '국민은행',
'bank_account' => '12345678901234',
'identity_no' => '900101',
'phone' => '01012345678',
]);
// status === 41이면 2단계로 진행
print_r($response);phpimport kr.co.bootpay.pg.Bootpay;
import kr.co.bootpay.pg.model.request.Subscribe;
Bootpay bootpay = new Bootpay("APPLICATION_ID", "PRIVATE_KEY");
Subscribe transfer = new Subscribe();
transfer.pg = "nicepay";
transfer.orderName = "자동이체 등록";
transfer.subscriptionId = "transfer_" + System.currentTimeMillis();
transfer.authType = "ARS";
transfer.username = "홍길동";
transfer.bankName = "국민은행";
transfer.bankAccount = "12345678901234";
transfer.identityNo = "900101";
transfer.phone = "01012345678";
var response = bootpay.getBillingKeyTransfer(transfer);
// status === 41이면 2단계로 진행
System.out.println(response);java# Ruby 서버 SDK에는 자동이체 빌링키 발급 헬퍼가 없어요.
# 이 API는 REST API로 직접 호출해요.rubyimport "github.com/bootpay/backend-go/v2"
api := bootpay.NewAPI("APPLICATION_ID", "PRIVATE_KEY", nil, "")
response, err := api.RequestSubscribeAutomaticTransferBillingKey(bootpay.BillingKeyPayload{
Pg: "nicepay",
OrderName: "자동이체 등록",
SubscriptionID: fmt.Sprintf("transfer_%d", time.Now().Unix()),
AuthType: "ARS",
Username: "홍길동",
BankName: "국민은행",
BankAccount: "12345678901234",
IdentityNo: "900101",
Phone: "01012345678",
})
if err != nil {
log.Fatal(err)
}
// status === 41이면 2단계로 진행
fmt.Println(response)gousing Bootpay;
using Bootpay.models;
var bootpay = new BootpayApi("APPLICATION_ID", "PRIVATE_KEY");
var response = await bootpay.GetBillingKeyTransfer(new Subscribe
{
pg = "nicepay",
orderName = "자동이체 등록",
subscriptionId = $"transfer_{DateTimeOffset.UtcNow.ToUnixTimeSeconds()}",
authType = "ARS",
username = "홍길동",
bankName = "국민은행",
bankAccount = "12345678901234",
identityNo = "900101",
phone = "01012345678"
});
// status === 41이면 2단계로 진행
Console.WriteLine(response);csharp2단계: 인증 확정 (Publish)
1단계 응답에서 status === 41(ARS 인증 완료)이면 receipt_id를 사용하여 확정 요청을 보내야 해요.
POST
https://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# Python 서버 SDK에는 자동이체 빌링키 확정 헬퍼가 없어요.
# 이 API는 REST API로 직접 호출해요.python$result = BootpayApi::publishAutomaticTransferBillingKey('[ receipt_id ]');
// billing_key를 데이터베이스에 저장
print_r($result);phpvar result = bootpay.publishBillingKeyTransfer("[ receipt_id ]");
// billing_key를 데이터베이스에 저장
System.out.println(result);java# Ruby 서버 SDK에는 자동이체 빌링키 확정 헬퍼가 없어요.
# 이 API는 REST API로 직접 호출해요.rubyresult, err := api.PublishAutomaticTransferBillingKey("[ receipt_id ]")
if err != nil {
log.Fatal(err)
}
// billing_key를 데이터베이스에 저장
fmt.Println(result)govar result = await bootpay.PublishBillingKeyTransfer("[ receipt_id ]");
// billing_key를 데이터베이스에 저장
Console.WriteLine(result);csharp에러 코드
공통 에러
인증·권한 관련 에러는 에러 코드표를 참고해요.
| 코드 | 메시지 | 대처 방법 |
|---|---|---|
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) |
은행코드가 올바르지 않거나 비어있다 | 올바른 은행코드를 입력해요 |
