UnivaPay Java SDK

UnivaPay Java SDK は、UnivaPay API と通信するためのメソッドとモデルを提供します。

インストール

UnivaPay Java SDK を利用するには、pom ファイルに次の依存関係を追加します。

<dependency>
    <groupId>com.univapay</groupId>
    <artifactId>univapay-java-sdk</artifactId>
    <version>0.2.31</version>
</dependency>

使用方法

アプリケーション Json Web トークン（appJWT）とシークレットを取得し、次のように認証方法を定義します。

AppJWTStrategy authStrategy = new AppJWTStrategy(appJWT, appJWTSecret);

エンドポイント(endpoint)やリクエストごとのタイムアウト(timeout)が有効かについて定義することもできます。

UnivapaySettings settings =  new UnivapaySettings()
                    .withEndpoint(endpoint)
                    .withTimeoutSeconds(timeout)
                    .attachOrigin(MY_ORIGIN_URI);

すべてのフィールドは次のデフォルト値を持ちます。

Endpoint: 環境変数UNIVAPAY_ENDPOINTの値、または定義されていない場合はhttps://api.univapay.com
Timeout: 900 秒
Origin: 設定された場合は SDK のインスタンスからの全てのリクエストにOrigin [引数の値]というヘッダーが追加される。デフォルト設定ではOriginヘッダーが追加されない。

SDK のインスタンスを作成するには、static なメソッド createを以下のように使用します。

UnivapaySDK univapay = UnivapaySDK.create(authStrategy, settings);

作成されたインスタンスでは、API との通信に使用できるすべてのメソッドにアクセスできます。

また、 copyメソッドも用意されています。これにより、異なる認証情報、設定、またはその両方を使用して新しいインスタンスを作成することができます。

たとえば、次のように異なる資格情報を使用して単一の要求を行うことができます。

univapay.copy(newAuthStrategy).listCharges();

これは、元の univapayインスタンスの認証戦略と設定を変更しません。

リクエストビルダー

すべてのリクエストメソッドはリクエストビルダーを返します。これにより、任意のパラメータを自由に設定できます。

// ビルダーをインスタンス化
CreateRefundRequestBuilder refundCreationBuilder = univapay.createRefund(storeId, chargeId, BigInteger.valueOf(15), "JPY", RefundReason.CUSTOMER_REQUEST);

// 任意のパラメータを追加
RetrofitRequestCaller<Refund> request = refundCreationBuilder
            .withMetadata(metadata)
            .withMessage("reservation cancelled")
            .build()

// いつでも同期的に通信可能...
Refund refund = request.dispatch();

// または非同期的に通信可能
request.dispatch(new UnivapayCallback<Refund>() {
            @Override
            public void getResponse(Refund response) {
                logger.log(Level.INFO, "It succeeded!");
            }

            @Override
            public void getFailure(Throwable error) {
                logger.log(Level.SEVERE, "oh no!");
            }
        });

課金（Charge）する

まず、アプリケーショントークンとシークレットを入手します。用途に応じてTESTモードまたはLIVEモードでトークンを使用してください。

SDK インスタンスを取得し、トランザクショントークンを作成します。たとえば、クレジットカードを使用するワンタイムトランザクショントークンの場合は、次のようになります。

CreditCard creditCard = new CreditCard(cardHolder, cardNumber, expMonth, expYear, cvv)
                        .addAddress(country, state, city, line1, line2, postalCode);

TransactionTokenWithData transactionToken = univapay.createTransactionToken(email, creditCard, TransactionTokenType.ONE_TIME)
                                             .build()
                                             .dispatch();

その後、決済を行います。

Charge charge = univapay.createCharge(transactionToken.getId(), chargedAmount, requestedCurrency)
                     .withMetadata(metadata)
                     .withIdempotencyKey(idempotencyKey)
                     .build()
                     .dispatch();

withIdempotencyKey（idempotencyKey）メソッドは、idempotency（冪等）キーをリクエストに付加します。すべての非認証 POST メソッドと PATCH メソッドは、要求に idempotency キーを添付できます。

Charge（課金情報）と、 UnivapayResponseのすべてのインスタンスにおいて、getIdempotencyStatus（）メソッドを使ってリクエストが冪等であるかを確認することができます。

Charge の初期ステータスは「未確定（PENDING）」です。Charge の処理が完了するまで待ち、成功したかどうかに応じて対処することができます。この場合、以下のようにResourceMonitorを使用することで、最後のステータスを取得して返すまで、Charge のステータスをスマートにポーリングすることができます。

Charge polledCharge = univapay.chargeCompletionMonitor(charge.getStoreId(), charge.getId()).await()

キャプチャと認証

デフォルトでは、 createChargeメソッドは支払いまで処理を進めます（capture)。そうではなく、支払処理に権限を付与する必要がある場合は、キャプチャするかどうかを示す第 4 引数を渡します。たとえば、 univapay.createCharge（transactionToken.getId（）, chargedAmount, requestedCurrency, false）とした場合は、請求を許可するだけです。

これを取得するには、対応する StoreIdとChargeIdを渡して captureAuthorizedChargeメソッドを使用できます。

キャンセル

承認された請求は、以下の方法でキャンセルすることができます。

univapay.createCancel(storeId, authorizedCharge.getId())
     .withMetadata(metadata)
     .build()
     .dispatch

課金（Charge）のバッチ作成

SDK は、API の制限を超過することなく大量の料金を作成するためのユーティリティメソッドを提供し、そのような例外を処理する苦労を軽減します。

まず、バッチ用インスタンスを作成します。

BatchCreateCharge batchCharger = univapay.batchCreateCharge();

次に、作成しようとしている課金に必要なトランザクショントークンを取得し、それぞれに対してCreateChargeBuilderを追加します。

for (TransactionToken transactionToken: transactionTokens) {
    batchCharger.add(univapay.createCharge(transactionToken.getId(), amount, currency));
}

最後に、バッチ作成を実行します。このとき、作成された Charge の配列が返されます。このメカニズムは Charge のステータスをポーリングします。

CreateChargeResult[] chargeResults = batchCharger.execute();

すべての課金は、バッチ処理の際に冪等に作成されます。

改ページ用リストと反復処理

UnivaPay Java SDK には、結果リストを反復処理するメソッドも用意されています。

たとえば、いくつかの検索条件を満たすマーチャントの課金一覧が必要な場合は、次のようにします。

ListChargesRequestBuilder builder = payments.listCharges()
                                            .withCardChargeSearch(cardChargeSearch)
                                            .setLimit(15)
                                            .setCursorDirection(CursorDirection.DESC)
                                            .setCursor(new ChargeId("8486dc98-9836-41dd-b598-bbf49d5bc862"));

limitは 1 ページあたりの最大項目数を設定します。 cursor directionは、降順または昇順でソートされた項目を返すように API に指示します。cursorは指定された ID から結果を返すように API に要求します。

これにより、改ページ用のリクエストビルダーが返されます。それをbuild()、dispatch()することで、 PaginatedList <Charge>が返されます。

このリストの結果を使用して、次のレスポンスをナビゲートすることができます。しかしこの場合、TOO_MANY_REQUESTSエラーを自分で処理する必要があります。

より良い方法は、PaginatedListを Java のIterableにすることです。

PaginatedListIterable<Charge> chargesIterable = builder.asIterable();

for(List<Charge> charges: chargesIterable){
    doSomething(charges);
}

基礎となるイテレータは、API のリクエスト制限を考慮し、バックオフメカニズムを使用して失敗したリクエストを再試行します。 asIterableメソッドは、timeoutと backoffアルゴリズムをカスタマイズする方法を提供します。より詳細については、JavaDoc を参照してください。

その他

UnivaPay API の詳細については、JavadocまたはAPI リファレンスを参照してください。

univapay / univapay-java-sdk

readme