May 9, 2019 Knowledge Center

Integrate Monetha into any PHP based e-commerce store: Payment Plugin SDK for PHP

 

This article is technical: it assumes some programming and blockchain knowledge.


You can read more about the SDK and find its source code on our Github repository.


Monetha’s payment gateway was built to let any merchant accept fast, inexpensive, and secure cryptocurrency payments, coupled with a portable and reliable reputation system. Recently, we also included fiat transactions, turning the gateway into a complete payment solution.

To make adoption as frictionless as possible, we have developed plugins for some of the major e-commerce platforms: WooCommerce, PrestaShop, and Magento. They offer a straightforward way to integrate our payment gateway without any programming knowledge.

However, while the three platforms cover the majority of the market, there are merchants who use different services. They find themselves unable to integrate our gateway—and that’s, of course, a problem for us.

For a while, our way to overcome it would be to offer the “Buy Now” button functionality. It’s a brilliant little tool, and it gets the job done. But the button has its limitations; and in some cases, it might fall a little short of substituting proper integration.

That’s why we’ve come up with another method to bring Monetha payments into the hands (and e-shops) of merchants. It’s called the Payment Plugin PHP SDK, and you can use it to integrate the gateway into any PHP based e-commerce store—granted, some programming chops will be needed.

What is it, exactly?

Monetha’s Payment Plugin PHP SDK is a wrapper around our API that uses our infrastructure to process cryptocurrency and fiat payments. In other words, it’s the IKEA build-it-yourself version of our pre-packaged plugins. This SDK is used in all the plugins we have built and continue to maintain.

The SDK provides:

– Interfaces that need to be implemented in order to ensure interoperability of data between your e-commerce store and Monetha’s Payment Gateway API
– Definitions of request and response payloads to communicate with Monetha’s Payment Gateway API

Here’s a visual representation of how our PHP SDK is structured:

How do I use the SDK?

The following sequence diagrams show a general concept of the main flows of the SDK when integrating it into your e-commerce store. More usage scenarios may apply in your particular case. Feel free to contact us if any guidance is needed.

Making a purchase

workflow-purchase.png

Canceling an order

workflow-cancel-order.png

Synchronizing data between platforms

To keep your e-shop in sync with order changes in Monetha’s payment gateway, we trigger webhooks whenever an order state changes. There are three events that trigger a webhook. They take place in different stages of an order’s lifecycle and inform the e-commerce platform to update the order status:

  • – order.canceled – pretty self-explanatory.
  • – order.finalized – the order was paid for in the payment page where the user was redirected.
  • – order.money_authorized – the order was paid for by card (which was successfully authorized).

Code examples

In order to make the onboarding easier, we’ve prepared a full example index.php which demonstrates how to:

– Make a purchase
– Cancel an order
– Process a webhook

Below are some excerpts from the file. This is what creating an order looks like:

// Sign up at Monetha to become a Merchant - https://help.monetha.io/hc/en-us/categories/360000271031#article=Preliminary-steps
// After completing the sign up you visit your Merchant Cabinet
// Payment > Payment settings and copy paste the following
$merchantSecret = 'MONETHA_MERCHANT_SECRET';
$apiKey = 'MONETHA_MERCHANT_API_TOKEN';

// testMode - is a flag describing that shop will be run in Ropsten.
// Meaning that no true crypto currency will be used
$testMode = true;

// by using Monetha\ConfigAdapterTrait inside Config class
// and setting those private variables from arguments,
// you are actually implementing Monetha\Adapter\ConfigAdapterInterface
// which is required to construct Monetha\Services\GatewayService
$config = new Config(
    $merchantSecret,
    $apiKey,
    $testMode
);

$gateway = new GatewayService($config);

try {
    // optional and could be called only when updating Monetha's API settings
    $gateway->validateApiKey();

    // Prepare an Offer by signing the Order information
    // This information will be used during Order execution
    // You might need to repeat this step if your order information is updated
    // It is advised to execute this API call on a Checkout page
    $createOfferResponse = $gateway->createOffer($order, $client);
    $token = $createOfferResponse->getToken();

    // Execute the signed Offer. It is best to execute following method 
    // on “Pay now” button press
    $executeOfferResponse = $gateway->executeOffer($token);

    // After an Order was executed an E-shop must redirect a user
    // to payment page. A payment url is unique for each order 
    // and can be retrieved as follows
    $paymentUrl = $executeOfferResponse->getPaymentUrl();

    // It is best to retrieve and store a back reference to 
    // Monetha Order. You can achieve that by reading the response payload
    // of Order execution call
    $monethaOrder = $executeOfferResponse->getOrder();

} catch(ApiException $e) {
    error_log(
        'Status code: ' . $e->getApiStatusCode() .
        ', error: ' . $e->getApiErrorCode() .
        ', message: ' . $e->getMessage()
    );

    echo $e->getFriendlyMessage();

    return;
}

header('Location: ' . $paymentUrl);

And here’s how you can cancel an order:

try {
    $monethaOrderId = $executeOfferResponse->getOrderId();
    $jsonResponse = $gateway->cancelExternalOrder($monethaOrderId)->getResponseJson();
    if ($jsonResponse->order_status->name == 'OrderCanceled') {
        // TODO: Make any shop specific actions
        echo 'Order cancelled.';
    }

} catch(ApiException $e) {
    error_log(
        'Status code: ' . $e->getApiStatusCode() .
        ', error: ' . $e->getApiErrorCode() .
        ', message: ' . $e->getMessage()
    );

    echo 'Cannot cancel the order. ' . $e->getFriendlyMessage();

    return;
}

That’s all for our short overview of the Payment Plugin PHP SDK. We welcome any suggestions or improvements. If you have any questions, shoot us an email at [email protected].

Thank you for reading!


If you would like to learn more about the SDK or access its source code, have a look at our Github repository.

The SDK is part of Monetha’s Decentralized Reputation Framework. You can read about it here.

 

Share