elepay 技術ドキュメント

elepayはモバイルに特化したマルチ決済プラットフォームです。複数の決済を一本化し、一度の開発でメジャーのモバイル決済方法を対応できます。elepay SDKはClient SDKとServer SDKを含めています。Client SDKはiOS, AndroidとHTML 5を対応しています。

ガイド    APIリファレンス

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

対応バージョン

  • elepay iOS SDK は、iOS 10.0 以降と互換性があります。
  • 開発環境:Xcode 11.0 以降をご使用ください。

インストール方法

1. Cocoapod によるインストール

  1. Podfile に ElepaySDK を追加します。
    ご注意:Cocoapods 1.10.0 以降をご利用ください。
# バージョンが2.2未満のElepaySDKはdynamic frameworks形式のみ対応しています
# 2.3からのstatic frameworks形式の導入も対応しました
#use_frameworks!

# From 2.0.0, the SDK renamed from ElePay to ElepaySDK

pod 'ElepaySDK', '~> 2.0'
  1. 中国のペイメント(Alipay, WeChat Pay, Union Pay)を利用する場合のみ、Elepay_ChinesePayments_Plugin も追加します。
# From 2.0.0, the SDK renamed from ElePay-ChinesePayments-Plugin to Elepay_ChinesePayments_Plugin

pod 'Elepay_ChinesePayments_Plugin', '~> 2.0'
  1. PayPal を利用する、かつ elepay SDK が 1.7.0 以上の場合のみ、Braintreeを追加してください。
pod 'Braintree'
  1. pod install を実行します。

2. 手動インストール

7ステップで、 elepay SDK for iOS をアプリに導入できます。

  1. Github.comElePaySDK.zip をダウンロードして解凍します。

  2. ElePay.framework を Xcode のプロジェクトに追加します。必要に応じて「Copy items if needed」をチェックしてください。

  3. ターゲット設定に、ElePay.framework を「Embedded Binaries」に追加します。

3. Objective-C プロジェクトで利用する場合

📘

Objective-Cで開発する場合

Objective-C のプロジェクトに elepay を実装する場合、こちらの
ElePayObjCBridge.swift ファイルをご利用ください。

実装

1. URL Scheme の追加

Xcode で、PROJECTTARGETS 項目> Info タグにある URL Types を開いて、elepay 専用 URL Scheme を追加してください。

elepay共通の設定

elepay 専用の URL Scheme「elepay 管理画面」 > 開発設定 > アプリ設定にある URL Scheme 項目を確認してください。

URL Scheme のテスト

モバイル Safari や Chrome のアドレスバーに上記の URL Scheme(例:ep1a2b3c4d5e://)が正しく App を呼び出されるかどうかをテストできます。

📘

重要

複数の TARGETS が存在する場合、全てのターゲットの URL Type に、上記の URL Scheme を追加してください。

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

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

3. elepay の初期化

プロジェクトの application(_:didFinishLaunchingWithOptions:) 関数に、以下の初期化コードを追加します。

Elepay.initApp(key: "ELEPAY_APP_PUBLIC_KEY")

📘

Public Key について

ELEPAY_APP_PUBLIC_KEY「elepay 管理画面」で発行したものに変更してください

4. callback の設定

application(_:open:options:) -> Bool 関数に, 以下のコードを追加します。

func application(_ app: UIApplication, open url: URL, options: [UIApplicationOpenURLOptionsKey : Any] = [:]) -> Bool {
    // Let elepay Handle Result Callback from 3rd party payment Apps first.
    if (Elepay.handleOpenURL(url)) {
        // When ELEPay has already handled the URL, make sure your code returns here.
        return true;
    }

    // for no payment URL handle it in your own code here.
    return false;
}

5. 支払い処理(都度決済)

お客様サーバー側処理

elepay API のチャージ API /api/charges で都度決済を開始します。
当 API は認証が必要なため、認証用のセキュリティーキーを契約者が管理しているサーバーに保存して、そのサーバーから請求してください。

❗️

セキュリティー:

安全のために、セキュリティーキーは絶対にアプリに保存したり、転送したりしないでください。

ネーティブApp側処理

elepay API のチャージ API から取得したペイロードを、以下のコードのように elepay SDK に送信して、elepay SDK からのコールバックに支払い完了(失敗)後の処理コードを追加します。

以下3つの中で使いやすいメソッドをご利用ください。

1. JSON String でチャージする場合:

_ = Elepay.handlePayment(
  chargeJSON: jsonString, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { result in
    switch (result) {
    case let .succeeded(paymentId):
        // your code for handling successful situation
    case let .canceled(paymentId):
        // your code for handling canceled by user
    case let .failed(paymentId, error):
        // your code for handling failure situation
    }
}

メソッド説明:
Handle response you've got from elepay's Charge API.

  • Parameters:

    • chargeJSON: The result of elepay's Charge API, a JSON formatted String is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

2. JSON Data でチャージする場合:

_ = Elepay.handlePayment(
  chargeData: jsonData, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { result in
    switch (result) {
    case let .succeeded(paymentId):
        // your code for handling successful situation
    case let .canceled(paymentId):
        // your code for handling canceled by user
    case let .failed(paymentId, error):
        // your code for handling failure situation
    }
}

メソッド説明:
Handle response you've got from elepay's Charge API.

  • Parameters:

    • chargeData: The result of elepay's Charge API, a JSON Data is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

3. JSON Dictionary でチャージする場合:

_ = Elepay.handlePayment(
  charge: jsonDictionary, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { result in
    switch (result) {
    case let .succeeded(paymentId):
        // your code for handling successful situation
    case let .canceled(paymentId):
        // your code for handling canceled by user
    case let .failed(paymentId, error):
        // your code for handling failure situation
    }
}

メソッド説明:
Handle response you've got from elepay's Charge API.

  • Parameters:
    • charge: The result of elepay's Charge API, a Dictionary is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

6. 支払い処理(定期払い・ウォレット決済)

お客様サーバー側処理

elepay API のソース API customers/<_customerId_>/sources でソース登録を開始します。
当 API は認証が必要なため、認証用のセキュリティーキーを契約者が管理しているサーバーに保存して、そのサーバーから請求してください。

ネーティブApp側処理

elepay API のソース API から取得したペイロードを、以下のコードのように elepay SDK に送信して、elepay SDK からのコールバックに支払い完了(失敗)後の処理コードを追加します。

以下3つの中で使いやすいメソッドをご利用ください。

1. JSON String でソースを取得した場合:

_ = Elepay.handleSource(
  sourceJSON: jsonString, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { (result) in
    switch (result) {
    case let .succeeded(sourceId):
        // your code for handling successful situation
    case let .canceled(sourceId):
        // your code for handling canceled by user
    case let .failed(sourceId, error):
        // your code for handling failure situation
    }
 }

メソッド説明:
Handle response you've got from elepay's Source API.

  • Parameters:
    • sourceJSON: The result of elepay's Source API, a JSON formatted String is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

2. JSON Data でソースを取得した場合:

_ = Elepay.handleSource(
  chargeData: jsonData, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { (result) in
    switch (result) {
    case let .succeeded(sourceId):
        // your code for handling successful situation
    case let .canceled(sourceId):
        // your code for handling canceled by user
    case let .failed(sourceId, error):
        // your code for handling failure situation
    }
 }

メソッド説明:
Handle response you've got from elepay's Source API.

  • Parameters:
    • sourceData: The result of elepay's Source API, a JSON Data is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

2. JSON Dictionary でソースを取得した場合:

_ = Elepay.handleSource(
  source: jsonDictionary, 
  cardParams: elepayCardParams, /* <- Optinal parameter, can be removed */
  viewController: viewController) { (result) in
    switch (result) {
    case let .succeeded(sourceId):
        // your code for handling successful situation
    case let .canceled(sourceId):
        // your code for handling canceled by user
    case let .failed(sourceId, error):
        // your code for handling failure situation
    }
 }

メソッド説明:
Handle response you've got from elepay's Source API.

  • Parameters:
    • source: The result of elepay's Source API, a Dictionary is required.
    • cardParams: Optional. Use cardParams for customized Credit Card input UI.
      You can pass nil to use the default Credit Card input UI.
    • viewController: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • completion: The block to execute after the payment is succeed, failed or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's document.
  • Returns: true if all input parameters are parsed correctlly.
    false if something wrong happened before acctually process the payment request.
    NOTE: completion block will always be called no matter what the return value is.

Checkout 機能

サーバー側処理

elepay API のコード API からチェックアウト用のペイロードを作成します。
詳細は API リファレンスをご参照ください。

ネーティブApp側処理

elepay API のコード API から取得したペイロードを、elepay SDK に送信し、elepay SDKよりcheckout 処理を完成させます。

ペイロードのタイプに合わせて3つのメソッドを提供します。
サンプルコードとメソッドの説明は下記です。

1. JSON String でチェックアウトする場合:

Elepay.checkout(
  checkoutJSONString: checkoutJSONString, 
  from: viewController
) { result in
   switch (result) {
   case .succeeded(let codeId):
     // checkout is succeeded.
   case .cancelled(let codeId):
     // checkout is canceled.
   case let .failed(let codeId, let error):
     // checkout is failed.
   }
}

メソッド説明:
Perform checkout.

  • Parameters:
    • checkoutJSONString: The result of elepay's Checkout API,
      a JSON formatted String is required.
    • from: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • resultHandler: The block to execute after the chekcout is succeed, failed
      or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's
      document.

2. JSON Data でチェックアウトする場合:

Elepay.checkout(
  checkoutJSONData: checkoutJSONData, 
  from: viewController
) { result in
   switch (result) {
   case .succeeded(let codeId):
     // checkout is succeeded.
   case .cancelled(let codeId):
     // checkout is canceled.
   case let .failed(let codeId, let error):
     // checkout is failed.
   }
}

メソッド説明:
Perform checkout.

  • Parameters:
    • checkoutJSONData: The result of elepay's Checkout API, a JSON Data is required.
    • from: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • resultHandler: The block to execute after the chekcout is succeed, failed
      or cancelled by user.
      This block takes the following parameter: result. For values, check ElepayResult's
      document.

3. JSON Dictionary でチェックアウトする場合:

Elepay.checkout(
  checkoutJSON: checkoutJSON, 
  from: viewController
) { result in
   switch (result) {
   case .succeeded(let codeId):
     // checkout is succeeded.
   case .cancelled(let codeId):
     // checkout is canceled.
   case let .failed(let codeId, let error):
     // checkout is failed.
   }
}

メソッド説明:
Perform checkout.

  • Parameters:
    • checkoutJSON: The result of elepay's Checkout API, a JSON Dictionary is required.
    • from: The UIViewController tell elepay SDK where to display further payment UI.
      You should always use a currentlly visible ViewController.
    • resultHandler: The block to execute after the chekcout is succeed, failed
      or cancelled by user.
      This block takes the following parameter: result. For values, please check out
      ElepayResult's document.

エラー処理

SDKが各種類のエラー(ElepayError)がコールバックします。

ユーザー体験がよくなるため、case unsupportedPaymentMethod(errorCode: String, paymentMethod: String)のエラー情報をユーザーに表示する事をお薦めします。

サンプルコード

switch (result) {
case .succeeded(let codeId):
    // checkout is succeeded.
case .cancelled(let codeId):
    // checkout is canceled.
case let .failed(let codeId, let error):
    switch error {
    case let .unsupportedPaymentMethod(errorCode, method):
        if errorCode == "10110" {   // 3rd party App not installed error
            print("The \(method) App is not installed for payment processing. Please install the app first or selected another payment method.")
        } if errorCode == "10100" {   // The device or the iOS system is too old to use this payment method
            print("Your device is too old to use \(method)")
        } else {    // Other error codes. Such as: a new payment method not supported by current SDK. The App using elepay SDK need to be updated
            print("Your App need to be updated to use \(method)")
        }
    default:
        // other error handling code
    }
}

エラーコード にエラーコードリストをご参照ください。

注意事項

🚧

支払い結果の処理について

アプリ内の支払い結果は、ユーザーへの結果照会のみでご使用ください。実際の課金結果は必ずサーバー上の callback API を経由し、elepay サーバーから送信されたデータでご確認ください。 詳しくは elepay API ガイドをご確認ください。

1. Apple Pay について

  1. Apple Pay を実装するときは、Xcode の PROJECTTARGETS にある Capabilities タグをクリックして、Apple Pay を「ON」に設定してください。
  1. Apple Pay の証明書を「elepay 管理画面」-「開発設定」-「Apple Pay」にアップロードしてください。
    証明書の作成方法はこちらのドキュメントでご参照ください。

2. LSApplicationQueriesSchemes(iOS 9 及び以降のシステム)について

各決済アプリに遷移するために、Xcode の PROJECTTARGETS にある Infoタグ(或いは Info.plist)で、LSApplicationQueriesSchemes Key を追加してください。

<key>LSApplicationQueriesSchemes</key>
    <array>
        <string>**各アプリのSchemeを追加してください**</string>
    </array>

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

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

多言語

elepay iOS SDK は多言語に対応しています(現状は English, Japanese, Simplified Chinese, Traditional Chinese に対応しています)。

SDK のデフォルトは iOS のシステム設定と一致した言語を表示します。

表示言語の指定

システム設定値と異なる言語を表示したい場合、以下のコードで表示したい言語を指定してください。

ElepayLocalization.shared.switchLanguage(code: .ja) // Use Japanese

ElepayLocalization.shared.switchLanguage(code: .en) // Use English

ElepayLocalization.shared.switchLanguage(code: .cn) // Use Simplified Chinese

ElepayLocalization.shared.switchLanguage(code: .tw) // Use Traditional Chinese

この switchLanguage 関数は何回でも使えます。関数を呼び出した後に表示される画面が指定した言語で表示します。

📘

一部の画面の表示言語がご指定出来かねます

一部の決済方法は第三者画面に遷移する事があります。その画面は elepay SDK の制御範囲外のため、ご指定の言語と異なる言語で表示する可能性があります。

Updated 18 days ago


What's Next

リファレンス

Android SDK
H5 SDK
Server SDK

iOS SDK


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.