> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zafapay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# トークン

> ブラウザからカード情報を安全にトークン化

## 概要

トークンを使用すると、自社の決済フォームでカード情報を安全に収集できます。カードデータはJavaScript SDKと公開キーを使用してブラウザ上でトークン化されるため、生のカード番号がサーバーに送信されることはありません。

## トークン作成

`POST /v1/tokens`

**認証:** 公開キー（`pk_test_*` / `pk_live_*`）をBearerトークンとして使用

<Note>
  このエンドポイントは `fetch` やその他のHTTPクライアントから直接呼び出せます。[JavaScript SDK](#javascript-sdk) はオプションです。クライアントサイドのバリデーションやシンプルなAPIを提供しますが、必須ではありません。
</Note>

#### リクエストパラメータ

<ParamField body="card" type="object" required>
  カード情報オブジェクト

  <Expandable title="card のプロパティ">
    <ParamField body="number" type="string" required>
      カード番号（13〜19桁）。スペースとハイフンは自動的に除去されます。
    </ParamField>

    <ParamField body="exp_month" type="integer" required>
      有効期限（月）（1〜12）
    </ParamField>

    <ParamField body="exp_year" type="integer" required>
      有効期限（年）（例: 2027）
    </ParamField>

    <ParamField body="cvc" type="string" required>
      セキュリティコード（3〜4桁）
    </ParamField>

    <ParamField body="cardholder_name" type="string">
      カード名義
    </ParamField>
  </Expandable>
</ParamField>

#### レスポンス

<ResponseField name="id" type="string">
  トークンID（`tok_` プレフィックス）。有効期限30分、1回のみ使用可能。
</ResponseField>

<ResponseField name="card" type="object">
  マスクされたカード情報

  <Expandable title="card のプロパティ">
    <ResponseField name="last4" type="string">
      カード番号の下4桁
    </ResponseField>

    <ResponseField name="brand" type="string">
      カードブランド（`visa`, `mastercard`, `amex`, `discover`, `jcb`, `diners`）
    </ResponseField>

    <ResponseField name="exp_month" type="integer">
      有効期限（月）
    </ResponseField>

    <ResponseField name="exp_year" type="integer">
      有効期限（年）
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="created_at" type="string">
  作成日時（ISO 8601形式）
</ResponseField>

<ResponseField name="expires_at" type="string">
  有効期限（ISO 8601形式）。作成から30分後。
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.sandbox.zafapay.com/v1/tokens \
    -H "Authorization: Bearer pk_test_xxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "card": {
        "number": "4242424242424242",
        "exp_month": 12,
        "exp_year": 2027,
        "cvc": "123",
        "cardholder_name": "John Doe"
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.sandbox.zafapay.com/v1/tokens', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer pk_test_xxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      card: {
        number: '4242424242424242',
        exp_month: 12,
        exp_year: 2027,
        cvc: '123',
        cardholder_name: 'John Doe'
      }
    })
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "id": "tok_xxxxxxxxxxxxxxxxxxxxxx",
    "card": {
      "last4": "4242",
      "brand": "visa",
      "exp_month": 12,
      "exp_year": 2027
    },
    "created_at": "2026-04-07T10:30:00.000Z",
    "expires_at": "2026-04-07T11:00:00.000Z"
  }
  ```
</ResponseExample>

## トークンエラー

| コード                          | HTTPステータス | 説明                    |
| ---------------------------- | --------- | --------------------- |
| `validation_error`           | 400       | カード情報が不正（番号、有効期限、CVC） |
| `tokenization_failed`        | 400       | カードデータのトークン化に失敗       |
| `payment_token_expired`      | 400       | トークンの有効期限切れ（30分制限）    |
| `payment_token_already_used` | 400       | トークンは既に決済に使用済み        |

## トークンを使った決済

トークン作成後、`POST /v1/payments` に渡します：

```json theme={null}
{
  "amount": 10.00,
  "currency": "usd",
  "token": "tok_xxxxxxxxxxxxxxxxxxxxxx",
  "return_url": "https://your-site.com/complete"
}
```

完全な統合ガイドは[サーバー間決済 (S2S)](/ja/guide/s2s-payments)をご覧ください。

<Tip>
  決済リクエストに `save_card: true` と `customer_id` を追加することで、継続決済用にカードを保存できます。詳細は[S2S決済 — カード保存](/ja/guide/s2s-payments#カード保存と継続決済)をご覧ください。
</Tip>

## JavaScript SDK

JavaScript SDKはオプションの便利なラッパーで、クライアントサイドのカードバリデーションとシンプルなAPIを提供します。

```html theme={null}
<script src="https://js.zafapay.com/v1/zafapay.js"></script>
```

```javascript theme={null}
const zafapay = Zafapay('pk_test_xxxxx');

const { token, card, expires_at } = await zafapay.createToken({
  number: '4242424242424242',
  exp_month: 12,
  exp_year: 2027,
  cvc: '123',
  cardholder_name: 'John Doe'
});
// token: "tok_xxxxxxxxxxxxxxxxxxxxxx"
// card: { last4, brand, exp_month, exp_year }
```

<Info>
  SDKはトークンIDを `token` として返します（APIレスポンスのフィールド名は `id` ですが、SDKが便宜上リネームしています）。
</Info>