PayGol Android SDK - 使用 SMS 的支付模型

• 下载 PayGolApp - 30.67 KB
• 下载 PayGolDoc - 58.4 KB
• 下载 PayGolSDK - 27.12 KB

为什么选择 PayGol？ 

从用户的角度来看，您的支付模式有多么方便和简单？购买服务是否需要信用卡号或银行账户信息？用户在提供信用卡号或银行账户信息时是否存在安全方面的顾虑？是否可以有一种不同的、更实用的支付模式，而无需提供任何数据？幸运的是，答案是肯定的。PayGol 提供了一种使用短信消息的支付模式。当用户购买服务时，她只需发送短信消息即可完成支付，而无需提供任何个人数据。PayGol 技术对集成支付模式的开发者和购买服务的最终用户来说，都既实用、安全、易于集成，又方便。 

概述

在本文中，我们将介绍 PayGol Android SDK，并详细解释开发者如何将其集成到其 Android 应用程序中。PayGol Android SDK 是一个适用于 Android 手机的 JAR 库，用于通过短信消息进行支付。 下图显示了 PayGol 支付模式的工作流程概览。

使用 PayGol Android SDK 进行支付包括以下步骤：

1. 向 PayGol 服务器发出支付请求。此步骤由集成应用程序以编程方式发起，对应图 1 中的箭头 1。 
2. 如果请求已被接受，PayGol 服务器会将接受的支付参数返回给 PayGol Android SDK。此步骤对应图 1 中的箭头 2。 
3. 在支付请求被 PayGol 服务器接受后，PayGol Android SDK 会自动执行以下三个步骤。 
   1. SDK 以编程方式将 PayGol 服务器已接受的支付参数传达给集成软件。这是图 1 中第 3 步的一部分。 
   2. SDK 将 PayGol 服务器已接受的支付参数显示给最终用户，并询问其是否接受。这也是图 1 中第 3 步的一部分。 
   3. 如果最终用户接受支付条件，SDK 将继续发送短信消息以完成支付。这在图 1 中显示为 4。 
4. PayGol 服务器与“移动运营商网络”通信，以检查支付是否成功。这是图 1 中的 5。此步骤由服务器执行，不属于在应用程序中集成 PayGol Android SDK 的一部分。 
5. 在 PayGol SDK 发送短信消息后，作为最后一步，集成应用程序应了解支付是否成功。为此，它会向 PayGol 服务器发出最终调用。此步骤由集成应用程序以编程方式发起，对应图 1 中的箭头 6。PayGol 服务器会回复其从“移动运营商网络”获得的信息。这在图 1 中显示为步骤 7。 

以下部分将详细解释将 PayGol Android SDK 配置和集成到任何 Android 应用程序所需的所有必要步骤。  

如何使用 PayGol Android SDK？ 

PayGol Android SDK:  

1. 异步工作。其接口函数的调用是非阻塞的。因此，PayGol Android SDK 绝不会导致 ANR 错误。 
2. 始终在正确的线程上下文中工作。每当它需要显示弹出窗口时，它都会在 UI 线程上下文中执行相应的语句；否则，它会在后台线程中执行语句。因此，开发者无需考虑在调用 PayGol SDK 接口方法时是否应切换线程上下文。 

本节的解释假设使用的 IDE 是 Eclipse。 

在 Eclipse 中配置 PayGol Android SDK

PayGol Android SDK JAR 库文件（例如 PayGolSDK.jar）应作为外部 JAR 添加到 Java Build Path 中： 

单击“Properties”打开项目属性。然后转到“Java Build Path”和“Libraries”选项卡。 

 

单击“Add External JARs”并浏览到 PayGolSDK.jar 文件的位置。 

在 AndroidManifest.xml 中添加权限

以下三个权限应添加到 AndroidManifest.xml 中： 

<uses-permission android:name="android.permission.INTERNET" /> 
<uses-permission android:name="android.permission.SEND_SMS" /> 
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

需要“android.permission.INTERNET”权限，因为与 PayGol 服务器通信以进行支付需要互联网连接。

由于支付模式基于发送短信消息，因此需要“android.permission.SEND_SMS”权限。  

PayGol Android SDK 将 IMEI 附加到支付请求中，以进行交易的唯一标识和可追溯性。读取手机 IMEI 需要“android.permission.READ_PHONE_STATE”权限。  

集成 PayGol Android SDK 

一旦 PayGolSDK.jar 配置在项目设置中并在清单文件中添加了权限，您就可以在代码中使用 PayGol Android SDK 了。以下步骤详细解释了需要遵循的每个步骤。图 4 显示了集成顺序图。 

步骤 1 – 实例化 

实例化一个 PayGolSDK 对象。有两种构造函数可供选择： 

PayGolSDK(Context context)

PayGolSDK(Context context, 
          PayGolSDKConfig config)

两个构造函数都接受应用程序上下文作为参数。第二个构造函数还接受一个配置对象作为参数。有关配置对象和默认配置参数的更多信息，请参阅“PayGolSDKConfigObject”部分。

步骤 2 – 配置（可选） 

PayGolSDK 也可以在实例化步骤之后进行配置。实际上，PayGolSDK 可以在任何步骤进行重新配置。为此，您可以使用 PayGolSDK 对象的以下方法： 

void SetPayGolSDKConfig(PayGolSDKConfig config) 

有关配置对象和默认配置参数的更多信息，请参阅“PayGolSDKConfigObject”部分。 

步骤 3 – 发起支付请求 

当需要进行支付时，必须向 PayGol 服务器发起支付请求。为此，您应该调用 PayGolSDK 的 MakePayment 方法。有四种重载选项。  

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final Object userArgs)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final String custom)

void MakePayment(final PayGolSDKProduct product,
                 final String language,
                 final Activity activity,
                 final PayGolSDKListener.OnMakePaymentListener listener,
                 final String custom,
                 final Object userArgs)

PayGolSDKProduct 对象有三个成员：您的 service_id、支付的 price 和 currency。有关 PayGolSDKProduct 对象的信息，请参阅“PayGolSDKProduct Object”部分。  

参数 language 可以是以下四个值之一：en、de、fr、es，它指定支付过程中使用的语言（例如，显示给最终用户的消息的语言）。  

下一个参数 activity 是您 Android 应用程序当前可见的活动，支付正在进行中。此参数是必需的，因为 PayGol SDK 将向最终用户显示一个对话框，询问她是否接受支付条件。用于显示此对话框的代码始终在 UiThread 上下文中运行，因此开发者无需考虑何时更改线程上下文。要在 UiThread 上下文中运行代码片段，必须能够访问当前显示的活动对象。因此，PayGolSDK.MakePayment 方法需要 activity 参数。 

PayGolSDKListener.OnMakePaymentListener 是一个监听器对象，用于通信支付请求的结果。第 3.1 节将详细介绍 PayGolSDKListener.OnMakePaymentListener。  

可选参数 custom 是一个占位符字段，可用于杂项用途。其典型用例之一是存储最终用户的唯一标识符。在在线游戏环境中，此唯一标识符可以是用户 ID 或会话 ID，以便 PayGol 服务器知道确切的哪个用户正在购买服务。 

最后，可选参数 userArgs 是您传递给 MakePayment 的任何对象，稍后在调用 PayGolSDKListener.OnMakePaymentListener 的 onAction 和 onData 方法时会收到。当您想为支付请求添加更多数据以在支付成功时显示或处理时，这非常方便。  

步骤 3.1 – 实现 PayGolSDKListener.OnMakePaymentListener 

PayGolSDK 定义了 PayGolSDKListener.OnMakePaymentListener，这是一个您应该实现的接口，并在发起支付请求时将其实例传递给 MakePayment。实现应覆盖三个方法：  

void onAction(int which, 
              Object userArgs) 

PayGolSDK 调用 onAction 来报告支付当前所处的状态。典型场景是：当 PayGol 服务器拒绝支付时、当短信消息无法发送或送达时，或者当短信消息已发送并送达时。文档枚举了调用 onAction 的所有情况。 

参数 which 存储一个代码，显示支付的最新状态。 

参数 userArgs 是您传递给 MakePayment 的用户参数对象。如果未将用户参数对象传递给 MakePayment，则 userArgs 存储 null。  

void onData(PayGolSDKProduct product, 
            Object userArgs) 

当 PayGol 服务器接受支付请求时，会调用 onData 方法。您在发起支付请求时指定的支付参数（请参阅“PayGolSDKProduct Object”部分）不一定是 PayGol 服务器接受的参数。PayGol 服务器会在必要时根据发送短信消息在用户所在国家/地区的成本调整指定的价格和货币。当支付被接受时，onData 会以编程方式将 PayGol 服务器接受的支付参数传达给您的应用程序。  

参数 product 是存储 PayGol 服务器接受的支付参数的对象。有关此对象的进一步解释，请参阅“PayGolSDKProductObject”部分。 

与 onAction 类似，参数 userArgs 是您传递给 MakePayment 的用户参数对象。如果未将用户参数对象传递给 MakePayment，则 userArgs 存储 null。 

void onResult(PayGolSDKPayment payment)

当进行支付所需的短信消息成功送达时，PayGol SDK 会调用 onResult 方法。此方法向您的应用程序传递一个 PayGolSDKPayment 对象（例如 payment），该对象对于稍后检查支付是否成功是必需的。  

步骤 4 – 检查支付是否成功

在短信消息成功送达并调用 PayGolSDKListener.OnMakePaymentListener 的 onResult 方法后，在考虑交易成功之前，您应该检查支付是否实际上在 PayGol 服务器上成功了。为此，您需要使用从 onResult 获取的 PayGolSDKPayment 的 IsPaymentSuccessful 方法。IsPaymentSuccessful 会以指定的间隔定期运行；如果它检测到支付已成功，它会向您的应用程序传达一个成功代码。如果它在指定的时间段内无法检测到支付已成功，它会传达一个超时代码。IsPaymentSuccessful 运行的时间段和最长时间是 PayGolSDK 配置参数的一部分；有关更多信息，请参阅“PayGolSDKConfig Object”部分。 

void IsPaymentSuccessful(PayGolSDKListener.OnIsPaymentSuccessfulListener listener)

PayGolSDKListener.OnIsPaymentSuccessfulListener 是一个监听器对象，用于通信支付是否成功的状态。第 4.1 节提供了更多信息。 

步骤 4.1 – 实现 PayGolSDKListener.OnIsPaymentSuccessfulListener

这是一个您应该实现的接口，并将其实例传递给 IsPaymentSuccessful。实现应覆盖一个方法： 

void onAction(int which, 
              PayGolSDKPayment payment)

参数 which 存储一个代码，显示支付是否成功。  

最后，参数 payment 是指向调用 IsPaymentSuccessful 方法的 PayGolSDKPayment 对象的指针。这在您想知道 onAction 方法是为哪个交易调用的时很有用。  

PayGolSDKConfig 对象

PayGolSDKConfig 使开发者能够配置 PayGol SDK 的以下选项： 

1. PayGol SDK 是否会生成日志信息。这在调试 PayGolSDK 集成时是必要且非常有用的。对应的成员是 PayGolSDKConfig.enableDebug，默认值为 false。 
2. 交易将以真实模式还是模拟模式进行。真实模式是指发送短信消息进行支付。模拟模式是指在 PayGol SDK 和 PayGol 服务器之间模拟发送短信消息。模拟模式已被设计出来，并且在开发阶段非常有用，此时开发者需要在不为每次支付周期运行付费的情况下测试集成。请联系 PayGol 以验证哪个服务 ID 用于模拟模式。对应的成员是 PayGolSDKConfig.isSimulation，默认值为 false。 

(其余配置参数会影响 PayGolSDKPayment.IsPaymentSuccessful 的执行) 

3. PayGolSDKPayment.IsPaymentSuccessful 检查相应支付是否成功的最大时间（以秒为单位）。对应的成员是 PayGolSDKConfig.maxTimeControlPayment，默认值为 60 (六十) 秒。 
4. PayGolSDKPayment.IsPaymentSuccessful 检查相应支付是否成功的基准时间（以秒为单位）。对应的成员是 PayGolSDKConfig.periodControlPayment，默认值为 10 (十) 秒。 

5. 基准时间的变化方差。对应的成员是 PayGolSDKConfig.changePeriodControlPayment，默认值为 0 (零) 秒。例如，如果您想在 10、25、45... 这些时间点控制支付是否成功，而不是在 10、20、30... 这些时间点，您应该指定 periodControlPayment=10 和 changePeriodControlPayment=5。

PayGolSDKProduct 对象

PayGolSDKProduct 封装了在 PayGol 交易中定义产品所需的三个字段：service_id、price 和 currency。在 PayGol 服务器发起支付请求时，PayGolSDKProduct 作为参数传递给 MakePayment，并在 PayGol 服务器接受请求的支付后（可能经过调整价格和货币）在 PayGolSDKListener.OnMakePaymentListener 的 onData 侦听器方法中检索。  

建议？  

如有建议和意见，请联系：

Ali Chousein  

附注

PayGol Android SDK 已正式发布。相关链接：

http://www.paygol.com/android/implementation 

http://www.paygol.com/newservice