***

title: 자동결제(빌링) API로 연동하기
description: 구매자의 카드 정보를 등록해 빌링키를 얻고 자동결제를 연동하는 방법을 알아보세요.
keyword: 정기 결제, 빌링, billing, 구독, billingKey, 빌링키, 구독 결제, 빌링키 발급, schedule, scheduling, cron, cron job, 스케줄링, 스케줄러, 빌링키 관리, 추가 계약, 카드 등록, 결제 주기 변경, 원하는 시점, 특정 시점
searchIndex: false
------------------

**Version 1**

# 자동결제(빌링) API로 연동하기

> **경고**: 결제창 SDK v1은 더 이상 업데이트되지 않습니다. [토스페이먼츠 SDK v2](/guides/v2/billing) 연동을 추천합니다.

✅ 토스페이먼츠 API만으로 자동결제를 연동하고 구독 결제 서비스를 만들어보세요. (서버 투 서버)

✅ 구매자의 카드를 처음 한 번 등록할 때 본인인증을 마치고 [빌링키](/guides/billing/overview#빌링키란)를 발급하면, 별도의 인증 없이 간편하게 빌링키로 계속 결제할 수 있습니다.

✅ API로 자동결제를 연동하면 본인인증은 직접 구현해야 합니다. [결제창 방식](/guides/billing/integration)으로 연동하면 토스페이먼츠에서 휴대폰 본인인증을 제공합니다.



title: 자동결제 API 레퍼런스
description: 응답 객체, API 엔드포인트 및 파라미터를 자세히 살펴보세요.
href: /reference#자동결제




title: API 실행해보기
description: 카드 자동결제 빌링키 발급 API를 직접 실행해보세요.
href: /reference/test/v1/billing/authorizations/issue/POST


## API 키 준비하기

자동결제는 [**API 개별 연동 키**](/reference/using-api/api-keys#api-키-이해하기)로 연동하세요.

개발자센터의 [API 키 메뉴](https://developers.tosspayments.com/my/api-keys)에서 클라이언트 키와 시크릿 키를 확인하고 코드의 `{CLIENT_KEY}`, `{SECRET_KEY}` 자리에 넣으세요. 아직 회원이 아니라면 이메일 주소만으로 간편하게 [회원가입](https://app.tosspayments.com/signup)할 수 있어요.

```js
// API 개별 테스트 연동 키
// 개발자센터 API 키 메뉴에서 확인한 키를 넣으세요.
const clientKey = "{CLIENT_KEY}";
const secretKey = "{SECRET_KEY}";
```

## 자동결제 연동 흐름 이해하기

![자동결제-흐름](https://static.tosspayments.com/docs/billing/billing-overview.png#1502x765)

큰 흐름은 다음과 같습니다.

* **빌링키 발급 API 요청 (Server)**: API로 빌링키를 발급하고 데이터베이스에 저장하세요. 빌링키 발급 전 본인인증은 직접 구현해야 합니다.
* **빌링 결제 승인 요청 (Server)**: API로 발급한 빌링키로 원하는 주기, 시점에 자동결제를 실행하세요. 스케줄링 기능은 직접 구현해야 합니다. [스케줄링 예제](/guides/billing/integration#구독-스케줄링-예제)를 참고하세요.

API로 연동하면 UI는 직접 구현해야 합니다. [결제창 방식](/guides/billing/integration)으로 연동하면 토스페이먼츠에서 카드 등록창과 본인인증 기능을 제공합니다.

## 1. 빌링키 발급하기

먼저 [API 인증](/reference/using-api/authorization)을 위해 아래와 같이 인증 헤더 값을 만듭니다. 시크릿 키 뒤에 `:`을 추가하고 base64로 인코딩합니다. **`:`을 빠트리지 않도록 주의하세요.**

```bash theme="grey" copyable="false" feedbackable="false"
base64('{SECRET_KEY}:')
        ─────┬───── ┬
             │      └─ 콜론
             └─ 발급받은 시크릿 키
```

아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.

```bash theme="grey" copyable="false"
echo -n '{SECRET_KEY}:' | base64
```

인코딩된 값을 [Basic 인증 헤더](/reference/using-api/authorization)에 넣고 카드 번호, 카드 유효기간, 카드 소유자의 생년월일, 카드 비밀번호 등을 빌링키 발급 요청 API 본문에 포함하세요.

카드 번호와 카드 유효기간은 필수 파라미터입니다. 카드 정보는 빌링키를 발급할 때만 한 번 사용되고, 이후에는 카드 정보 대신 발급한 빌링키로 결제를 실행합니다. 토스페이먼츠와 계약할 때 요청하면 비밀번호, 카드 소유자의 생년월일 정보도 빌링키 발급을 위한 필수 파라미터로 추가할 수 있습니다.

#### 카드 정보로 빌링키 발급

POST

/v1/billing/authorizations/card



title: 'NOT\_SUPPORTED\_METHOD' 에러는 왜 발생하나요?


자동결제 계약이 안 되어 있는 클라이언트 키로 연동하면 발생합니다. 자동결제 계약이 되어있는 클라이언트 키를 사용하거나 토스페이먼츠 고객센터(1544-7772, 평일 오전 8시~오후 7시)로 문의해주세요.

#### 파라미터



name: customerKey
required: true
type: string


구매자 ID입니다. 빌링키와 연결됩니다. 다른 사용자가 이 값을 알게 되면 악의적으로 사용될 수 있습니다. 자동 증가하는 숫자 또는 이메일・전화번호・사용자 아이디와 같이 유추가 가능한 값은 안전하지 않습니다. [UUID](/resources/glossary/uuid)와 같이 충분히 무작위적인 고유 값으로 생성해주세요.



name: cardNumber
required: true
type: string


카드 번호입니다. 최대 길이는 20자입니다.

\* 테스트 환경에서는 카드 번호의 앞 여섯 자리(BIN 번호)만 유효해도 자동결제가 등록됩니다. 라이브 환경에서는 전체 카드 번호가 유효해야 등록됩니다.



name: cardExpirationYear
required: true
type: string


카드 유효 연도입니다.



name: cardExpirationMonth
required: true
type: string


카드 유효 월입니다.



name: customerIdentityNumber
required: true
type: string


카드 소유자 정보입니다. 생년월일 6자리(`YYMMDD`) 혹은 사업자등록번호 10자리가 들어갑니다.



name: cardPassword
required: true
type: string


카드 비밀번호 앞 두 자리입니다.



name: customerName
type: string


구매자명입니다. 최대 길이는 100자입니다.



name: customerEmail
type: string


구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 [결제내역](/guides/learn/payment-results#이메일)이 전송됩니다. 최대 길이는 100자입니다.

### API 결과 확인하기

API 호출 결과로 HTTP `200 OK`를 받으면 빌링키 발급 성공입니다. 이제 응답 본문에 포함된 [`billingKey`](/reference#billingconfirmdto-billingkey)를 이용해 결제 승인을 요청합니다.

```json title="응답" {6}
{
  "mId": "tosspayments",
  "customerKey": "<UniqueId name='customerKey.cardBilling' />",
  "authenticatedAt": "2021-01-01T10:01:30+09:00",
  "method": "카드",
  "billingKey": "<UniqueId name='billingKey.cardBilling' />",
  "card": {
    "issuerCode": "61",
    "acquirerCode": "31",
    "number": "43301234****123*",
    "cardType": "신용",
    "ownerType": "개인"
  },
  "cardCompany": "현대",
  "cardNumber": "43301234****123*"
}
```

### 빌링키 관리하기

구매자를 특정하는 [`customerKey`](/reference#v1billingauthorizationsissuepost-customerkey)와 빌링키를 매핑해서 서버에 저장하세요. 한 번 발급된 빌링키는 다시 조회할 수 없습니다. 저장한 키값으로 자동결제를 요청해주세요.

빌링키의 유효기간은 빌링키와 연결된 카드 유효기간과 같습니다. 발급된 빌링키가 더 이상 필요하지 않으면 사용하지 않거나 [빌링키 삭제 API](/reference#빌링키-삭제)로 삭제하세요.



title: 구매자가 등록한 카드가 결제할 수 있는 카드인지 유효성을 검사할 수 있는 방법은 없나요?


별도로 제공하지 않습니다. 자동결제에 등록할 카드의 유효성 여부는 빌링키 발급을 요청할 때 카드사를 통해 확인합니다. 만약 유효하지 않다면 [에러](/reference/error-codes#카드-자동결제-빌링키-발급-요청)를 응답합니다. 카드 잔고 부족이나 한도 초과는 [결제 승인을 요청](/reference#자동결제-승인)할 때 카드사를 통해 확인합니다.



title: 구매자가 카드를 재발급 받거나 카드 유효기간이 만료되면 어떻게 해야 하나요?


새로운 카드 정보로 빌링키를 다시 발급하세요. 별도로 빌링키를 갱신하는 과정은 없습니다.

## 2. 빌링키로 자동결제 실행하기

발급한 [`billingKey`](/reference#v1billingbillingkeypost-billingkey)를 [카드 자동결제 승인 API](/reference#자동결제-승인)의 Path 파라미터로 추가합니다. 요청 본문에는 주문 정보와 함께 [`customerKey`](/reference#v1billingbillingkeypost-customerkey)를 포함합니다.



title: 'NOT\_MATCHES\_CUSTOMER\_KEY' 에러는 왜 발생하나요?


[`customerkey`](/reference#billingconfirmdto-customerkey)와 매핑되지 않은 [`billingKey`](/reference#billingconfirmdto-billingkey)를 사용하면 발생합니다.

### 구독 스케줄링 예제

**토스페이먼츠에서는 자체적으로 스케줄링 기능을 제공하지 않습니다.** 따라서 직접 스케줄링 기능을 구현해서 원하는 주기, 시점에 결제를 실행해야 합니다.

만약 Node.js 애플리케이션에 스케줄링 로직을 추가하려면, [`node-cron`](https://www.npmjs.com/package/node-cron)과 같은 패키지를 사용할 수 있습니다. 이 패키지를 사용하면 스케쥴을 정의하고 그에 따라 특정 작업을 자동으로 실행할 수 있습니다. 각 언어나 프레임워크에서 제공하는 스케줄링 기능을 사용하세요.

먼저 [`node-cron`](https://www.npmjs.com/package/node-cron) 패키지를 설치해야 합니다. 프로젝트의 루트 디렉토리에서 다음 명령어를 실행하세요.

```bash
npm install --save node-cron
```

이제 [`node-cron`](https://www.npmjs.com/package/node-cron)을 사용하여 매월 1일에 자동결제를 진행하는 스케쥴러를 설정할 수 있습니다. 아래 코드는 기존 `routes/index.js` 파일에 스케쥴러를 추가하는 방법을 보여줍니다:

```javascript {3}
var express = require("express");
var got = require("got");
var cron = require("node-cron"); // 스케줄링을 위해 cron 잡을 수행할 수 있는 node-cron 패키지 추가
var uuid = require("uuid").v4;
var router = express.Router();

router.get("/", function (req, res) {
  res.render("index");
});

router.get("/billing_confirm", function (req, res) {
  // ...
}

// 매 달 1일 01:00에 스케줄링을 수행하는 cron 잡 추가
cron.schedule("0 0 1 * *", function() {
  console.log("매월 1일 01:00에 결제 실행하기");
  got.post("https://api.tosspayments.com/v1/billing/" + billingKey, {
    headers: {
      Authorization:
        "Basic " + Buffer.from(secretKey + ":").toString("base64"),
      "Content-Type": "application/json",
    },
    json: {
      customerKey: "test_customer_key",
      amount: 50000,
      orderId: uuid(),
      orderName: ‘토스 프라임 구독’,
      customerEmail: "customer@email.com",
      customerName: "박토스",
      taxFreeAmount: 0
    },
    responseType: "json",
  })
  .then(function (response) {
    console.log(response.body);
  })
  .catch(function (error) {
    console.log(‘Error:’, error);
  });
})
// ...
```

위 코드는 매월 1일에 [`billingKey`](/reference#v1billingbillingkeypost-billingkey)\`를 사용하여 자동결제를 진행하는 스케쥴러입니다. 이러한 방식으로 스케줄링 로직을 추가하면, 매월 1일마다 자동으로 지정된 결제가 진행됩니다. 실제 서비스에서는 에러 처리, 로깅, 데이터베이스와의 통신 등이 추가로 필요할 수 있습니다.



title: 구매자가 구독을 취소하면 어떻게 해야 하나요?


다음 결제일에 구독을 취소한 구매자의 빌링키,`customerKey`로 [카드 자동결제 승인 API](/reference#자동결제-승인)를 호출하지 않으면 됩니다. 사용하지 않는 빌링키는 [빌링키 삭제 API](/reference#빌링키-삭제)로 삭제할 수 있습니다.



title: 구독 결제 금액이 변경되면 어떻게 해야 하나요?


[카드 자동결제 승인 API](/reference#자동결제-승인)를 호출할 때 `amount` 파라미터를 변경된 결제 금액으로 설정하면 됩니다.



title: 구독 결제 주기가 변경되면 어떻게 해야 하나요?


[카드 자동결제 승인 API](/reference#자동결제-승인)를 호출하는 주기를 변경해주세요.

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

[`billingKey`](/reference#billingconfirmdto-billingkey)가 발급되는 동시에 [자동결제 승인 API](/reference#자동결제-승인)를 호출하면 카드 자동결제 등록과 결제가 한 번에 완료됩니다.

> **참고**: - 자동결제는 정기 구독형 서비스에만 사용할 수 있어요. 비정기 결제 서비스에는 정책적으로 사용이 제한되니 유의하세요.
>
> - 해외카드, 해외결제는 정기결제를 지원하지 않습니다.

## 3. 결제 완료 후 응답 확인하기

요청이 승인되면 빌링키를 발급할 때 등록했던 카드로 결제되고, [`card`](/reference#paymentdetaildto-card) 객체가 포함된 응답이 돌아옵니다.

```json title="응답" {14-27,55}
{
  "mId": "tosspayments",
  "version": "2024-06-01",
  "paymentKey": "<UniqueId name='paymentKey.cardBilling' />",
  "status": "DONE",
  "transactionKey": "<UniqueId name='transactionKey.cardBilling' />",
  "lastTransactionKey": "<UniqueId name='lastTransactionKey.cardBilling' />",
  "orderId": "<UniqueId name='orderId.cardBilling' />",
  "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/<ClientKey />/receipt/<UniqueId name='paymentKey.cardBilling' />"
  },
  "checkout": {
    "url": "https://api.tosspayments.com/v1/payments/<UniqueId name='paymentKey.cardBilling' />/checkout"
  },
  "currency": "KRW",
  "totalAmount": 4900,
  "balanceAmount": 4900,
  "suppliedAmount": 4455,
  "vat": 455,
  "taxFreeAmount": 0,
  "metadata": null,
  "taxExemptionAmount": 0,
  "method": "카드"
}
```



title: 응답 객체에 원하는 필드가 없어요.


응답 객체의 필드는 API 버전에 따라 조금씩 달라집니다. [개발자센터](https://developers.tosspayments.com/my/api-keys)에 설정된 API 버전을 확인하고, 원하는 필드가 있는 버전으로 변경해보세요.

API 버전 업데이트 사항은 [릴리즈 노트](/resources/release-note)에서 확인할 수 있습니다.

***

[카드 자동결제 API를 자세히 알아보세요](/reference#카드-정보로-빌링키-발급)

[카드 자동결제 API를 직접 실행해보세요](/reference/test/v1/billing/authorizations/card/POST)