시작하기
4. 자동 결제 승인하기
활성화된 빌링키로 구매자 인증 없이 결제를 실행해요.
이 단계에서는 활성화된 빌링키로 실제 결제를 실행해요. 매월 구독료를 청구하는 시점처럼 가맹점이 원하는 때에 승인 API를 호출하면 되고, 유효시간이나 횟수 제한이 없어요. 청구 주기 관리(매월 1일 청구 등)는 가맹점 서버의 스케줄러가 담당해요.
자동 결제 승인 API Endpoint
POST https://pay.toss.im/api/v1/billing-key/bill
승인 API 호출하기
curl https://pay.toss.im/api/v1/billing-key/bill \
-H "Content-Type: application/json" \
-d '{
"apiKey": "sk_test_w5lNQylNqa5lNQe013Nq",
"billingKey": "example-billingKey",
"orderNo": "subscribe-2026-07-0001",
"productDesc": "프리미엄 멤버십 월 구독",
"amount": 9900,
"amountTaxFree": 0,
"spreadOut": 0,
"cashReceipt": true,
"cashReceiptTradeOption": "GENERAL",
"sendFailPush": true
}'| 파라미터 | 필수 | 설명 |
|---|---|---|
apiKey | 필수 | 빌링키 생성 때 사용한 API Key와 동일해야 해요. |
billingKey | 필수 | 3단계에서 활성화를 확인한 빌링키예요. |
orderNo | 필수 | 가맹점 주문번호예요. 유니크하게 관리하고, 허용 특수문자는 _ - : . ^ @ =예요. |
productDesc | 필수 | 상품 설명이에요. |
amount | 필수 | 결제 요청 금액이에요. |
amountTaxFree | 필수 | 결제 금액 중 비과세 금액이에요. 없으면 0을 넣어요. |
spreadOut | 필수 | 카드 할부 개월 수예요. 0이 일시불이고, 5만 원 미만은 일시불만 가능해요. |
cashReceipt | 필수 | 토스 현금영수증 자동발행 사용 여부예요. |
cashReceiptTradeOption | 필수 | 현금영수증 발행 유형이에요. GENERAL(일반), CULTURE(문화비), PUBLIC_TP(대중교통) 중 선택해요. |
sendFailPush | 필수 | 결제 실패 시 사용자에게 실패 알림을 보낼지 여부예요. |
과세 금액 구성, 선승인 같은 선택 파라미터는 자동 결제 승인 요청 레퍼런스에서 확인할 수 있어요.
응답 확인하기
승인에 성공하면 결제 결과가 바로 응답으로 와요. 일반 결제와 달리 별도 콜백을 기다릴 필요 없이 이 응답으로 완료 처리하면 돼요.
{
"code": 0,
"mode": "TEST",
"payToken": "example-payToken",
"orderNo": "subscribe-2026-07-0001",
"payMethod": "CARD",
"amount": 9900,
"discountedAmount": 0,
"paidAmount": 9900,
"approvalTime": "2026-07-14 12:00:00",
"transactionId": "example-transaction-id"
}code가0이면 성공이에요. 실패하면code: -1과 함께errorCode,msg가 전달되니 이 값으로 분기하세요.payToken은 이 결제 건의 고유 값이에요. 환불이나 결제 상태 조회는 일반 결제와 같은 API를 이 값으로 호출해요.mode가TEST면 테스트용 API Key로 승인된 결제라 실제 출금이 없어요.- 카드 결제면 카드 승인 정보(
cardCompanyName,cardAuthorizationNo등)가 함께 와요.
환불과 결제 조회
승인된 결제 건의 환불과 상태 조회는 일반 결제와 같은 API를 사용해요.
- 환불은 결제 환불하기에서
payToken으로 요청해요. - 결제 건 상태는 결제 상태 알아보기로 조회해요.
다음 단계
결제까지 완주했어요. 마지막으로 빌링키 운영에 필요한 관리 기능을 알아봐요. 5. 빌링키 관리하기로 이동하세요.