athmovil-checkout 4.0.0

athmovil-checkout 4.0.0

Leonardo Maldonado 维护。



  • Evertec

ATH Móvil Payment Button - iOS SDK

简介

ATH Móvil 的支付按钮 SDK 为 iOS 应用端付费客户提供简单、安全快速的结账体验。在您的应用中集成支付按钮后,您将能从超过 150 万 ATH Móvil 用户那里实时接收付款。

先决条件

在开始之前,请查看以下先决条件

  1. 您需要一个活跃的 ATH Móvil 商业账户来继续。要注册,请在 iOS 或 Android 设备的 App Store 或 Play Store 下载 "ATH Móvil Business"。
  2. 您的 ATH Móvil 商业账户需要有一个已注册、已验证并活跃的 ATH® 卡。
  3. 准备您的商业账户的公钥和私钥。 您可以在 iOS 或 Android 的 ATH Móvil Business 的设置部分查看您的 API 密钥。

支持

如果您在注册、添加卡片或遇到其他任何问题时需要帮助,请参考https://athmovilbusiness.com/preguntas或联系我们的支持团队,电话:(787) 773-5466。关于技术支持,请填写以下表格:https://forms.gle/ZSeL8DtxVNP2K2iDA

安装

在开始之前,让我们配置您的项目

target 'MyProject' do
use_frameworks!
pod 'athmovil-checkout'
end
  • 执行pod install来完成SDK pod的安装。
  • 打开CocoaPods工作区,并确保您的项目仍然可以编译。
  • 现在,您可以开始使用ATH Móvil支付按钮了。

用法

要在您的应用程序中实现ATH Móvil的支付按钮,您需要完成以下逐步指南。通过遵循此指南,您将能够:

  • 在应用程序界面上显示“使用ATH Móvil付款”按钮。
  • 向ATH Móvil发送支付请求。
  • 管理ATH Móvil发送的支付请求的响应。

在应用程序界面上显示“使用ATH Móvil付款”按钮。

ATH Móvil的支付按钮定义了一个名为ATHMButton的类用于用户界面。您可以通过以下三种方式创建ATHMButton的实例:

  • 使用Storyboard或Xib中的“使用ATH Móvil付款”按钮。
  • 将UIKit的UIButton转换为“使用ATH Móvil付款”按钮样式。
  • 通过代码添加“使用ATH Móvil付款”按钮。

“使用ATH Móvil付款”按钮的文本将自动显示在设备配置的语言上。

语言 示例
英语 alt text
西班牙语 alt text

在Storyboard或Xib中使用“使用ATH Móvil付款”按钮。

  1. 打开您的视图接口构建器,并添加一个 UIButton
  2. 更改新 UIButton 的以下属性: changeProperties
  3. 在视图控制器中创建 @IBOutlet 或将 @IBaction 事件添加到视图控制器中。默认情况下,ATHMButton 设置为经典样式,但您可以通过 theme 属性更改主题。

将 UIKit 的 UIButton 转换为 "Pay with ATH Móvil" 按钮样式

如果您有一个 UIKit UIButton 的实例,可以使用以下方法将其转换为 "Pay with ATH Móvil"

主题 示例
.toggleATHMClassic() alt text
.toggleATHMLight() alt text
.toggleATHMNight() alt text

您的按钮将是一个 UIButton 的实例,但它将具有 ATH Móvil 支付按钮样式。

通过代码添加 "Pay with ATH Móvil" 按钮

您可以使用以下示例代码创建 "Pay with ATH Móvil" 按钮实例

let athMovilButton = ATHMButton(frame: CGRect(x: 0, y: 0, width: 320, height: 50))
view.addSubview(athMovilButton)
athMovilButton.addTarget(self, action:#selector(payWithATHMovil(_:)), for: UIControl.Event.touchUpInside)
  • ATHMButton 继承自 UIButton。这意味着您可以像使用 frameaddsubviewaddtarget 方法一样使用 UIKit 功能。
  • 您可以通过修改 theme 属性来更改 ATHMButton 实例的主题。主题可以在多线程中安全地多次修改。
主题 示例
athMovilButton.theme = ATHMThemeClassic() alt text
athMovilButton.theme = ATHMThemeLight() alt text
.athMovilButton.theme = ATHMThemeNight() alt text

向 ATH Móvil 发送支付请求

支付按钮 SDK 提供了一些简单的类,允许您发送支付请求到 ATH Móvil,如下面的示例代码所示

func payWithATHMovil() {

    let businessAccount = ATHMBusinessAccount(token: "Public Token of your ATH Móvil business account")
    let urlScheme = ATHMURLScheme(urlScheme: "URL Scheme of your application")
    let payment = ATHMPayment(total: 20.00)

    /// The object below will tell you the status of the payment after the end user has completed the payment process.
    /// The code inside onCompleted, onExpired, onCancelled or onException is on the main thread.

    let hander = ATHMPaymentHandler(onCompleted: { [weak self] (payment: ATHMPaymentResponse) in
        /// Handle the response when the payment is completed here.

    }, onExpired: { [weak self] (payment: ATHMPaymentResponse) in
        /// Handle the response when the payment is expired here.

    }, onCancelled: { [weak self] (payment: ATHMPaymentResponse) in
        /// Handle the response when the payment is cancelled here.

    }) { [weak self] (error: ATHMPaymentError) in
        /// Handle any exception regarding a request or response here. See error section for more details.
    }

    let request = ATHMPaymentRequest(account: businessAccount, scheme: urlScheme, payment: payment)
    request.pay(handler: hander)

    /// At this point your app will open ATH Móvil and the payment process will start.
    /// If ATH Móvil is not installed on the end user's device the App Store will be automatically opened on ATH Móvil's listing.
}
  • 支付过程与用户界面解耦,这意味着您可以使用这些类发送支付请求,无论您是否使用 UIButtonATHMButton

  • 以下可选属性可用于向支付添加额外信息

        payment.subtotal = 1.00  /// Set to 0 by default
        payment.tax = 2.00       /// Set to 0 by default
        payment.metadata1 = "Attach data to the payment object" /// Empty String by default
        payment.metadata2 = "Attach data to the payment object" /// Empty String by default
        payment.items = [ATHMPaymentItem(name: "Test Item", price: 1, quantity: 1 )] /// Empty array by default
        request.timeout = 120 /// Amount of time that the user has to complete the payment process. This time is for ATH Movil Personal application
    变量 数据类型 必需 描述
    total NSNumber 最终用户需要支付的总金额。
    subtotal NSNumber 可选变量,用于显示支付小计(如果适用)
    tax NSNumber 可选变量,用于显示支付的税额(如果适用)。
    metadata1 String 可选变量,用于将数据附加到支付对象。
    metadata2 String 可选变量,用于将数据附加到支付对象。
    items Array 可选变量,用于显示用户在ATH Móvil付款摘要屏幕上购买的项目。
    令牌 ATHMBusinessAccount ATH Móvil企业账户的公共令牌。为了测试,将公共令牌设置为“dummy”。
    urlScheme ATHMURLScheme 在您的项目中定义的URL方案。有关如何为您的应用程序定义自定义URL方案的说明,请点击这里
    timeout Double 此可选超时时间会在用户在提供的时间内没有完成付款时终止支付过程。倒计时从ATH Móvil应用程序显示付款审查时开始。默认值为600秒(10分钟)。
    handler ATHMPaymentHandler 处理支付响应的对象。在onCompleted、onExpired、onCancelled或onException内部的代码在主线程上。👁❗️

    项目数组

    变量 数据类型 必需 描述
    name String 项目的名称。
    desc String 项目的简要描述。
    price NSNumber 单个项目的价格。
    quantity Int 单个项目的数量。
    metadata String 将数据附加到项目对象的可选变量。

管理ATH Móvil发送的支付请求的响应

用户在您的应用程序中按下付款按钮并在ATH Móvil上完成支付后,ATH Móvil将自动打开您的应用程序以发送付款响应。您的应用程序需要正确配置以接收这些响应。为准备您的应用程序,请将以下行添加到您的AppDelegate或主场景中

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    ATHMPaymentSession.shared.url = url
    return true
}
  • 您现在将接收之前在请求中定义的对象处理器上的付款响应。
  • 不需要保留处理器的引用,SDK会自动处理。在SDK处理完URL后,它将通过ATHMHandler调用正确的请求,并使用回调onCompletedonExpiredonCancelledonException根据支付结果。
  • 如果您的应用程序有其他 deepen links或使用application(app:open:options:)方法打开您的应用程序的其他第三方应用程序,ATH Móvil SDK将自动丢弃URL,因此您不需要为ATHMPaymentSession.shared.url = url实现额外的验证。

ATHMPaymentHandler将现在接收到一个类型为ATHMPaymentResponse的对象。根据交易结果,将自动调用onCompletedonExpiredonCancelled闭包。您将接收到包含以下内容的付款信息对象

/// Payment data initially configured on the request.
response.payment.total
response.payment.subtotal
response.payment.tax
response.payment.fee
response.payment.netAmount
response.payment.metadata1
response.payment.metadata2

/// Items data initially configured on the request.
let paymentItem = response.payment.items.first
paymentItem?.name
paymentItem?.price
paymentItem?.quantity
paymentItem?.desc
paymentItem?.metadata

/// Transaction information.
response.status.dailyTransactionID /// Consecutive of the transaction
response.status.referenceNumber /// Unique idenfier of the transaction
response.status.date /// Date of the transaction

/// ATH Móvil user information.
response.customer.name /// Customer name
response.customer.phoneNumber /// Customer telephone number in format (xxx) xxx-xxxx
response.customer.email /// Customer email
变量 数据类型 描述
dailyTransactionID Int 交易每日ID。如果交易已取消或过期,则值将为0。
referenceNumber String 唯一的交易标识符。如果交易已取消或过期,则值为空字符串。
date 日期 交易日期。
customer.name String 在ATH Móvil上注册的付款用户的名称。如果交易未由最终用户完成,此值可能为空。
customer.phoneNumber String 在ATH Móvil上注册的付款用户的电话号码。如果交易未由最终用户完成,此值可能为空。
customer.email String 在 ATH Móvil 上注册的电子邮箱地址,用户已使用此地址进行交易。如果交易未由最终用户完成,则此值可能为空。
  • 注意:`response.payment` 和 `payment.items` 是请求中接收到的相同对象。值和数据类型将相同。

如果请求支付时发送了未预期数据,SDK 将调用闭包 `onException`,您将接收到类型为 `ATHMPaymentError` 的对象。您的应用程序必须能够处理这些异常。您可以使用以下示例代码查看异常原因

...
}) { [weak self] (error: ATHMPaymentError) in

            error.failureReason ///Description of the error.
            error.errorDescription ///"Error in request" or "Error in response".
            error.isRequestError ///True if the error is in the request.
            ///Here you will receive any exception related to a request or response.
}
  • 在请求中,请确保您遵守对 `ATHMPayment`、`ATHMBusinessAccount` 和 `ATHMURLScheme` 对象的要求,否则在回调中您将收到异常。

    变量 预期值
    total 正值
    subtotal 正值或零
    tax 正值或零
    metadata1 包含字符、数字或空格的字符串
    metadata2 包含字符、数字或空格的字符串
    令牌 包含字符的字符串
    urlScheme 包含字符的字符串。**不要在示例中使用 urlscheme**❗️
    timeout 介于 60 和 600 之间的整数
  • 如果您在请求中提供项目,请确保您遵守对 `ATHMPaymentItem` 对象的要求

    变量 预期值
    name 包含字符的字符串
    desc 包含字符、数字或空格的字符串
    price 大于零的正值
    quantity 大于零的正值
    metadata 包含字符、数字或空格的字符串

测试

为了测试您的支付按钮集成,您可以使用您的 ATH Móvil 商业账户的私人令牌和公开令牌在生产环境中进行支付,或者您可以使用公开令牌 "dummy" 进行模拟支付。

  • ATH Movil 生产应用程序将模拟一次支付。
  • 在与模拟支付交互时无需提供任何最终用户凭据。
  • 可以测试完成、取消和过期的支付。
func payWithATHMovil() {

    let businessDummy = ATHMBusinessAccount(token: "dummy")
    ...

混合应用程序

如果您使用 Flutter 或 Ionic 构建应用程序,您可能需要向我们的 SDK 发送字典。`ATHMBusinessAccount`、`ATHMURLScheme` 和 `ATHMPayment` 都有对字典的构造函数。您应该使用 `ATHMPaymentHandlerDictionary` 和 `pay` 方法来接收 `ATHMPaymentHandlerDictionary` 实例。例如

...
let requestDic = NSDictionary(dictionary: ["scheme": "athm-checkout",
                                            "publicToken": "dummy",
                                            "total": 20.00,
                                            "subtotal": 1.00,
                                            "tax": "2.00",
                                            "metadata1": "This is metadata1",
                                            "metadata2": "This is metadata2",
                                            "items":[
                                                ["name": "ItemTest",
                                                "price": 2.0,
                                                "quantity": 1,
                                                "desc": "Description",
                                                "metadata": "Metadata"]
                                                ]
                                            ])

let businessAccount = ATHMBusinessAccount(dictionary: requestDic)
let urlScheme = ATHMURLScheme(dictionary: requestDic)
let payment = ATHMPayment(dictionary: requestDic)

let handler = ATHMPaymentHandlerDictionary(onCompleted: { [weak self] (response: NSDictionary) in
    /**
    response["total"]
    response["items"]
    response["name"]
    response["email"]
    ...
    */
}, onExpired: { [weak self] (response: NSDictionary) in

}, onCancelled: { [weak self] (response: NSDictionary) in

}) { [weak self] (error: ATHMPaymentError) in
}

let request = ATHMPaymentRequest(account: businessAccount, scheme: urlScheme, payment: payment)
request.pay(dictionaryHandler: handler)
  • 此字典包含所有必需的属性。其中一些属性是可选的,如上面“管理由 ATH Móvil 发送的支付请求响应”部分中所述。
  • 支付响应也是一个字典,这意味着您可以使用上面“管理由 ATH Móvil 发送的支付请求响应”部分中提到的键查看响应数据。
  • 公开令牌 "dummy" 也可以与字典一起使用。
  • 注意:响应支付需要 `ATHMPaymentSession`。

用户体验

paymentux

法律

此API及相关文档的使用受ATH Móvi Business®的使用条款和条件的管理,可在以下地址找到:[https://athmovilbusiness.com/terminos](https://athmovilbusiness.com/terminos)。