Ksher H5页面支付实例指导 (PHP实现)

news2025/3/1 4:03:13

`前文`

背景介绍
前两天，公司的项目，为了满足泰国客户的支付需求，要求使用 Ksher (开时支付)
对接任务突然就给了鄙人，一脸懵 …
通过了解客户的使用场景、以及参考官网指导
发现：Ksher支付最令人满意的便是 —— 提供了便捷的支付 Demo
在此，做下梳理，希望能对小伙伴有所帮助，欢迎指摘 …
场景要求

满足在手机 H5 页面，能在商品下单后，弹出支付二维码 (promptPay、trueMoney、card、wechat) , 引导去支付

简单介绍

  Ksher 成立于 2016 年，由红杉资本和 Infinity 投资，
  在 11 个国家设立运营公司，聚焦东南亚，为全球 150,000+ 企业提供支付服务。
  ksher 专注东南亚市场、深耕出口卖家生态，帮助中国卖家安全、高效、便捷地处理东南亚电商结算货款

官方文档

【API 开发文档 >>>】
【SDK Support >>> 】 （满足 Java、Python、Go、PHP、Netcore、NodeJs）

`☛ 开发步骤`

当前需求，是要满足在手机 H5 页面，能在商品下单后，弹出支付二维码 (promptPay、trueMoney、card、wechat) , 引导去支付

`①. 确认支付场景，选取参考代码`

以我的场景需求和实际操作，想实现 H5页面的 Ksher支付，那么参考 【PHP - SDK Demo >>>】 中的 gateway_pay(WebSite) 这一部分即可

demo 演示页面如下：

`②. 代码整合SDK`

以我使用的 Yii2 框架 为例，将 php-sdk 文件放在了 common目录

在提取使用时，其实就是对 ksher_pay_sdk.php 文件的 KsherPay类的使用
为了避免直接改动 sdk 文件（方便出错排查），
我复制了一份 ksher_pay_sdk文件，稍作个文件名和命名空间变动即可：

`③. 实现下单流程`

提取核心下单逻辑代码，封装处理如下

    /**
     * @Notes:处理获取 Ksher支付数据 (gateway_pay 方式)
     * @param string $ksher_pay_order_sn	唯一的订单编号
     * @param int $ksher_sum_pay_amount		订单金额，例：25.50
     * @return array
     * @User: zhanghj
     * @DateTime: 2023-12-22 11:57
     */
    public function dealGetKsherGatewayPayData($ksher_pay_order_sn = '',
                                        $ksher_sum_pay_amount = 0){
        $err_msg = '';
        $ksher_data = [];
        $ks_appid = PayMzConfig::KSHER_APP_ID;
        $ks_privatekey = PayMzConfig::KSHER_PRIVATE_KEY;
        $class = new KsherPay($ks_appid,$ks_privatekey);

        $gateway_pay_data = array(
            'mch_order_no' => $ksher_pay_order_sn,
            "total_fee" => round($ksher_sum_pay_amount, 2) * 100,
            "fee_type" => 'THB',    //默认为泰铢
            "channel_list" => 'promptpay,truemoney,card,wechat',   //支付方式 wechat
            'mch_code' => $ksher_pay_order_sn,
            'mch_redirect_url' => 'http://www.ksher.cn',
            'mch_redirect_url_fail' => 'http://www.ksher.cn',
            'product_name' => PayMzConfig::KSHER_SHOW_PAY_PRODUCT_NAME,
            'refer_url' => 'http://www.ksher.cn',
            "mch_notify_url" => PayMzConfig::KSHER_H5_ORDER_PAY_NOTIFY,
            'device' => 'H5' //H5(手机端)、PC(电脑端)
        );
        $gateway_pay_response = $class->gateway_pay($gateway_pay_data);
        $gateway_pay_array = json_decode($gateway_pay_response, true);

        if (isset($gateway_pay_array['data']['pay_content'])) {
            $ksher_data['pay_link'] = $gateway_pay_array['data']['pay_content']??'';
        }else{
            $failed_msg = $gateway_pay_array['msg']??'';
            $failed_message = $gateway_pay_array['message']??'';
            $failed_message = empty($failed_message)?(LanguageMz::CHECK_KSHER_PAY_AWAKE_FAILED):$failed_message;
            $err_msg = $failed_msg?$failed_msg:$failed_message;
        }
        return [$err_msg,$ksher_data];
    }

重点是得到上面的 pay_link 数据，整理反馈给前端数据形式如下：

{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "pay_link": "https://gateway.ksher.com/h5?order_uuid=074ad88ca3c911ee9148525400962f26&lang=en"
    }
}

`④. 实现效果`

点击前面成功生成的支付链接，会直接跳转到 Ksher 支付唤醒页面，如下为 H5 页面（PC端同理）

提示：测试发现，如果手机端使用微信打开，会默认唤醒微信支付界面，同时支付金额自动由泰铢转化为人民币

`⑤. 支付回调处理`

对于支付回调的处理，参考 sdk 中提供的 demo_notify.php 文件代码进行实现

根据业务功能，整理支付回调接口，处理如下：

    /**
     * @Notes:Ksher H5订单支付回调接口 （正式）
     * @User: zhanghj
     * @DateTime: 2023-12-22 11:46
     */
    public function actionKsherH5OrderNotify(){
        //1.接收参数
        $input = file_get_contents("php://input");
        $query = urldecode($input);
        if( !$query){
        	//记录日志信息
            CommonMzService::recordLocalFileLog('ksher_pay',"NO RETURN DATA" );
            echo json_encode(array('result'=>'FAIL',"msg"=>'NO RETURN DATA'));
            exit;
        }

        //2.验证参数
        $data_array = json_decode($query,true);
        CommonMzService::recordLocalFileLog('ksher_pay',"notify data :".json_encode( $data_array) );
        if( !isset( $data_array['data']) || !isset( $data_array['data']['mch_order_no']) || !$data_array['data']['mch_order_no']){
            echo json_encode(array('result'=>'FAIL',"msg"=>'RETURN DATA ERROR'));
            exit;
        }

        //3.处理订单
        if( array_key_exists("code", $data_array)
            && array_key_exists("sign", $data_array)
            && array_key_exists("data", $data_array)
            && array_key_exists("result", $data_array['data'])
            && $data_array['data']["result"] == "SUCCESS"){
            $ks_appid = PayMzConfig::KSHER_APP_ID;
            $ks_privatekey = PayMzConfig::KSHER_PRIVATE_KEY;
            $class = new KsherPay($ks_appid,$ks_privatekey);
            //3.1验证签名
            $verify_sign = $class->verify_ksher_sign($data_array['data'], $data_array['sign']);

            if( $verify_sign==1 ){
                //更新订单信息 change order status
                $pay_order_sn = $data_array['data']['mch_order_no'];
                $channel = $data_array['data']['channel']??'';
                $total_fee = $data_array['data']['total_fee']??'';
                $payment_json_str = json_encode($data_array,JSON_UNESCAPED_UNICODE);
                //TODO 此处为我的业务处理，可根据自己的业务，替换更新 ...
                (new PayMzService())->dealUpdateKsherGatewayPayOrder($pay_order_sn,$payment_json_str,$channel,$total_fee);
                echo json_encode(array('result'=>'SUCCESS',"msg"=>'OK'));
            } else {
                CommonMzService::recordLocalFileLog('ksher_pay','VERIFY_KSHER_SIGN_FAIL');
                echo json_encode(array('result'=>'Fail',"msg"=>'VERIFY_KSHER_SIGN_FAIL'));
            }
        }
    }

`附录`

1. 为什么手机端的 H5 页面支付场景会是显示支付二维码？

  通过了解，泰国常用的APP并非微信、支付宝，他们常用的支付APP 为 promptPay、trueMoney、VISA 等
  在H5页面，可以截图需要支付的二维码，打开支付APP，进行识别支付即可
  个人感觉，没有微信（国内）和支付宝使用方便

2. 源代码中，提到的 `PayMzConfig` 为支付配置类，方便后期对 `Ksher` 支付配置信息的改动

摘取部分代码如下：

<?php
namespace common\enum;
/**
 * Mz 专用开发配置
 * Class PayMzConfig
 * @package common\enum
 */
class PayMzConfig {

    //=================Ksher支付配置=============
    const KSHER_APP_ID = 'mch4XXXX';    //应用ID
    //私钥
    const KSHER_PRIVATE_KEY = <<<EOD
-----BEGIN RSA PRIVATE KEY-----
MIICYAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXGk34+n
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
u9UlGXXXXXXXXXXXXXXXXXXXXXXXXXXXXp9xJa
-----END RSA PRIVATE KEY-----
EOD;
    const KSHER_SHOW_PAY_PRODUCT_NAME = 'HWAPPU-Water';
    //TODO 配置为自己的支付回调接口
    const KSHER_H5_ORDER_PAY_NOTIFY = 'http://clientapi.xxxxx.com/notify/ksher_h5_order_notify';
}

3. 对于支付回调接口中提到的`recordLocalFileLog()`方法，可根据自己的代码，放在合适位置

    /**
     * @Notes:记录本地文件 日志信息
     * @param string $op_type
     * @param string $log_content
     * @return bool
     * @User: zhanghj
     * @DateTime: 2023-12-22 13:59
     */
    public static function recordLocalFileLog($op_type = '',$log_content = '') {
        $time_stamp = date("Y-m-d H:i:s", time());
        if( !$log_content ) return false;
        if ($op_type == 'ksher_pay'){
            $log_file_name = 'ksher_pay';
        }else{
            $log_file_name = 'mz';
        }
        $file = dirname(Yii::$app->basePath)."/api/log/{$log_file_name}_".date("Ymd").".txt";
        $handle = fopen( $file, 'a+');
        fwrite( $handle , "[{$time_stamp}]: ".$log_content."\r");
        fclose( $handle );
    }