> For the complete documentation index, see [llms.txt](https://docs.payments.thalescloud.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/ja/implement-nfc-wallet/make-payment/replenish-payment-keys.md).

# 支払いキーを補充する

## 概要

支払いキー（SUK または LUK）は、非接触決済用の EMV クリプトグラムを計算するために必要です。

HCE（Host Card Emulation）モデルでは、支払いキーは一時的です。使い切る前に補充してください。これにより決済の中断を防げます。

このガイドでは、補充のタイミングとトリガー方法を説明します。

{% hint style="info" %}
NFC Wallet SDK は次の支払いキータイプをサポートします:

* **SUK（単回使用キー）**: 1取引につき1つのキーを使用します。Mastercard と PURE（ホワイトラベル EMV）で使用されます。
* **LUK（限定使用キー）**: 複数取引に1つのキーを使用します。Visa で使用されます。
  {% endhint %}

## 前提条件

### 補充しきい値の設定（オンボーディング）

オンボーディング中に、次を使用して補充しきい値を設定します: **Thales デリバリーチーム**.

{% hint style="info" %}
しきい値を定義する際は、次を考慮してください:

* **SUK**: 補充をトリガーする残り SUK 数。
* **LUK**: 残り取引回数と LUK の有効期限。
  {% endhint %}

## SDK の統合

### 補充が必要なタイミングを検出する

次の信号のいずれか（または両方）を使用します:

* **事前チェック**: デジタルカードの状態を読み取ります。
* **反応型プッシュ（TSP トリガー）**: 処理する `MG:ReplenishmentNeededNotification` 〜からの **TSP**.

プッシュ配信とルーティングについては、次を参照してください: [プッシュ通知の処理](/nfc-wallet-sdk-android/ja/get-started/configuration/5.-push-notifications/handle-push-notifications.md).

#### 事前チェック

このチェックは各デジタルカードに対して実行します。アプリ起動時または決済後に実行してください。

1. 取得 `DigitalizedCardStatus` から `DigitalizedCard`.
2. 呼び出します `DigitalizedCardStatus.needsReplenishment()`.

参照 [デジタルカードを表示する](/nfc-wallet-sdk-android/ja/implement-nfc-wallet/manage-digital-cards/display-digital-cards.md).

{% code title="デジタルカードに補充が必要か確認する" %}

```java
public static boolean needsReplenishment(final DigitalizedCard card) {
    AsyncResult<DigitalizedCardStatus> result =
            card.getCardState(null).waitToComplete();

    if (!result.isSuccessful()) {
        // TODO: エラー処理
        return false;
    }

    DigitalizedCardStatus status = result.getResult();
    return status != null && status.needsReplenishment();
}
```

{% endcode %}

この事前チェックは次の場合に実行します:

* 通常のアプリケーション起動時
  * アプリケーションが決済のために起動した場合はチェックを実行しないでください。下の警告を参照してください
* 決済後
  * イベント時 `onNextTransactionReady` - 参照: [非接触決済コールバックを実装する](/nfc-wallet-sdk-android/ja/implement-nfc-wallet/make-payment/implement-contactless-payments/2.-implement-contactless-payment-callbacks.md).
* カードがデフォルトに設定されたとき。
* 接続が回復した後（オフライン → オンライン）。

{% hint style="warning" %}
このチェックはアプリケーションの起動時、および次の後に実行してください: **NFC Wallet SDK** の初期化。

エンドユーザーが非接触決済のためにアプリケーションを起動した場合は、このチェックを実行しないでください。決済の実行が遅れる可能性があります。
{% endhint %}

### 補充をトリガーする

呼び出します `ProvisioningBusinessService.sendRequestForReplenishment(...)` 新しい支払いキーを要求します。

1. カード識別子を取得します。

   次を使用します: **トークン化カード ID** - 参照: [デジタルカードを表示する](/nfc-wallet-sdk-android/ja/implement-nfc-wallet/manage-digital-cards/display-digital-cards.md#tokenized-card-id-versus-digital-card-id).
2. 補充リクエストを送信します。

   呼び出します `sendRequestForReplenishment(...)` および実装します `PushServiceListener`:

   * `onComplete`: リクエストは受け付けられました。
   * `onError`: SDK はリクエストを送信できません。確認してください `ProvisioningServiceError`.

   <pre class="language-java" data-title="補充リクエストを送信する"><code class="lang-java">public void replenish(final String tokenizedCardId, final boolean forced) {
       ProvisioningBusinessService service =
               ProvisioningServiceManager.getProvisioningBusinessService();

       service.sendRequestForReplenishment(
               tokenizedCardId,
               new ReplenishmentListener(),
               forced
       );
   }

   private static class ReplenishmentListener implements PushServiceListener {
       @Override
       public void onComplete() {
           // TODO: 成功をログに記録
       }

       @Override
       public void onError(final ProvisioningServiceError error) {
           // TODO: エラーをログに記録
       }

       @Override
       public void onUnsupportedPushContent(final Bundle bundle) {
           // この呼び出しでは使用されません。
       }

       @Override
       public void onServerMessage(final String tokenizedCardId,
                                   final ProvisioningServiceMessage message) {
           // この呼び出しでは使用されません。
       }
   }
   </code></pre>
3. 補充プッシュを処理します。

   リクエストを送信すると、NFC Wallet バックエンドからプッシュ通知が送信されます。あなたの **デジタルウォレットアプリケーション** はそれを処理する必要があります。その後、SDK が新しい支払いキーを取得します。

{% hint style="info" %}
〜を終了しないでください **デジタルウォレットアプリケーション** 補充処理が進行中の間は。
{% endhint %}

{% hint style="info" %}
**TSP トリガーによる補充**

受信したら `MG:ReplenishmentNeededNotification`、次を使用して補充をトリガーします: `forced = true`.

参照 [MG 通知（補充）を処理する](/nfc-wallet-sdk-android/ja/get-started/configuration/5.-push-notifications/handle-push-notifications.md#process-mg-notifications-replenishment).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.payments.thalescloud.io/nfc-wallet-sdk-android/ja/implement-nfc-wallet/make-payment/replenish-payment-keys.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.