목차

카드 자동결제를 연동하면 고객은 결제할 때마다 매번 카드 정보를 입력할 필요가 없고, 상점에서는 등록된 카드의 billingKey 값을 사용해서 자동으로 결제할 수 있습니다. 이 방식으로 정기 결제를 구현할 수 있습니다.

샘플 프로젝트빌링키 발급요청 API 프로젝트입니다

자동결제는 추가 계약 후 테스트 및 라이브 환경에서 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

1. 빌링키를 발급받아요

카드 번호, 카드 유효기간, 카드 소유자의 생년월일, 카드 비밀번호 등을 빌링키 발급 요청 API 본문에 포함하세요. 카드 번호와 카드 유효기간은 필수 파라미터입니다. 토스페이먼츠와 계약할 때 옵션으로 비밀번호, 카드 소유자의 생년월일 필드를 필수 파라미터로 추가할 수 있습니다. 이 카드 정보는 빌링키를 발급할 때만 한 번 사용되고, 이후에는 발급받은 빌링키를 자동결제의 결제수단으로 사용합니다.

customerKey도 요청 본문에 포함해야 합니다. customerKey는 가맹점에서 고객을 특정하는 값으로, 빌링키가 발급되면 이 값에 연결됩니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/billing/authorizations/card \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"cardNumber":"4330123412341234","cardExpirationYear":"24","cardExpirationMonth":"07","cardPassword":"12","customerIdentityNumber":"881212","customerKey":"6uSA0QJetFsw-NQoHRaH8"}'

API 호출 결과로 HTTP 200 OK를 받으면 빌링키 발급 성공입니다. 이제 응답 본문에 포함된 billingKey를 이용해 결제 승인을 요청합니다.

응답
{
"mId": "tosspayments",
"customerKey": "",
"authenticatedAt": "2021-01-01T10:01:30+09:00",
"method": "카드",
"billingKey": "",
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "43301234****123*",
"cardType": "신용",
"ownerType": "개인"
}
}
JSON

빌링키와 고객을 특정하는 customerkey를 매핑하여 서버에 저장하세요.

2. 빌링키로 결제 승인을 요청하세요

발급받은 billingKey카드 자동결제 승인 API의 Path 파라미터로 추가합니다. 요청 본문에는 주문 정보와 함께 customerKey를 포함합니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/billing/{billingKey} \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"6uSA0QJetFsw-NQoHRaH8","amount":15000,"orderId":"5TI0aDk6ZJKrjf9GL9hYU","orderName":"토스 티셔츠 외 2건"}'

반드시 customerkey와 일치하는 billingKey를 사용하세요. 만약 값이 일치하지 않으면 NOT_MATCHES_CUSTOMER_KEY 에러가 발생합니다.

3. 자동결제를 성공적으로 완료하셨네요! 🎉

요청이 승인되면 빌링키를 발급받을 때 등록했던 카드로 결제되고, card 객체가 포함된 응답이 돌아옵니다.

응답
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"transactionKey": "",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 프라임 구독",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "43301234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 4900
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "BILLING",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"currency": "KRW",
"totalAmount": 4900,
"balanceAmount": 4900,
"suppliedAmount": 4455,
"vat": 455,
"taxFreeAmount": 0,
"taxExemptionAmount": 0,
"method": "카드"
}
JSON

카드 등록과 첫 번째 결제 같이 하기

billingKey가 발급되는 동시에 자동결제 승인 API를 호출하면 카드 자동결제 등록과 결제가 한 번에 완료됩니다.

자체 간편결제는 카드 자동결제 API 대신 브랜드페이를 사용해서 구현해주세요.


카드 자동결제 API를 자세히 알아보세요

카드 자동결제 API를 직접 실행해보세요

  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기