Safepay custom integration

safepay-integration.md

To integrate with Safepay, you will need a production account and a sandbox account.

Production accounts can be created by visiting this link https://getsafepay.com

Sandbox accounts can be created by visiting this link https://sandbox.api.getsafepay.com

Please take a note of your:

1. Production API Key
2. Production Secret Key
3. Sandbox API Key
4. Sandbox Secret Key

When the customer reaches the payment step, selects pay with Safepay, and clicks Place Order, the plugin should create an order in your system, generate an Order ID and then with the appropriate API key (whether its sandbox or production) make a POST request to Safepay to generate a Payment like so:

$prod_url = "https://api.getsafepay.com";
$sandbox_url = "https://sandbox.api.getsafepay.com";
$url = $env === "sandbox" ? $sandbox_url : $prod_url;

curl --location --request POST $url.'/order/v1/init' \
--header 'Content-Type: application/json' \
--data-raw '{
"client": "sec_c18b707b-bd0f-41fe-947a-e894adf81e20",
"amount": 1000.00,
"currency": "PKR",
"environment": "sandbox" ("sandbox" or "production" based on the plugin setting)
}'

This request will return the following response

{
  "data":{
    "token":"track_a323b3d5-c9e8-410f-9020-6f3a9395f13e",
    "created_at":"2019-12-23T20:28:54Z",
    "updated_at":"2019-12-23T20:28:54Z",
    "user":"",
    "billing":"",
    "client":"sec_c18b707b-bd0f-41fe-947a-e894adf81e20",
    "environment":"local",
    "state":"TRACKER_STARTED",
    "state_reason":"",
    "amount":10,
    "currency":"USD",
    "default_currency":"PKR",
    "conversion_rate":153.37580742
  },
  "status":{
    "errors":[

    ],
    "message":"success"
  }
}

Upon receiving the response extract the "token" property from the JSON payload and use it to construct the following URL like so:

const PRODUCTION_CHECKOUT_URL = "https://www.getsafepay.com/components";
const SANDBOX_CHECKOUT_URL = "https://sandbox.api.getsafepay.com/components";

function construct_url($order, $tracker="")
{
  $baseURL = $this->sandbox ? self::SANDBOX_CHECKOUT_URL : self::PRODUCTION_CHECKOUT_URL;
  $params = array(
    "env" => $this->sandbox ? "sandbox" : "production",
    "beacon" => $tracker,
    "source" => 'magento',
    "order_id" => $order->get_id(),
    "redirect_url" => $this->get_success_url(),
    "cancel_url" => $this->get_cancel_url()
  );

  $baseURL = add_query_arg($params, $baseURL);

  return $baseURL;
}

Once the URL is constructed, redirect the user to this URL.

When the user is on the Safepay payment page, if he clicks on "Cancel Payment", Safepay will automatically redirect the user to the "cancel_url". Your application should handle the order cancellation flow including marking the order as cancelled and redirecting the user back to the Checkout page.

If the user completes payment, Safepay will make a POST request via an HTML form with the "action" being the "redirect_url". The following body will be sent to the post request: Order ID (Your Order ID) Reference Code (Safepay Transaction Reference Code) Tracker (Safepay Transaction Tracker Token) Signature (Signed value to prove authenticity of transaction)

The plugin must use the appropriate secret key (whether sandbox or production) to verify the transaction using the following code as example:

public function validate_signature($tracker, $signature)
{
  $secret = $this->get_shared_secret();
  $signature_2 = hash_hmac('sha256', $tracker, $secret);
  if ($signature_2 === $signature) {
    return true;
  }
  return false;
}

If the signature fails validation, your should mark the order as "review" and add a note saying the payment failed validation. Or your app should just cancel the order and redirect the customer back to the checkout page.

If the signature passes validation, your app should save the Safepay Reference Code & Safepay Tracker to your database so that the store owner can reconcile the Order with the payment.

The plugin should then mark the order as complete and redirect the customer to the order confirmed page.

Please refer to the Official Safepay Wordpress plugin for details and code on how to achieve this. https://github.com/getsafepay/safepay-woocommerce

Also refer to the Official Safepay Wordpress Plugin on the wordpress registry for screenshots on how the admin settings should look like: https://wordpress.org/plugins/woo-safepay-gateway/

add_query_arg() is a WordPress function how are we supposed to do it in CorePHP? or Laravel?

How can I create a payout with safepay?