카드 자동 결제(Billing) API

자동 결제는 고객의 결제 수단 정보를 저장해두고 상점에서 원하는 시점에 결제하는 방법입니다.

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

API를 사용하기 위해 필요한 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.

1. 빌링키 발급받기

카드 번호, 카드 유효기간, 카드 소유자의 생년월일, 카드 비밀번호(선택)를 빌링키 발급 요청 API 본문에 포함하세요. 이 카드 정보는 빌링키를 발급할 때만 한 번 사용되고, 이후에는 발급받은 빌링키를 자동 결제의 결제 수단으로 사용합니다.

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

요청

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/billing/authorizations/card"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"cardNumber\":\"4330123412341234\",\"cardExpirationYear\":\"24\",\"cardExpirationMonth\":\"07\",\"cardPassword\":\"12\",\"customerIdentityNumber\":\"881212\",\"customerKey\":\"tNnoxMVndIRgA56kpnKe-\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

발급된 빌링키가 포함된 응답이 돌아옵니다.

응답

{
  "mId": "tosspayments",
  "customerKey": "",
  "authenticatedAt": "2021-01-01T10:01:30+09:00",
  "method": "카드",
  "billingKey": "",
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "cardType": "신용",
    "ownerType": "개인"
  }
}

JSON

2. 결제 승인 요청하기

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

요청

HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/billing/{billingKey}"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"customerKey\":\"tNnoxMVndIRgA56kpnKe-\",\"amount\":15000,\"orderId\":\"_ARq0sCBIoLKcKJrAoLSK\",\"orderName\":\"토스 티셔츠 외 2건\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

응답

{
  "mId": "tosspayments",
  "version": "1.4",
  "paymentKey": "",
  "orderId": "",
  "orderName": "토스 프라임 구독",
  "currency": "KRW",
  "method": "카드",
  "status": "DONE",
  "requestedAt": "2021-01-01T10:01:30+09:00",
  "approvedAt": "2021-01-01T10:05:40+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq/receipt/"
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "foreignEasyPay": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BILLING",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "totalAmount": 4900,
  "balanceAmount": 4900,
  "suppliedAmount": 4455,
  "vat": 455,
  "taxFreeAmount": 0
}

JSON

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

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

자동 결제는 구독 서비스의 정기 결제, 사용량에 따른 후불 결제 등 상점에서 원하는 시점에 자동으로 결제가 되는 모든 경우에 사용할 수 있습니다.

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

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