> ## 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.

# PayTo 契約で継続課金を構築する

> 銀行が承認する PayTo のマンデートを設定し、サブスクリプション、分割払い、利用量に基づく請求で継続的な決済を回収します。

## 構築するもの

PayTo では、顧客が自身のバンキングアプリで一度承認するだけのデジタルな銀行承認型マンデート（「決済契約」）を設定できます。その後は、設定したスケジュールに沿って Hello Clever が自動的に資金を回収します（サブスクリプション、分割払い、住宅ローン、利用量に基づく請求など）。毎回顧客に確認を求める必要はありません。

<Card title="決済契約" icon="file-signature">
  顧客が承認する継続的な授権です。誰が支払うか、どの方法か（PayID または BSB/口座番号）、1回あたりの上限、そして回収を駆動する頻度のパターンを定めます。
</Card>

<Info>
  これは **AUD 専用 (v1)** の機能です。以下のエンドポイントは AUD Payment API を使用します。
</Info>

## 事前準備

* 加盟店アカウントと `app-id` / `secret-key`（Merchant Portal から取得）。
* サンドボックスのエンドポイント `https://api.cleverhub.co`、本番環境 `https://api-merchant.helloclever.co`。
* ステータスの変更を受け取る Webhook のエンドポイント（TLS 1.2、公開アクセス可能、商用発行の証明書）。

## 契約の種類と頻度

契約を作成する際に `payment_agreement_type`（例：`MORTGAGE`）と、次の4つの形のいずれかである `agreement_details` のブロックを設定します。

| 種類              | 挙動                                                                             | 適した用途                      |
| --------------- | ------------------------------------------------------------------------------ | -------------------------- |
| **Variable**    | 周期ごとに金額が変わり得る継続的な引き落としです。`start_date` と `frequency`（例：`ADHOC` または固定の周期）を設定します。 | 金額が変動するサブスクリプション、利用量に基づく請求 |
| **Fixed**       | 毎回同じ金額です。`limit_amount` は請求する予定の正確な金額と一致させる必要があります。                            | 定額のサブスクリプション               |
| **Usage-based** | 計測された利用量に連動した引き落としです。                                                          | 従量制のサービス                   |
| **Balloon**     | 最後の支払いが大きい分割払い形式です。                                                            | 分割の資金計画                    |

<Tip>
  `limit_amount` は個々の回収の上限を定めます。Variable や Usage-based の契約では、想定される最大の請求額を賄える値を選んでください。
</Tip>

## 契約を設定して請求を始める

<Steps>
  <Step title="決済契約を作成する">
    一意の `client_transaction_id`、`limit_amount`、`description`（5〜140 文字）、`agreement_details`、`payer_details`、そして `payment_agreement_notification`（Webhook の認証ヘッダー）を指定して **create-payment-agreement** を呼び出します。payer details には、`bank_account_details`（BSB と口座番号）または `pay_id_details`（`pay_id` と `pay_id_type`。例：`EMAIL`）のいずれかを指定します。

    ```json Create agreement request theme={null}
    {
      "client_transaction_id": "30597959-a853-44d4-bdab-54332bf7a98e",
      "limit_amount": 1000,
      "description": "Monthly subscription",
      "external_id": "sub_343",
      "payment_agreement_type": "MORTGAGE",
      "agreement_details": {
        "variable_agreement_details_obj": {
          "start_date": "01/01/22",
          "frequency": "MONTHLY"
        }
      },
      "payer_details": {
        "name": "Jane Doe",
        "pay_id_details": { "pay_id": "customer@example.com", "pay_id_type": "EMAIL" }
      },
      "payment_agreement_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payto",
        "authorization_header": "SECRET"
      }
    }
    ```

    レスポンスでは Hello Clever の `id` と `payment_agreement_id` が返され、初期の `status` は `created` になります。
  </Step>

  <Step title="顧客の承認を待つ">
    顧客はバンキングアプリでマンデートを承認します。契約のステータスが変わると、Hello Clever が Webhook を呼び出します。請求は `active` の契約に対してのみ行ってください。

    | ステータス       | 意味                 |
    | ----------- | ------------------ |
    | `created`   | 作成が開始され、承認を待っている状態 |
    | `active`    | 承認済みで、請求が可能な状態     |
    | `suspended` | 一時的に停止されている状態      |
    | `cancelled` | 恒久的に終了した状態         |
    | `failed`    | 作成が失敗した状態          |
  </Step>

  <Step title="スケジュールに沿って請求させる">
    別途「引き落とし」や「請求」の呼び出しを行う必要はありません。契約が `active` のステータスに達すると、`agreement_details` で設定した `frequency`（例：`MONTHLY`、`WEEKLY`、`FORTNIGHTLY`）が自動的に回収を駆動します。Hello Clever が周期ごとに `limit_amount` の範囲内で決済を引き落とし、各回収のステータスが変わるたびに `payment_agreement_notification` の Webhook へ通知します。

    **Fixed** の契約では、`limit_amount` を毎周期に請求する予定の正確な金額に設定してください。**Variable** や **Usage-based** の契約で周期ごとに金額が変わる場合、または固定の周期の外で単発や `ADHOC` の請求を行う場合は、周期ごとの金額をどう送信するかを Hello Clever の連携担当者にご確認ください。この点は公開されている API リファレンスではまだ扱われていません。

    回収の消込には、専用の決済や開始の記録ではなく、**Get payment agreement detail** (`/v1/pay_to/payment_agreement/detail`) または **Get payment agreements** (`/v1/pay_to/payment_agreement/search`) を使ってください。
  </Step>

  <Step title="契約をライフサイクル全体で管理する">
    * **Amend** (`amend-payment-agreement`)：プランが変わったときに `limit_amount` や `agreement_details`（頻度など）を変更します。Hello Clever の `id`、新しい `limit_amount`、`agreement_details` のブロック全体、そして `payment_agreement_notification` が必要です。1つの項目のみを変更する場合でも、これら4つはすべての呼び出しで必須です。
    * **Change status** (`change-status`)：`status` を `active`、`suspended`、`cancelled` に設定します。異議申立ての間に一時停止したり、解約時に取り消したりできます。
    * **Get detail** / **Get list**：契約の状態を消込します。期間で絞り込み、ページ分割にも対応しています。
  </Step>
</Steps>

## サンドボックスのテスト用 PayID

サンドボックスで特定の契約の状態を発生させるには、次の支払人の PayID を使ってください。

| PayID                           | 結果のステータス      |
| ------------------------------- | ------------- |
| `no-action@example.com`         | `created` のまま |
| `error@example.com`             | `failed`      |
| `cancel-agreement@example.com`  | `cancelled`   |
| `suspend-agreement@example.com` | `suspended`   |

## Webhook の取り扱い

<Warning>
  Webhook は冪等に実装してください。Hello Clever は同じペイロードを複数回配信することがあり、毎回 `200 OK` を期待します。200 以外のレスポンスは 15 分間隔で3回リトライされます。検証を強化するため、契約ごとに異なる `authorization_header` を使ってください。
</Warning>


## Related topics

- [Hello Clever 開発者ドキュメント](/ja/index.md)
- [Hello Clever を始める](/ja/getting-started/overview.md)
- [継続的な決済向けの PayTo](/ja/platform-overview/payment-concepts/payto-recurring.md)