Cashfree iOS SDK (CFSDK)

CFSDK 是由 Cashfree 创建的 iOS 支付 SDK。此 SDK 可以用于将 Cashfree 支付网关直接集成到您的 iOS 应用中。CFSDK 设计用于简化您应用程序中处理和集成支付的复杂性。

手动安装和设置

以下是最新版本的 iOS SDK 下载链接
ENABLE_BITCODE 应设置为 YES

设置您的项目

添加 Cashfree SDK

1. 将 zip 文件的 contents 拖放到您的 Xcode 项目导航器中。勾选 如果需要则复制项目 复选框。点击 完成
2. 然后在您的 iOS 应用项目文件“通用”标签下的“嵌入式二进制文件”中点击加号按钮。
3. 选择 CFSDK.xcframework。
4. 点击 完成。

点击这里获取更多信息。

这是一个示例iOS应用程序，展示和使用Cashfree的iOS SDK

1. 使用zip文件下载或使用克隆github项目。

git clone https://github.com/cashfree/ios-CFWebSDK.git

2. 使用XCode打开ExampleCFWebSDK应用程序。

3. 将变量appID更改为在Cashfree商户仪表板上生成的相应appId。

4. 按照以下集成文档进行操作，生成orderToken。

5. 在"tokenData"键中添加生成的令牌。

6. 设置相应的环境"TEST"或"PROD"并运行项目。

NOTE:- In case if the project says "Unable to find module", follow the steps:

1. Extract the CFSDK.xcframework from the zip file.
2. Remove the XCFramework in the project and Drag and Drop the extracted XCFramework.
3. Select "Copy Items If Needed" and select the target app and click on "Finish".
4. Run the app.

集成文档

要将Cashfree iOS SDK集成到您的iOS应用程序中，

1. 在Cashfree上创建账户并获取API密钥
2. 将Cashfree SDK集成到您的应用程序中
3. 生成令牌（从后端）
4. 发起支付 - 在Cashfree SDK中调用支付API，用顾客从您的应用程序中下单初始化支付时生成的令牌。Cashfree SDK向顾客展示适当的支付屏幕。
5. 接收和处理响应 - Cashfree SDK返回订单的支付结果，应在你的应用程序中处理。
6. 验证响应 - 我们建议您使用webhooks并检查支付响应中返回的签名值来验证支付响应。

步骤1：创建账户并获取API密钥

1. 前往Cashfree网站并创建账户。点击这里获取创建和激活账户的详细步骤。
2. 使用相同的凭据登录商户仪表板。
3. 点击“支付网关”部分，点击“查看仪表板”，然后点击“凭据”。出于安全考虑，您需要输入密码进行验证。
4. 复制appId和密钥。这些值是使用您的服务器创建orderToken所必需的。订单令牌用于认证从Cashfree iOS SDK发起的API调用。

第二步：从后端生成令牌

cftoken 用于验证从SDK发出的支付请求。每次为订单尝试支付时，都必须生成一个 cftoken。在启动特定订单的支付时，将此令牌传递给SDK。要从API生成cftoken，您需要使用我们的令牌生成API。

生成令牌的请求描述

生产环境：将URL设置为 **https://api.cashfree.com/api/v2/cftoken/order** 测试环境：将URL设置为 https://test.cashfree.com/api/v2/cftoken/order

您需要将 orderId、orderCurrency 和 orderAmount 作为JSON对象发送到API端点，在响应中将接收到令牌。请参阅以下请求描述。

令牌请求描述

curl -XPOST -H 'Content-Type: application/json' 
-H 'x-client-id: ' 
-H 'x-client-secret: ' 
-d '{
  "orderId": "",
  "orderAmount":,
  "orderCurrency": "INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'

令牌请求示例：将 YOUR_APP_ID 和 YOUR_SECRET_KEY 替换为实际值。

curl -XPOST -H 'Content-Type: application/json' -H 'x-client-id: 2754xxxxxxxxxxf5272' -H 'x-client-secret: 2279ccxxxxxxxxxxxxx409517' -d '{
  "orderId": "Order0001",
  "orderAmount":1,
  "orderCurrency":"INR"
}' 'https://test.cashfree.com/api/v2/cftoken/order'

令牌响应示例

{
"status": "OK",
"message": "Token generated",
"cftoken": "v79JCXXXXXXXXXXXXN1EjOiAHelJCLiXXXXXXXXXXXZiclRmcvJye.K3NKICVS5DcEzXm2VQUO_ZagtWMIKKXzYOqPZ4x0r2P_N3-PRu2mowm-8UXoyqAgsG"
}

“cftoken” 属性是需要用于保护请求的令牌。
此API应仅在服务器（后端）上调用，永远不要从iOS应用程序中调用，因为它使用secretKey。

第三步：启动支付

生成订单令牌后，在调用支付API（doWebCheckoutPayment、doUPIPayment、doGPayPayment、doAmazonPayment）时启动支付。对于支付，您的应用将订单信息和cftoken传递给SDK。向客户显示相应的支付屏幕，他们在其中输入所需信息并完成支付。支付完成后，客户将被重定向到iOS应用程序，并在ResultDelegate实现中收到响应。

在令牌生成和支付启动期间传递的订单详情应匹配。否则，您将收到一个无效订单详情错误。无效的应用ID和令牌将导致无法验证商户错误。为支付生成的令牌有效期为5分钟，在此期间必须启动支付。否则，您将收到一个无效令牌错误。

第4步：接收和处理响应

支付完成时，您将在结果代理实现中获得响应。

extension ViewController: ResultDelegate {
    func onPaymentCompletion(msg: String) {
        print("Result Delegate : onPaymentCompletion")
        print(msg)
        // Handle the result here
    }
}

第6步：验证响应

我们建议您通过Webhooks验证支付响应。您也可以通过检查支付响应中的签名来验证响应。

示例应用

点击这里查看示例应用。

结账

结账是Cashfree iOS SDK的标准流程。在此流程中，SDK加载一个webview，在其中渲染Cashfree的支付页面。客户可以在这里填写详细信息并完成支付。
Web Checkout有两种类型。您可以根据业务需求选择所需的方法。

更新您的项目中的Info.plist文件
将以下代码添加到Info.plist文件中。

<key>LSApplicationCategoryType</key>
<string></string>
<key>LSApplicationQueriesSchemes</key>
<array>
<string>phonepe</string>
<string>tez</string>
<string>paytm</string>
<string>bhim</string>
</array>

1. 正常 - 客户在Cashfree的Web支付页面中选择支付方式并输入支付详细信息以完成支付。
2. 无缝连接 - 客户选择付款方式并在您的应用程序中输入付款详情。然后，这些详情将被传递给Cashfree SDK。仅针对两步验证，才启动WebView。

当集成我们的iOS SDK时，调用 UIViewController 应该嵌入在 UINavigationController 之内。如果您 UIViewController 在 UITabBarController 中，应将 UIViewController 嵌入 UINavigationController。

步骤 1：导入SDK

import CFSDK

步骤 2：输入参数字典

一旦您从服务器端生成令牌，请创建以下值的输入参数字典。

从服务器发送的订单详情应与从应用程序发送到SDK的值相匹配，否则您将看到此错误 "无效的订单数据"。

func getPaymentParams() -> Dictionary<String, Any> {
    return [
        "appId": "<<YOUR_APP_ID>>",
        "orderId": "Order100003",
        "tokenData" : "<<GENERATED_TOKEN>>",
        "orderAmount": "1",
        "customerName": "Customer name",
        "orderNote": "Order Note",
        "orderCurrency": "INR",
        "customerPhone": "9012341234",
        "customerEmail": "[email protected]",
        "notifyUrl": "https://test.gocashfree.com/notify"
    ]
}

步骤 3：调用支付函数

从SDK创建CFPaymentService对象，并使用env和ResultDelegatecallback调用doWebCheckoutPaymentfunction函数。env可以是TEST或PROD。点击此处了解如何获取应用ID和密钥。

CFPaymentService().doWebCheckoutPayment(
                        params: params,
                        env: Constants.environment,
                        callback: self)

步骤 4：结果代理

支付完成后，您会在ResultDelegate实现中收到响应。

extension ViewController: ResultDelegate {
    func onPaymentCompletion(msg: String) {
        print("Result Delegate : onPaymentCompletion")
        print(msg)
        // Handle the result here
    }
}

无缝结账

在无缝支付流程中，客户在商家应用结账视图中输入所有详细信息。一旦客户输入了与支付方式相关的所有详细信息，请求将在一个展示服务提供商（例如，在卡支付的情况下OTP页面）的webview中打开。
无缝模式的集成步骤几乎与结账流程相同，只是在传递的输入参数中会有根据所选支付方式添加的额外参数。
除了其他指定的输入参数之外，请将以下片段中的参数传递：这里。

卡支付

在调用doWebCheckoutPayment()方法启动无缝卡交易之前，请将以下参数添加到params映射中。

let cardParams = [
    "paymentOption": "card",
    "card_number": "4434260000000008", //Replace Card number
    "card_holder": "John Doe", // Card Holder name
    "card_expiryMonth": "05", // Card Expiry Month in MM
    "card_expiryYear": "2021", // Card Expiry Year in YYYY
    "card_cvv": "123" // Card CVV
]

UPI支付

在调用doWebCheckoutPayment()方法启动无缝UPI交易之前，请将以下参数添加到params映射中。

let upiParams = [
    "paymentOption": "upi",
    "upi_vpa": "testsuccess@gocash"
]

钱包支付

在调用doWebCheckoutPayment()方法启动无缝钱包交易之前，请将以下参数添加到params映射中。所有有效的钱包代码均可在此处找到。

let walletParams = [
    "paymentOption": "wallet",
    "paymentCode": "4001" // Wallet code https://docs.cashfree.com/docs/resources/#wallet
]

网上银行支付

在调用doWebCheckoutPayment()方法以启动无缝网上银行业务交易之前，将以下参数添加到params映射中。所有有效的银行代码均可在此处找到。

let netBankingParams = [
    "paymentOption": "nb",
    "paymentCode": "3333" // Bank code https://docs.cashfree.com/docs/resources/#net-banking
]

Paypal付款

在调用doWebCheckoutPayment()方法以启动无缝Paypal交易之前，将以下参数添加到params映射中。

let paypalParams = [
    "paymentOption": "paypal"
]

UPI Intent

对于iOS，目前UPI Intent支持Googlepay、PhonePe和Paytm。
集成步骤

1. 更新您的项目中的Info.plist文件
   将以下代码添加到Info.plist文件中。

<key>LSApplicationCategoryType</key>
<string></string>
<key>LSApplicationQueriesSchemes</key>
<array>
<string>phonepe</string>
<string>tez</string>
<string>paytm</string>
<string>bhim</string>
</array>

2. 编写订单详情并将其传递给Cashfree PG SDK
   使用最后的2个API响应来组合字典<String, Any>。

var orderParms = [
   "orderId": "<YOUR_ORDER_ID>",
   "tokenData" : "<cfToken>",
   "orderAmount": "<ORDER_AMOUNT>",
   "orderCurrency":"<ORDER_AMOUNT_CURRENCY>",
   "customerName": "Example",
   "orderNote": "First Order",
   "customerPhone": "1111111111",
   "appId": "<YOUR_APP_ID>",
   "customerEmail": "[email protected]",
   "notifyUrl": "https://test.gocashfree.com/notify", //optional
   ]

将此对象与appName和环境传递给Cashfree SDK。一旦函数被调用，Cashfree iOS SDK将显示支持的app列表。一旦用户选择app，他们将重定向到所选app进行支付。在完成支付后，您的客户必须导航回到您的应用程序。

CFPaymentService().doUPIPayment(params : orderParams,  env: "TEST", callback: self)

3. 从Cashfree PG SDK获取结果
   Cashfree SDK将根据用户选择的选项启动PhonePe或Google Pay。一旦在第三方UPI付款应用程序中完成支付且用户返回到应用程序，SDK将验证支付并通过ResultDelegate返回结果。

extension ViewController: ResultDelegate 
{
    func onPaymentCompletion(msg: String) 
    {
        print("Result Delegate : onPaymentCompletion \(msg)")
        // Handle the result here
    }
}

响应将为字符串化的JSON语法

{"txStatus": "PENDING", "message": null}

在成功完成以上步骤后，您可以验证支付。

直接应用程序集成

AmazonPay

集成步骤

1. 使用上述提到的订单令牌API创建令牌
2. 编写订单详情并将其传递给Cashfree PG SDK
   使用最后的2个API响应来组合字典<String, Any>。

var orderParms = [
   "orderId": <YOUR_ORDER_ID>,
   "tokenData" : <cfToken>,
   "orderAmount": <ORDER_AMOUNT>,
   "orderCurrency":<ORDER_AMOUNT_CURRENCY>,
   "customerName": "Example",
   "orderNote": "First Order",
   "customerPhone": "1111111111",
   "appId": <YOUR_APP_ID>,
   "customerEmail": "[email protected]",
   "notifyUrl": "https://test.gocashfree.com/notify"
]

现在将此对象与appName和环境传递给Cashfree SDK

CFPaymentService().doAmazonPayPayment(params : orderParams,  env: "TEST", callback: self)

3. 从Cashfree PG SDK获取结果
   根据用户选择的选项，Cashfree SDK将启动PhonePe或Google Pay。一旦在SFSafariViewController中完成支付，并且用户点击完成，SDK将验证支付并通过ResultDelegate传递结果。

extension ViewController: ResultDelegate {
    func onPaymentCompletion(msg: String) {
        print("Result Delegate : onPaymentCompletion \(msg)")
        // Handle the result here
    }
}

响应将是语法为{"txStatus": "PENDING", "message": null}的字符串化JSON。

请求参数

这些是在您使用Cashfree iOS SDK进行支付请求时可供使用的参数。

响应参数

这些参数通过您使用paymentVC.getResult()实现的功能返回。transactionResult包含交易的详细信息。始终如下面所述验证响应中的签名。

• 可能存在SDK无法在短时间内验证支付的场景。此类订单的状态将是PENDING。\
• 如果在打开Webview后立即关闭，可能是由于SDK传入的输入存在问题。请检查传入的输入，如果您需要进一步的帮助，请联系我们 [email protected]。
• 如果在交易状态中收到“不完整”，请联系您的账户经理或 [email protected]。了解更多关于交易状态的信息，请点击 这里。

Webhook通知

不要在不集成webhook通知的情况下上线。

当成功处理订单付款并到达您的notifyUrl时，我们会在后端向您后端发送通知。这在用户支付后网络连接中断的情况下很有用。这将允许您在您的一端对所有的成功订单进行核对。通知将发送到创建订单时指定的notifyUrl。通知中发送的参数在此 处描述。

要指定notifyUrl，只需将它与其它参数（orderId，orderAmount等）一起添加即可。

通常通知几乎是瞬时的，但很少可能在1分钟内到达您的服务器。请确保您的URL支持https。只有成功的付款才会发送通知。
有时您可能会收到相同的通知两次或更多次。建议确保您的webhook实现是无状态的。
请确保您验证webhook响应中的签名。

响应验证

验证响应签名以检查交易响应的真实性。请勿在未验证签名的情况下上线。

在每个响应中，我们添加一个数字签名以建立消息的真实性。我们需要您在您的端验证接收到的签名。这将验证响应是否未被篡改。\

此验证必须在您的后端服务器上完成，因为它将涉及secretKey，该密钥不应暴露在客户端端。\

请根据您的后端语言使用下面的适当代码示例。

CFSDK动态框架适用于iOS 10及以上版本。

点击 这里 了解如何查看或生成生产环境和测试环境的API密钥。

测试凭证