ATH Móvil Payment Button - iOS SDK
简介
ATH Móvil 的支付按钮 SDK 为 iOS 应用端付费客户提供简单、安全快速的结账体验。在您的应用中集成支付按钮后,您将能从超过 150 万 ATH Móvil 用户那里实时接收付款。
先决条件
在开始之前,请查看以下先决条件
- 您需要一个活跃的 ATH Móvil 商业账户来继续。要注册,请在 iOS 或 Android 设备的 App Store 或 Play Store 下载 "ATH Móvil Business"。
- 您的 ATH Móvil 商业账户需要有一个已注册、已验证并活跃的 ATH® 卡。
- 准备您的商业账户的公钥和私钥。 您可以在 iOS 或 Android 的 ATH Móvil Business 的设置部分查看您的 API 密钥。
支持
如果您在注册、添加卡片或遇到其他任何问题时需要帮助,请参考https://athmovilbusiness.com/preguntas或联系我们的支持团队,电话:(787) 773-5466。关于技术支持,请填写以下表格:https://forms.gle/ZSeL8DtxVNP2K2iDA。
安装
在开始之前,让我们配置您的项目
-
安装CocoaPods(点击此处获取详细说明)。安装后,使用
pod init
来启动Podfile。 -
在Podfile中添加
athmovil-checkout
依赖。
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付款”按钮的文本将自动显示在设备配置的语言上。
语言 | 示例 |
---|---|
英语 | |
西班牙语 |
在Storyboard或Xib中使用“使用ATH Móvil付款”按钮。
- 打开您的视图接口构建器,并添加一个
UIButton
。 - 更改新
UIButton
的以下属性: - 在视图控制器中创建
@IBOutlet
或将@IBaction
事件添加到视图控制器中。默认情况下,ATHMButton
设置为经典样式,但您可以通过theme
属性更改主题。
UIButton
转换为 "Pay with ATH Móvil" 按钮样式
将 UIKit 的 如果您有一个 UIKit UIButton
的实例,可以使用以下方法将其转换为 "Pay with ATH Móvil"
主题 | 示例 |
---|---|
.toggleATHMClassic() | |
.toggleATHMLight() | |
.toggleATHMNight() |
您的按钮将是一个 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
。这意味着您可以像使用frame
、addsubview
和addtarget
方法一样使用 UIKit 功能。- 您可以通过修改
theme
属性来更改ATHMButton
实例的主题。主题可以在多线程中安全地多次修改。
主题 | 示例 |
---|---|
athMovilButton.theme = ATHMThemeClassic() | |
athMovilButton.theme = ATHMThemeLight() | |
.athMovilButton.theme = ATHMThemeNight() |
向 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.
}
-
支付过程与用户界面解耦,这意味着您可以使用这些类发送支付请求,无论您是否使用
UIButton
或ATHMButton
。 -
以下可选属性可用于向支付添加额外信息
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
调用正确的请求,并使用回调onCompleted
、onExpired
、onCancelled
或onException
根据支付结果。 - 如果您的应用程序有其他 deepen links或使用
application(app:open:options:)
方法打开您的应用程序的其他第三方应用程序,ATH Móvil SDK将自动丢弃URL,因此您不需要为ATHMPaymentSession.shared.url = url
实现额外的验证。
ATHMPaymentHandler
将现在接收到一个类型为ATHMPaymentResponse
的对象。根据交易结果,将自动调用onCompleted
、onExpired
或onCancelled
闭包。您将接收到包含以下内容的付款信息对象
/// 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
`。
用户体验
法律
此API及相关文档的使用受ATH Móvi Business®的使用条款和条件的管理,可在以下地址找到:[https://athmovilbusiness.com/terminos](https://athmovilbusiness.com/terminos)。