README

用于轻松使用Dohone支付API的PHP 5.4+ SDK。

注意

此PHP包让您轻松将Dohone支付API集成到您的应用程序或您的网站，适用于所有喀麦隆移动支付运营商（MTN Mobile Money、Orange Money和Express Union Mobile Money）。

在开始使用此包之前，强烈建议您阅读以下文档。

1. 要求

此包需要：

2. 安装

2.1. 安装Composer包

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

$ composer require mathermann/dohone-sdk

2.2. 实现TransactionInterface接口

然后您需要一个实现TransactionInterface接口的类。
例如

<?php

namespace Your\Name\Space; // Replace with your namespace

use Mathermann\DohoneSDK\TransactionInterface;

class Transaction implements TransactionInterface
{
    /**
     * Transaction reference (or id) in your system
     */
    private $transactionRef;
    
    /**
     * Transaction operator, must be one of the following values:
     * ['DOHONE_MOMO', 'DOHONE_OM', 'DOHONE_EU', 'DOHONE_TRANSFER']
     */
    private $transactionOperator;
    
    private $transactionAmount;
    
    /**
     * Transaction currency, must be one of the following values:
     * ['XAF', 'EUR', 'USD']
     */
    private $transactionCurrency;
    
    private $transactionReason;
    
    /**
     * Transaction reference in Dohone's system
     */
    private $dohoneTransactionRef;
    
    private $customerName;
    
    private $customerPhoneNumber;
    
    private $customerEmail;
    
    private $customerCountry;
    
    private $customerCity;
    
    /**
     * Notification URL for this transaction
     */
    private $notifyUrl;
    
    // You can add some additional properties...
    
    
    public function getTransactionRef()
    {
        return $this->transactionRef;
    }

    public function getTransactionOperator()
    {
        return $this->transactionOperator;
    }

    public function getTransactionAmount()
    {
        return $this->transactionAmount;
    }

    public function getTransactionCurrency()
    {
        return $this->transactionCurrency;
    }

    public function getTransactionReason()
    {
        return $this->transactionReason;
    }

    public function getDohoneTransactionRef()
    {
        return $this->dohoneTransactionRef;
    }

    public function getCustomerName()
    {
        return $this->customerName;
    }

    public function getCustomerPhoneNumber()
    {
        return $this->customerPhoneNumber;
    }

    public function getCustomerEmail()
    {
        return $this->customerEmail;
    }

    public function getCustomerCountry()
    {
        return $this->customerCountry;
    }

    public function getCustomerCity()
    {
        return $this->customerCity;
    }

    public function getNotifyUrl()
    {
        return $this->notifyUrl;
    }
    
    // add setters...
    
    // you can add some additional methods...
}

3. Payin请求（收集付款）

3.1. 创建DohoneSDK对象

您可以在这里找到DohoneSDK类。

<?php

use Mathermann\DohoneSDK\DohoneSDK;

// constants
define('MERCHANT_KEY', '...'); // your dohone merchant key (required)
define('APP_NAME', '...'); // the name by which your application is recognized at Dohone
define('HASH_CODE', '...'); // your dohone hash code (only if you handle dohone notifications in your system)
define('NOTIFY_URL', '...'); // default notification URL for incoming payments

$dohoneSdk = new DohoneSDK(MERCHANT_KEY, APP_NAME, HASH_CODE, NOTIFY_URL);

// ...

3.2. 发送“COTATION”命令

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try 
{
    /**
     * $transaction is an object of type Transaction defined above,
     * $mode is exactly the same as "levelFeeds" in Dohone's documentation
     */
    $response = $dohoneSdk->quote($transaction, ['mode' => $mode]);
    
    if ($response->isSuccess())
    {
        echo $response->getMessage(); // display result
    }
    else
    {
        echo $response->getMessage(); // display error message
    }                
}
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

3.3. 发送“START”命令

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try
{
    /**
     * $transaction is an object of type Transaction defined above,
     * $OTP is exactly the same as "rOTP" in Dohone's documentation, required only for Orange Money payment
     */
    $response = $dohoneSdk->start($transaction, ['OTP' => $OTP]);
    
    if ($response->isSuccess())
    {
        if ($response->hasREF()) {
            // ToDo: handle success
        }
        else if ($response->needCFRMSMS()) {
            // ToDo: request SMS confirmation code to user
        }
    }
    else
    {
        echo $response->getMessage(); // display error message
    }                
}
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

3.4. 发送“CRFMSMS”命令

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try
{
    /**
     * $transaction is an object of type Transaction defined above,
     * $code is exactly the same as "rCS" in Dohone's documentation
     */
    $response = $dohoneSdk->confirmSMS($transaction, ['code' => $code]);
    
    if ($response->isSuccess())
    {
        if ($response->hasREF()) {
            // ToDo: handle success
        }
        else if ($response->needCFRMSMS()) {
            // ToDo: request SMS confirmation code to user
        }
    }
    else
    {
        echo $response->getMessage(); // display error message
    }                
}
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

3.5. 发送“VERIFY”命令

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try
{
    /**
     * $transaction is an object of type Transaction defined above
     */
    $response = $dohoneSdk->verify($transaction);
    
    if ($response->isSuccess()) {
        // ToDo: handle OK
    }
    else {
        // ToDo: handle NO
    }                
} 
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

3.6. 处理Dohone通知

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

// convert data into more readable format
/**
 * $notificationData is data received from the request, it can be
 * $_GET if you use vanilla PHP,
 * $request->query->all() if you use Symfony or
 * Input::all() if you use Laravel
 */
$data = $dohoneSdk->mapNotificationData($notificationData);

// check for request integrity
if ($dohoneSdk->checkHash($data))
{
    // fill new Transaction() with data and check if Dohone recognizes the transaction
    try
    {
        /**
         * $transaction is an object of type Transaction defined above
         */
        $response = $dohoneSdk->verify($transaction);
        
        if ($response->isSuccess()) {
            // ToDo: handle OK
        }
        else {
            // ToDo: handle NO (or just ignore the request)
        }                
    } 
    catch (InvalidDohoneResponseException $e)
    {
        echo $e->getMessage(); // display error message
    }
}

// ...

4. Payout请求（退款或提款）

4.1. 创建DohonePayoutSDK对象

您可以在这里找到DohonePayoutSDK类。

<?php

use Mathermann\DohoneSDK\DohonePayoutSDK;

// constants
define('ACCOUNT', '...'); // the phone number of your Dohone account (required)
define('HASH_CODE', '...'); // your dohone hash code (required)
define('NOTIFY_URL', '...'); // default notification URL for payouts

$dohonePayoutSdk = new DohonePayoutSDK(ACCOUNT, HASH_CODE, NOTIFY_URL);

// ...

4.2. 发送“COTATION”命令

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try 
{
    /**
     * $transaction is an object of type Transaction defined above
     */
    $response = $dohonePayoutSdk->quote($transaction);
    
    if ($response->isSuccess())
    {
        echo $response->getMessage(); // display result
    }
    else
    {
        echo $response->getMessage(); // display error message
    }                
}
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

4.3. 进行转账

<?php

// ...

use Mathermann\DohoneSDK\InvalidDohoneResponseException;

try
{
    /**
     * $transaction is an object of type Transaction defined above
     */
    $response = $dohonePayoutSdk->transfer($transaction);
    
    if ($response->isSuccess() && $response->hasREF()) {
        // ToDo: handle success
    }
    else {
        echo $response->getMessage(); // display error message
    }
}
catch (InvalidDohoneResponseException $e)
{
    echo $e->getMessage(); // display error message
}

// ...

4.4. 处理Dohone的付款通知

<?php

// ...

// convert data into more readable format
/**
 * $notificationData is data received from the request, it can be
 * $_GET if you use vanilla PHP,
 * $request->query->all() if you use Symfony or
 * Input::all() if you use Laravel
 */
$data = $dohonePayoutSdk->mapNotificationData($notificationData);

// ToDo: handle notification

// ...

致谢

mathermann

mathermann / dohone-sdk

维护者

详细信息