elepay Android SDK は elepay を Android アプリに導入するための SDK です。
このガイドでは、 elepay の SDK を Android アプリと連携する方法について詳しく説明します。

対応バージョン

elepay Android SDK のバージョン 2.9.0 までは Android API 21 をサポートしていましたが、2.10.0 以降の minSdkVersion は 23 になります。

インストール方法

gradle によるインストール

下記のコードを build.gradle の repositories ブロックに追加してください。

maven {
   ... // 他のコード
   url "https://elestyle.github.io/elepay-android/repository"
}

同 build.gradle ファイルの dependency に以下のコードを追加してください。
(latest-version)はリリースページをご参照ください

//ご注意：(latest-version)は https://github.com/elestyle/elepay-android/releases をご参照ください

implementation 'jp.elestyle.androidapp:elepay:(latest-version)'

🚧 常に新しいバージョンを使用することを推奨します。

gradle build tool 3.6.0 (Android Studio 3.6 に対応)以降を利用する場合、elepay Android SDK 1.7.0 以降が必要となります。

🚧 Android Support Library ご利用の方へ

elepay Android SDK は Android X のみ対応しています。 Google 社は 2018 年以降 Android support library の開発を停止しますので、 Android support library をご利用する場合は、Android X に変更するのはお勧めです。

変更手順に関して、Google 社のマイグレーション手順をご参照ください。

実装

1. Android システム権限

UnionPay や Alipay を利用するには、以下のパーミッションを AndroidManifest.xml に追加する必要があります。

📘 全てのパーミッションではなく、利用状況に応じて追加してください。例：カードをスキャンする仕様がなければ、カメラに関するパーミッションは不要です。

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<uses-feature android:name="android.hardware.camera"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.hardware.camera.autofocus"/>

<uses-permission android:name="org.simalliance.openmobileapi.SMARTCARD" />

<uses-permission android:name="android.permission.NFC" />
<uses-feature android:name="android.hardware.nfc.hce"/>

2. セットアップ

支払いの処理を行う前に、 elepay SDK をセットアップします。

val configuration = ElepayConfiguration(
  apiKey = "" // test key or live key
)
Elepay.setup(configuration)

appKey を申請するためには、elepay アカウントが必要となります。

📘 本配置処理はアプリの Application クラスまたはスタート Activity で行われるのが推薦します。

3. 支払いの処理

チャージ処理

チャージのデータオブジェクトは作成された後、下記のメソッドに渡されて、支払い処理を完了させます。
Elepay.processPayment(chargeJsonData, fromActivity, resultHandler)

パラメータ名	説明
chargeJsonData	ペイメントデータが含まれた JSON オブジェクトとなります。サーバー側により作成され、elepay Android SDK はこのデータで決済処理を行います。
fromActivity	決済を行う際に UI を表示するために使われた `Activity` の実例となります。
resultHandler	決済の結果を通知するコールバックです。

ソース処理

ソースのデータオブジェクトは作成された後、下記のメソッドに渡されて、支払い処理を完了させます。
Elepay.processSource(sourceJsonData, fromActivity, resultHandler)

パラメータ名	説明
sourceJsonData	ソースデータが含まれた JSON オブジェクトとなります。サーバー側により作成され、elepay Android SDK はこのデータで決済処理を行います。
fromActivity	決済を行う際に UI を表示するために使われた `Activity` の実例となります。
resultHandler	決済の結果を通知するコールバックです。

checkout 処理

📘 checkout は elepay Android SDK 1.9.0 及びその以上のバージョンが必要となります。

checkout のデータオブジェクトは作成された後、下記のメソッドに渡されて、支払い処理を完了させます。
Elepay.checkout(checkoutJsonData, fromActivity, resultHandler)

パラメータ名	説明
checkoutJsonData	checkout データが含まれた JSON オブジェクトとなります。サーバー側により作成され、elepay Android SDK はこのデータで決済処理を行います。
fromActivity	決済を行う際に UI を表示するために使われた `Activity` の実例となります。
resultHandler	決済の結果を通知するコールバックです。

📘 引数の詳細は API ドキュメントをご参照ください。

4. 結果の処理

elepay Android SDK 1.8.0 以降、AndroidManifest.xmlファイルに指定するコールバック Activity は、下記のようにひとつにまとめることが可能になります。また、1.7.1 までの支払い方法ごとの設定方法はサポート停止になりますので、1.8.0 以降のバージョンをご利用の際にElepayCallbackActivityをご使用ください。

<activity
    android:name="jp.elestyle.androidapp.elepay.activity.ElepayCallbackActivity"
    android:launchMode="singleTask"
    android:exported="true">
    <intent-filter>
        <data android:scheme="ep1234567890abcdef" /> <!-- * 必ずお忘れずに！このschemeはelepayの「アプリ設定」ページより取得してください。 -->

        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
    </intent-filter>
</activity>

🚧 必ずお忘れずに

上記コードの中、<data android:scheme="ep1234567890abcdef" />のschemeは elepay 専用 URL Scheme に書き換えてください。取得方法は「iOS / Android SDK 用 URL Scheme の取得」までご参照ください。

処理の結果は、上記の resultHandler コールバックの引数 ElepayResult に含まれます。 ElepayResult は Succeeded 、Failed と Canceled に別れますが、詳細は API のドキュメントをご参照ください。

// 処理例：
Elepay.processPayment(chargeData = result.jsonObject, fromActivity = activity) { paymentRes ->
    when (paymentRes) {
        is ElepayResult.Succeeded -> print("Payment is processed successfully. id=${payResult.paymentId}")
        is ElepayResult.Failed -> print("Payment error: ${payResult.error}")
        is ElepayResult.Canceled -> print("Payment is cancelled. id=${payResult.paymentId}")
    }
}

エラー処理について

elepay Android SDK から戻されたエラーには、エンドユーザとして処理すべきのものが含まれます。エラータイプとエラーコードをチェックし、ユーザに適切な案内を提供することを推奨します。例：

when (paymentRes) {
    is ElepayResult.Succeeded -> {
        // succeeded
    }
    is ElepayResult.Failed -> {
        when (paymentRes.error) {
            is ElepayError.PaymentFailure -> {
                if ((paymentRes.error as ElepayError.PaymentFailure).errorCode == "10110") {
                    Log.d("Payment", "app not installed.")
                }
            }

            is ElepayError.PermissionRequired -> {
                Log.d("Payment", "Please grand the following permissions to complete payment. ${(paymentRes.error as ElepayError.PermissionRequired).permissions}")
            }

            else -> {
                // Other error processing.
            }
        }
    }
    is ElepayResult.Canceled -> {
        // canceled
    }
}

UI カスタマイズ

UI のテーマ指定

elepay SDK はシステムのテーマに応じて UI を表示します。
ElepayThemeで定義したLightとDarkを利用し、UI のテーマを指定することができます。
指定する方法は下記となります。

elepay SDK を初期化する時に、ElepayConfiguration のelepayThemeを指定します。

val configuration = ElepayConfiguration(
apiKey = "", // test key or live key
elepayTheme = ElepayTheme.Light // または ElepayTheme.Dark
)
Elepay.setup(configuration)

Elepay.changeThemeを利用し、UI のテーマを指定します。

Elepay.changeTheme(theme = ElepayTheme.Light)

注意

elepay のテーマを指定すると、システムよりアプリの Configuation データは変更されるため、 elepay の支払い処理を呼び出す Activity は再起動される場合があります。 Activity 再起動を回避するには、AndroidManifest.xmlに elepay の支払い処理を呼び出す Activity のandroid:configChangesにuiModeを追加する必要があります。

changeThemeは支払い処理の前にコールするのみ有効です。

色のカスタマイズ

elepay SDK UI の色は個別にカスタマイズすることができます。

システムバーのカスとマイズ

colors.xmlにて下記の色を変更できます。

elepayColorPrimaryDark: Activity テーマcolorPrimaryDarkのオーバーライド。主にステータスバーの背景色。
elepayNavigationBarBackground: Activity テーマnavigationBarColorのオーバーライド。下のナビゲーションバーの背景色

その他、res/valuesフォルダに bool 値を格納できる任意のファイルに（例：bools.xml）下記の設定も変更できます。

elepayWindowLightStatusBar: android:windowLightStatusBarと同じ機能。API 23 以上に使えます。
elepayWindowLightNavigationBar: android:windowLightNavigationBarと同じ機能。API 27 以上に使えます。

SDK 内の UI のカスとマイズ

elepayTopBarBackground：Toolbar の背景色。
elepayTopBarContent：Toolbar の文字色とアイコン色。
elepayBackgroundNormal：画面の背景色。
elepayCreditCardBackground：クレジットカード入力画面のカードウェジットの背景色。
elepayControlHighlight：ハイライトになる UI 部品の色。
elepayControlNormal：UI 部品の色。
elepayTextColorPrimary：メインテキストの色。
elepayTextSecondary：サブテキストの色。
elepayTextOnControlHighlight：ハイライトになる UI 部品に表示されるテキストの色。
elepayTextColorHint：ヒントテキストの色。
elepayErrorTextColorOnNormalBackground：エラーテキストの色。
elepayColorDivider：区切り線となる UI 部品の色。

3000

注意 Lightテーマの色をカスタマイズする場合は、プロジェクトのres/values/colors.xmlに上記の値を指定します。 Darkテーマの色をカスタマイズする場合は、プロジェクトのres/values-night/colors.xmlに上記の値を指定します。 ElepayTheme.Systemをご利用する場合、res/values/colors.xmlとres/values-night/colors.xml両方とも値を指定する可能性がありますので、実際の状況に応じてご使用ください。

多言語

elepay SDK は多言語をサポートしています。デフォルトで、elepay はシステムの言語を使います。他の言語を使う場合、LanguageKeyで定義している言語を下記のいずれ方法で変更できます。

elepay の初期化時に、ElepayConfigurationのlanguageKeyを設定します。

val configuration = ElepayConfiguration(
  apiKey = "", // test key or live key
  languageKey = LanguageKey.English
)
Elepay.setup(configuration)

Elepay.changeLanguageKeyを利用し、言語を変更します。

Elepay.changeLanguageKey(LangaugeKey.English)

🚧 注意

Elepay.changeLanguageKeyは、Elepay.processPaymentの前にコールすることでしか効きませんので、言語を変更するタイミングをご注意ください。

各支払方法の設定に関して

決済方法ページをご参考ください。

Android Quick Start