README

My-CoolPay official SDK for PHP

Note

This PHP package let you easily integrate My-CoolPay Payment API to your application or your website. Before you start using this package, it's highly recommended to check resources below depending on your use case.

1. Requirements
2. Installation
3. Interact with API
4. Security helpers
- 4.1. IP verification
- 4.1. Callback request integrity
More assistance
Contributors

1. Requirements

This package requires:

2. Installation

2.1. Install Composer package

First of all, install Composer package from your CMD or your Terminal.

$ composer require mycoolpay/php-sdk

2.2. Initialize SDK object

Now you need to initialize the SDK object with your API keys.

<?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);

Recommendations:

It is better for you to save your keys outside the source code, in places like environment variables and just load them from source code
Logger object is optional, it is used for debug purposes. To know more about My-CoolPay Logger class see My-CoolPay PHP Logger
Both Logger and MyCoolPayClient objects don't need to be instantiated every time you need them, just instantiate them once (either at application startup or at first use) then share the instances within whole app with patterns such as Singleton or Dependency Injection

Logger constructor parameters:

See My-CoolPay PHP Logger

MyCoolPayClient constructor parameters:

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

Parameter	Type	Default	Description
`$public_key`	`string`		Your API public key
`$private_key`	`string`		Your API private key
`$logger`	`?LoggerInterface`	`null`	Logger object
`$debug`	`boolean`	`false`	true enables debug mode

3. Interact with API

3.1. Paylink

<?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);
}

Method description:

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

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

Data description:

For full $data description check Paylink section in API Docs

3.2. Payin

<?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);
}

Method description:

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

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

Data description:

For full $data description check Payin section in API Docs

3.3. OTP

<?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);
}

Method description:

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

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

Data description:

For full $data description check OTP section in API Docs

3.4. Payout

<?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);
}

Method description:

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

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

Data description:

For full $data description check Payout section in API Docs

3.5. Check status

<?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);
}

Method description:

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

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

More information:

For more information check Status section in API Docs

3.6. Get balance

<?php

use Exception;

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

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

Method description:

getBalance(): MyCoolPay\Http\Response

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

More information:

For more information check Balance section in API Docs

4. Security helpers

4.1. IP verification

<?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);
}

Method description:

isVerifiedIp(string $ip): true

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

More information:

For more information check Security section in API Docs

4.2. Callback request integrity

<?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);
}

Method description:

checkCallbackIntegrity(string $callback_data): true

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

More information:

For more information check Security section in API Docs

More assistance

ℹ️ If you need further information or assistance, our teams are available at support@my-coolpay.com. You can also get help from the developer community 💬

mycoolpay / php-sdk

Maintainers

Details

README

Note

Table of contents

1. Requirements

2. Installation

2.1. Install Composer package

2.2. Initialize SDK object

Recommendations:

Logger constructor parameters:

MyCoolPayClient constructor parameters:

3. Interact with API

3.1. Paylink

Method description:

Data description:

3.2. Payin

Method description:

Data description:

3.3. OTP

Method description:

Data description:

3.4. Payout

Method description:

Data description:

3.5. Check status

Method description:

More information:

3.6. Get balance

Method description:

More information:

4. Security helpers

4.1. IP verification

Method description:

More information:

4.2. Callback request integrity

Method description:

More information:

More assistance

Contributors