README

My-CoolPay 官方 PHP SDK

注意

此 PHP 包允许您轻松地将 My-CoolPay 支付 API 集成到您的应用程序或网站中。在开始使用此包之前，强烈建议您根据您的用例检查以下资源。

• My-CoolPay API 文档
• My-CoolPay WordPress 文档

目录

• 1. 要求
• 2. 安装
• 3. 与 API 交互
  • 3.1. 支付链接
  • 3.1. 收款
  • 3.1. 验证码
  • 3.1. 提款
  • 3.1. 检查状态
  • 3.1. 获取余额
• 4. 安全助手
  • 4.1. IP 验证
  • 4.1. 回调请求完整性
• 更多帮助
• 贡献者

1. 要求

此包需要：

2. 安装

2.1. 安装 Composer 包

首先，从您的 CMD 或终端安装 Composer 包。

$ composer require mycoolpay/php-sdk

2.2. 初始化 SDK 对象

现在您需要使用您的 API 密钥初始化 SDK 对象。

<?php

require_once "vendor/autoload.php";

use MyCoolPay\Logging\Logger;
use MyCoolPay\MyCoolPayClient;

define("MCP_PUBLIC_KEY", "<Add your public key here>"); // Your API public key
define("MCP_PRIVATE_KEY", "<Add your private key here>"); // Your API private key

$logger = new Logger('app.log', __DIR__);
$mycoolpay = new MyCoolPayClient(MCP_PUBLIC_KEY, MCP_PRIVATE_KEY, $logger, true);

建议

• 最好将您的密钥保存在源代码外部，例如在环境变量中，然后从源代码中加载它们
• 日志对象是可选的，用于调试目的。有关 My-CoolPay 日志类的更多信息，请参阅 My-CoolPay PHP Logger
• 日志和 MyCoolPayClient 对象不需要每次需要时都实例化，只需实例化一次（在应用程序启动时或首次使用时）然后在整个应用程序中通过 Singleton 或依赖注入模式共享实例

日志构造函数参数

请参阅 My-CoolPay PHP Logger

MyCoolPayClient 构造函数参数

MyCoolPayClient($public_key, $private_key, $logger = null, $debug = false)

3. 与 API 交互

3.1. 支付链接

<?php

use Exception;

try {
    $response = $mycoolpay->paylink([
        "transaction_amount" => 100,
        "transaction_currency" => "XAF",
        "transaction_reason" => "Bic pen",
        "app_transaction_ref" => "order_123",
        "customer_phone_number" => "699009900",
        "customer_name" => "Bob MARLEY",
        "customer_email" => "bob@mail.com",
        "customer_lang" => "en",
    ]);
    
    $transaction_ref = $response->get("transaction_ref"); // You can store this reference to order in your database
    
    $payment_url = $response->get("payment_url"); // Redirect customer to this url

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

paylink(array $data): MyCoolPay\Http\Response

• @param array $data
• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

数据描述

有关完整的 $data 描述，请参阅 API 文档中的支付链接部分

3.2. 收款

<?php

use Exception;

try {
    $response = $mycoolpay->payin([
        "transaction_amount" => 100,
        "transaction_currency" => "XAF",
        "transaction_reason" => "Bic pen",
        "app_transaction_ref" => "order_123",
        "customer_phone_number" => "699009900",
        "customer_name" => "Bob MARLEY",
        "customer_email" => "bob@mail.com",
        "customer_lang" => "en",
    ]);
    
    $transaction_ref = $response->get("transaction_ref"); // You can store this reference to order in your database
    
    $action = $response->get("action"); // This tells you what to do next
    
    if ($action === "REQUIRE_OTP") {
        // Ask your user to provide OTP received by SMS
        // Then perform OTP request (see next section)
    } elseif ($action === "PENDING") {
        $ussd = $response->get("ussd"); // Tell user to dial this USSD code on his phone
    } else {
        throw new Exception("Unknown action '$action' in Payin response");
    }

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

payin(array $data): MyCoolPay\Http\Response

• @param array $data
• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

数据描述

有关完整的 $data 描述，请参阅 API 文档中的收款部分

3.3. 验证码

<?php

use Exception;

try {
    $response = $mycoolpay->authorizePayin([
        "transaction_ref" => "f4fd89ea-e647-462c-9489-afc0aeb90d5f",
        "code" => "123456",
    ]);
    
    $action = $response->get("action"); // This tells you what to do next
    
    if ($action === "PENDING") {
        $ussd = $response->get("ussd"); // Tell user to dial this USSD code on his phone
    } else {
        throw new Exception("Unknown action '$action' in OTP response");
    }

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

authorizePayin(array $data): MyCoolPay\Http\Response

• @param array $data
• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

数据描述

有关完整的 $data 描述，请参阅 API 文档中的验证码部分

3.4. 提款

<?php

use Exception;
use MyCoolPay\Http\Http;

try {
    $response = $mycoolpay->payout([
        "transaction_amount" => 500,
        "transaction_currency" => "XAF",
        "transaction_reason" => "Customer refund",
        "transaction_operator" => "CM_OM",
        "app_transaction_ref" => "refund_123",
        "customer_phone_number" => "699009900",
        "customer_name" => "Bob MARLEY",
        "customer_email" => "bob@mail.com",
        "customer_lang" => "en",
    ]);
    
    $transaction_ref = $response->get("transaction_ref"); // You can store this reference to payout in your database
    
    $status_code = $response->getStatusCode(); // HTTP status code
    $message = $response->getMessage();
    
    if ($status_code === Http::OK) {
        // Successful payout
    } elseif ($status_code === Http::ACCEPTED) {
        // Payout is pending in background
    } else {
        throw new Exception($message, $status_code);
    }

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

payout(array $data): MyCoolPay\Http\Response

• @param array $data
• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

数据描述

关于完整的 $data 描述，请查看 API 文档中的支付部分

3.5. 检查状态

<?php

use Exception;

try {
    $response = $mycoolpay->checkStatus("f4fd89ea-e647-462c-9489-afc0aeb90d5f");
    
    $status = $response->get("transaction_status");
    
    // Do whatever you need with $status
    // Possible values are PENDING, SUCCESS, CANCELED and FAILED

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

checkStatus(string $transaction_ref): MyCoolPay\Http\Response

• @param string $transaction_ref
• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

更多信息

更多详细信息，请查看 API 文档中的状态部分

3.6. 获取余额

<?php

use Exception;

try {
    $response = $mycoolpay->getBalance();
    
    $balance = $response->get("balance");
    
    // Do whatever you need with $balance

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

getBalance(): MyCoolPay\Http\Response

• @return MyCoolPay\Http\Response
• @throws MyCoolPay\Http\Exception\HttpException

更多信息

更多详细信息，请查看 API 文档中的余额部分

4. 安全助手

4.1. IP 验证

<?php

use Exception;

try {
    // Adapt this to the framework you are using to get requester IP address
    $remote_ip = $_SERVER['REMOTE_ADDR'];
    
    if ($mycoolpay->isVerifiedIp($remote_ip)) {    
        // Process callback
    }

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

isVerifiedIp(string $ip): true

• @param string $ip
• @return true
• @throws MyCoolPay\Exception\UnknownIpException

更多信息

更多详细信息，请查看 API 文档中的安全部分

4.2. 回调请求完整性

<?php

use Exception;

try {
    // Adapt this to the framework you are using to get REST JSON data
    $callback_data = json_decode(file_get_contents('php://input'), true);
    
    if ($mycoolpay->checkCallbackIntegrity($callback_data)) {    
        // Process callback
    }

} catch (Exception $exception) {
    $logger->logException($exception);
}

方法描述

checkCallbackIntegrity(string $callback_data): true

• @param array $callback_data
• @return true
• @throws MyCoolPay\Exception\KeyMismatchException
• @throws MyCoolPay\Exception\BadSignatureException

更多信息

更多详细信息，请查看 API 文档中的安全部分

更多帮助

ℹ️ 如需进一步的信息或帮助，请联系我们的团队 support@my-coolpay.com。您也可以从开发者社区 💬 获取帮助

贡献者

• 数字之家国际
• Willy KOUOGANG
• Samuel BAKON
• Laetitia NGOMTCHO
• Arnold NGASSAM
• Aristide Herve MBASSI
• Aubry Yvan FANDOM