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

# AUD PayID で即時決済を受け付ける

> ワンタイム PayID と固定 PayID を使って NPP 上でリアルタイムの銀行決済を回収し、精算時に即時の Webhook を受け取ります。

## 構築するもの

PayID 決済では、顧客が自身のバンキングアプリから New Payments Platform (NPP) 経由でリアルタイムに支払えます。決済リクエストを作成し、支払先の PayID を顧客に渡すと、資金が届いた瞬間に Hello Clever が通知します。カードもチャージバックもなく、精算はほぼ即時です。

2つのパターンを利用できます。

<CardGroup cols={2}>
  <Card title="ワンタイム PayID" icon="receipt">
    取引ごとに新しい PayID を発行します。チェックアウトの注文などが該当します。
  </Card>

  <Card title="固定オープン PayID" icon="infinity">
    顧客に紐づく永続的な PayID で、複数回または任意の金額の決済を受け付けます。継続的なトップアップ用のアドレスやウォレットの参照先などが該当します。
  </Card>
</CardGroup>

<Info>
  これは **AUD 専用 (v1)** の機能です。
</Info>

## 事前準備

* 加盟店アカウントと `app-id` / `secret-key`。
* サンドボックス `https://api.cleverhub.co`、本番環境 `https://api-merchant.helloclever.co`。
* 決済ステータスのコールバックを受ける Webhook のエンドポイント（TLS 1.2、公開、商用証明書）。

## パターン A：単発の決済リクエスト

<Steps>
  <Step title="決済リクエストを作成する">
    **create-payment-request** を呼び出します。必須項目は `name`、`gst`（ブール値。GST を課すオーストラリアの加盟店のみ `true`）、`amount`、`description`、`emails`（カンマ区切り、**小文字のみ**）、そして `payment_request_notification` の Webhook のブロック（`endpoint_url` と `authorization_header`）です。取引のステータスが変わるたびに、Hello Clever がこのエンドポイントを呼び出します。有用な任意項目は `expired_at`（UTC、15 分以上先）、`external_id`、`metadata`（任意のカスタムのキーバリューのオブジェクト。取引にそのまま返されます）です。`prefix_static_payid` は引き続き受け付けられますが、現在は**非推奨**です。新規の連携では指定しないでください。

    ```json Create payment request theme={null}
    {
      "name": "Luyx",
      "gst": true,
      "amount": 1000,
      "description": "Order 4821",
      "emails": "customer@gmail.com",
      "expired_at": "2026-01-31T06:00:00.000+0000",
      "external_id": "order_4821",
      "payment_request_notification": {
        "endpoint_url": "https://yoursite.com/webhooks/payid",
        "authorization_header": "SECRET"
      },
      "metadata": {
        "custom_note": "Priority customer"
      }
    }
    ```

    レスポンスには、生成された `request_payid`（顧客が支払う先の PayID）、`total`（金額と GST の合計）、`expired_at`、`nonce`、そして `status: pending` が含まれます。
  </Step>

  <Step title="顧客に PayID を表示する">
    `request_payid` と正確な `total` を表示します。顧客はバンキングアプリを開いてその PayID へ支払い、送金が NPP 上で完了します。
  </Step>

  <Step title="通知を受け取る、またはステータスを取得する">
    資金が届くと、Hello Clever が更新されたペイロード（`status: received`、`paid_at`、`cashback_amount`、`sender_details`）を Webhook へ POST します。`id` と `payid` を指定して **Get payment request status** を呼び出すこともできます。
  </Step>
</Steps>

### 決済リクエストのステータス

| ステータス             | 意味                       |
| ----------------- | ------------------------ |
| `pending`         | 顧客がまだ支払っていません            |
| `received`        | 支払いが成功しました               |
| `expired`         | リクエストが失効しました             |
| `return_pending`  | 返金が開始されました               |
| `return_received` | 返金が支払人へ送金されました           |
| `return_expired`  | 返金のリクエストが失効しました（10 日で失効） |
| `return_rejected` | 送金先で返金が失敗しました。リトライはありません |

### 保留中のリクエストを取り消す

`{ "payid": "abc.xyz@example.co" }` を指定して **cancel-a-payid** を呼び出します。これにより PayID の登録が解除され、取引が `expired` として記録されます。

## パターン B：固定オープン PayID

顧客に対して、継続的に決済を受け付ける恒久的な PayID を提供する場合に使用します。

<Steps>
  <Step title="固定オープン PayID を作成する">
    **create-static-open-payid** を呼び出します。必須項目は `name`、`email`、`prefix_static_payid`（3〜35 文字、小文字・数字・ドット）、そして `customer_notification` の Webhook のブロック（`endpoint_url` と `authorization_header`）です。任意項目は `address`、`phone`、`city`、`zip_code`、`state`、`external_id` です。レスポンスでは、永続的な `static_payid` と `status: active` が返されます。

    生成されるアドレスは `prefix@example.com` の形式です。入金があるたびに、決済のペイロード（金額、`paid_at`、`sender_details`、キャッシュバック）とともに Webhook が発火します。
  </Step>

  <Step title="一覧を取得して照会する">
    **list-static-open-payids** を呼び出します。`email`、`payid`、`customer_id` で絞り込みができ、ページ分割にも対応しています。
  </Step>
</Steps>

## 照会と消込

* **期間内の決済リクエストの取得**：`from_date` / `to_date`（UTC、`YYYY-MM-DDThh:mm:ss` または `DD/MM/YY`）と `page`（1 ページ 20 件）を指定します。対象期間は最大1年です。
* **決済リクエストの統計の取得**：すべての決済リクエストの集計（総額、完了した取引件数、保留中の件数）を返します。
* `external_id` と返された `nonce` を使って、自社の記録と照合してください。

## 返金

**refund-a-payment** を呼び出します。`payment_request_id`、任意の `refund_amount`（既定では全額）、そして `reason`（5 文字以上）を指定します。返金用の PayID が生成されます。支払人へ返金できるよう、必要に応じて残高をトップアップしてください。進行状況は `return_pending` から `return_received` へと追跡できます。

<Warning>
  * メールアドレスは**小文字**でなければリクエストが拒否されます。
  * `expired_at` は **UTC** で、少なくとも 15 分先である必要があります。
  * `gst: true` は AUD において GST を課すオーストラリアの加盟店向けです。
  * すべての Webhook に対して `200 OK` を返し、重複した配信を冪等に処理してください。配信が失敗した場合、15 分間隔で3回リトライされます。リクエストごとに一意の `authorization_header` を使ってください。
</Warning>


## Related topics

- [Hello Clever 開発者ドキュメント](/ja/index.md)
- [JPY の A2A Payin を受け付ける](/ja/platform-overview/payment-concepts/jpy-payins.md)
- [Hello Clever を始める](/ja/getting-started/overview.md)