카드 등록 후 자동으로 결제하기 (빌링)

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

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

API 실행해보기카드 자동결제 빌링키 발급 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를 직접 실행해보세요