mycoolpay / php-sdk
My-CoolPay official SDK for PHP
Requires
- php: >=5.4
- ext-curl: *
- ext-json: *
- mycoolpay/php-rest-client: ^1.0
This package is auto-updated.
Last update: 2024-11-07 16:16:47 UTC
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.
Table of contents
- 1. Requirements
- 2. Installation
- 3. Interact with API
- 4. Security helpers
- More assistance
- Contributors
1. Requirements
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:
MyCoolPayClient constructor parameters:
MyCoolPayClient($public_key, $private_key, $logger = null, $debug = false)
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 💬