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

# カード決済の受け付けと管理

> カード決済を最初から最後まで受け付けて管理します。SDK またはサーバー間通信で、作成、オーソリ、キャプチャ、Void、返金、トークン化を行えます。

<Warning>
  **対象範囲について：** Hello Clever の Card API は、**カード決済の受け付けと管理**（作成、オーソリ、キャプチャ、Void、返金、トークン化）を目的としたものであり、ユーザーへの物理カードやバーチャルカードの発行は対象としていません。このガイドでは、カードの受け付けと管理のライフサイクル全体を扱います。
</Warning>

## 構築するもの

**Card API** では、カード決済のフローを最初から最後までコントロールできます。決済の作成、オーソリ済み資金のキャプチャ、キャプチャ前の Void、キャプチャ後の返金、繰り返し利用のためのカードのトークン化、そして一覧と詳細のエンドポイントによる消込が可能です。ステータスの変更は Webhook で通知され、購入後のフローはアップセルの場面にも対応します。

対応するスキームには Visa、Mastercard、その他の主要ブランドに加え、Apple Pay と Google Pay が含まれます。資金は通貨ごとの Treasury Account へ精算され、自動的に消込されます。

## 連携方法を選ぶ

<CardGroup cols={2}>
  <Card title="SDK（クライアントサイド）" icon="browser">
    Hello Clever の JavaScript SDK を使ったウェブ／モバイルのフロントエンドです。**USD と AUD** に対応します。生のカード情報を扱わずに、そのまま組み込めるチェックアウトに最適です。
  </Card>

  <Card title="サーバー間通信 (S2S)" icon="server">
    自社のバックエンドから生の `card_info` を送信します。**AUD** に対応します。PCI DSS に準拠したシステムで、オーソリとキャプチャを完全にコントロールしたい場合に適します。
  </Card>
</CardGroup>

<Tip>
  PCI DSS に準拠しており、生のカード情報の取り扱いが特に必要な場合を除き、SDK を選んでください。SDK ならカード情報が自社のサーバーを通りません。
</Tip>

## 事前準備

* 加盟店アカウントと `app-id` / `secret-key`。
* サンドボックス `https://api.cleverhub.co`、本番環境 `https://api-merchant.helloclever.co`。
* 決済ステータスの変更を受ける Webhook のエンドポイント（TLS 1.2、公開、商用証明書）。
* S2S の場合：PCI DSS に準拠した環境。

## カードのエンドポイント

| エンドポイント                                       | 目的                                                               |
| --------------------------------------------- | ---------------------------------------------------------------- |
| **Create Payment via Card Information (S2S)** | 生のカード情報から決済インテントを作成します（サーバーサイド、AUD）。                             |
| **Create Payment via Tokenisation**           | 以前にトークン化したカード、または新たに提供されたカードを使って決済を作成します。                        |
| **Capture Payment**                           | オーソリ済みの決済をキャプチャします（全額）。                                          |
| **Void Payment**                              | オーソリ済みの決済をキャプチャ**前**に取り消します（全額）。                                 |
| **Refund Payment**                            | **キャプチャ済み**の決済を全額または一部返金します。                                     |
| **Delete Token**                              | 保存された `token_id` を無効化・削除します。                                     |
| **List Payment**                              | `app-id` のカード取引を取得します。期間とステータスで絞り込みでき、ページ分割に対応します（既定は1ページ 20 件）。 |
| **Detail Payment**                            | 1件のカード取引の完全な詳細です。                                                |

## 決済のライフサイクル

<Steps>
  <Step title="作成（オーソリ）">
    <Tabs>
      <Tab title="SDK">
        フロントエンドで JS SDK を初期化し、決済を作成してコールバックを処理します。導入と初期化については SDK 連携ガイドを参照してください。
      </Tab>

      <Tab title="S2S">
        PCI 準拠のバックエンドから生の `card_info` を **Create Payment via Card Information** へ `POST` します。
      </Tab>

      <Tab title="トークン化">
        保存済みの `token_id` を使って **Create Payment via Tokenisation** を呼び出します（リピート顧客やワンクリックチェックアウトに最適です）。または、新しいカードを使い、その後再利用のためにトークン化することもできます。
      </Tab>
    </Tabs>

    この手順で決済が**オーソリ**されます。フローによっては自動でキャプチャされる場合と、キャプチャ待ちのままオーソリ状態で残る場合があります。
  </Step>

  <Step title="キャプチャまたは Void">
    * 決済がオーソリされたがキャプチャされていない場合は、**Capture Payment** を呼び出して全額を精算します（注文を発送するときなど）。
    * キャプチャ前に取り消す必要がある場合は、**Void Payment** を呼び出します。

    <Info>
      キャプチャと Void は排他的です。Void はキャプチャ前にのみ機能します。
    </Info>
  </Step>

  <Step title="返金">
    キャプチャ後は、**Refund Payment** を使って全額または一部を返金します（返品や価格の調整などの場合）。
  </Step>

  <Step title="購入後・アップセル">
    Card API は購入後のフローに対応します。保存されたトークンを再利用して、顧客がカード情報を再入力せずに、最初の購入の後にアップセルを請求できます。
  </Step>
</Steps>

## トークン化と保存されたカード

カードを一度トークン化すれば、その後は `token_id` を使って **Create Payment via Tokenisation** で請求できます。顧客がカードを削除した場合や不要になった場合は、**Delete Token** を呼び出して無効化してください。

<Warning>
  PCI DSS に準拠し S2S を使用している場合を除き、自社側で保存するのは `token_id` のみとし、生のカード情報は決して保存しないでください。
</Warning>

## 消込

* **List Payment**：レポート作成のため、期間とステータスで取引を取得します。既定では1ページ 20 件でページ分割されます。
* **Detail Payment**：サポートや異議申立ての対応のため、個々の取引を詳しく確認します。

## Webhook

<Warning>
  決済のステータスが変わった（オーソリ、キャプチャ、Void、返金など）ときに自社システムへ通知されるよう、Webhook の通知を設定してください。すべての配信に対して `200 OK` を返し、重複を冪等に処理してください。配信が失敗した場合はリトライされます。ペイロードと署名の詳細は Card Webhook ガイドを参照してください。
</Warning>

## 補足

* カード Payin サービスでは、**サーチャージ**と**デジタルウォレット**（Apple Pay / Google Pay）に対応しています。
* 対応通貨は連携方法に合わせてください。SDK は USD と AUD、S2S は AUD に対応します。


## Related topics

- [カード Payin サービス：カード決済の受け付け](/ja/services/card-payin.md)
- [カード決済の仕組み](/ja/platform-overview/payment-concepts/how-cards-work.md)
- [Payments Account](/ja/platform-overview/clever-concepts/payments-accounts.md)