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

# キャッシュバックキャンペーンでロイヤルティを高める

> キャンペーンを設定し、ユーザーを登録し、対象となる決済にリアルタイムでキャッシュバックを届け、出金を管理します。

## 構築するもの

Hello Clever のキャッシュバックでは、対象となる決済に対してリアルタイムで顧客に現金を還元できます。キャンペーン（段階、実施時期、対象となる決済手段、上限）を設定し、ユーザーごとにキャッシュバックのアカウントを有効化し、取引時にキャッシュバックを届け、蓄積された残高を出金できるようにします。特典は対象となる取引に対して自動的に配布されます。銀行決済では即時、カード決済では精算時に行われます。

**Cashback API (v2)** は、キャンペーンの読み取り、ユーザーアカウントの管理、キャッシュバックの移動のためのエンドポイントを提供します。

## 事前準備

* 加盟店アカウントと `app-id` / `secret-key`。
* サンドボックス `https://api.cleverhub.co`、本番環境 `https://api-merchant.helloclever.co`。
* キャッシュバックの率とキャンペーンは Merchant Portal（マーチャントポータル）でも設定できます。

## エンドポイント

| エンドポイント                                                        | 目的                                                                                                     |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Get Cashback Campaign List** (`GET /v2/cashbacks/campaigns`) | キャンペーンのページ分割された一覧です。ステータス（`active`、`scheduled`、`inactive`）で絞り込めます。段階、実施時期、対象となる決済手段、キャッシュバックの上限額を含みます。 |
| **Get Campaign Configurations**                                | キャンペーンの詳細な設定です。                                                                                        |
| **Activate User's Cashback Account**                           | 顧客がキャッシュバックを獲得・保持できるようにします。                                                                            |
| **Initiate Cashback Delivery**                                 | 対象となるイベントに対して、ユーザーへキャッシュバックを支払います。                                                                     |
| **Initiate Cashback Withdrawal**                               | ユーザーの蓄積されたキャッシュバックを、そのアカウントへ出金します。                                                                     |
| **Get User List**                                              | キャッシュバックに登録されているユーザーの一覧です。                                                                             |

## ロイヤルティのフローを構築する

<Steps>
  <Step title="キャンペーンを設計する">
    コードを書く前に、キャンペーンの形を決めてください。

    * **段階**：例として、\$50 まで 2%、それを超えると 5%。
    * **実施時期**：期間と頻度（季節のプロモーション、日替わりのオファー、単日のイベント）。
    * **対象となる決済手段**：どのネットワークが対象になるか（銀行とカードではタイミングの挙動が異なります）。
    * **上限**：1取引あたり、またはキャンペーンあたりのキャッシュバックの上限。

    Merchant Portal でキャンペーンを作成・設定し、**Get Cashback Campaign List** または **Get Campaign Configurations** で読み戻して、UI と対象判定のロジックに反映してください。
  </Step>

  <Step title="顧客を登録する">
    ユーザーがキャッシュバックを受け取り保持できるよう、**Activate User's Cashback Account** を呼び出します。登録時、または最初の対象チェックアウト時に実行してください。登録の状態を確認して自社の記録と照合するには **Get User List** を使います。
  </Step>

  <Step title="対象となる取引でキャッシュバックを届ける">
    顧客が対象となる決済を完了したら、**Initiate Cashback Delivery** を呼び出してキャッシュバックを付与します。銀行決済やリアルタイム決済では直ちに付与でき、カード決済では元の決済が精算された時点でキャッシュバックが適用されます。

    <Tip>
      AUD Payment Gateway を使用している場合、個々の明細には `enable_cashback` のフラグがあり、決済のペイロードは `cashback_amount` を返します。チェックアウトで獲得したキャッシュバックはそこに反映されます。独立したアカウント、配布、出金のライフサイクルの管理には Cashback API を使ってください。
    </Tip>
  </Step>

  <Step title="顧客が出金できるようにする">
    **Initiate Cashback Withdrawal** を呼び出して、ユーザーの蓄積されたキャッシュバックを指定されたアカウントへ支払います。現在の残高と出金のステータスをアプリ上に表示してください。
  </Step>
</Steps>

## 設計上の考慮点

<AccordionGroup>
  <Accordion title="タイミングはネットワークによって異なります" icon="clock">
    カードのキャッシュバックは即時ではなく精算時に届くことを顧客に伝え、期待値を合わせてください。
  </Accordion>

  <Accordion title="上限と段階はサーバー側で守る" icon="shield-check">
    キャンペーンの設定を読み取り、クライアントを信頼するのではなく自社のバックエンドで対象判定を行ってください。
  </Accordion>

  <Accordion title="定期的に消込する" icon="rotate">
    一覧のエンドポイントを使って、自社の元帳を Hello Clever の記録と整合させてください。
  </Accordion>
</AccordionGroup>


## Related topics

- [Hello Clever を始める](/ja/getting-started/overview.md)
- [Hello Clever 開発者ドキュメント](/ja/index.md)
- [キャッシュバックキャンペーンの作成と管理](/ja/portal/cashback-campaigns.md)