FreedomPay Integration

A payment gateway is a software program that sits between the merchant and customer, often supplied and hosted by a third-party provider. It offers a secure pathway that requests and manages payment in order to take money from the customer and pass it into the merchant’s bank account.  It’s often described as ‘an electronic cash register for the virtual world’.

Not all solutions are created equally. FreedomPay has worked for over a decade creating the world’s leading library of integration payment toolkits to join our platform. Find out why leading companies are choosing, and winning with FreedomPay.

Now we start the steps how to integrate the freedompay.

 

First Step:

You need to buy freedompay merchant account. then freedom team provides 3 authentications.

1. Terminal ID
2. Store ID
3. ESKey

ESKey: you can get the eskey from Enterprise Dashboard of freedompay account.

 

Second Step:

Create Session

First of all we need to create session key. Read from freedompay api documentation (https://hpc2.uat.freedompay.com/api/swagger/ui/index#/12647session) 

API URL : https://hpc2.uat.freedompay.com/api/v2/session/initialize

API Parameters : 

{ "PaymentFlow": "Direct", "Platform": "Web", "ConsumerAuthentication": { "Enabled": false}, "CultureCode": "en-US", "RequestMessage": { "storeId": "your_id_string", "terminalId": "your_id_string", "esKey": "your_key_string" } }

PHP Code Example:

$url = "https://hpc2.uat.freedompay.com/api/v2/session/initialize";

  $ConsumerAuthentication = array("Enabled" => false);
  $RequestMessage = array("storeId" => "Your Id", "terminalId" => "Your Id", "esKey" => "Your Key");
  $data = array("PaymentFlow" => "Direct", "Platform" => "Web", "ConsumerAuthentication" => $ConsumerAuthentication, "CultureCode" => "en-US", "RequestMessage" => $RequestMessage);

  $data_json = json_encode($data);

  $curl = curl_init();
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_POSTFIELDS, $data_json);
  curl_setopt($curl, CURLOPT_HTTPHEADER, array(
    'Accept: text/plain',
    'Content-Type: application/json',
  ));
  curl_setopt($curl, CURLOPT_HEADER, 0);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($curl, CURLOPT_TIMEOUT, 1000);

  $res = curl_exec($curl);
  $tokken = json_decode($res, false);

Output : { "messages": [ { "Code": "NotSpecified", "Message": "string", "Type": "Unknown" } ], "access_token": "eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiaXYiOiJueEh4RUdiWVZHTVZ2eEdPI iwidGFnIjoiVmE0dDk2eEowV3B5MVp1bVgtLU1HdyIsInppcCI6IkRFRiJ9", "expires_in": 0, "token_type": "string", "StatusCode": "Continue" }

you can see the output session key name as access_token.

 

Third Step : 

Now you need to call payment api for transaction you can see the freedompay api documentation (https://hpc2.uat.freedompay.com/api/swagger/ui/index#!/12647payments/Payments_Post_V1_3).

API URL : https://hpc2.uat.freedompay.com/api/v1.5/payments

API HEADERS :  'Content-Type: application/x-www-form-urlencoded',
    'Authorization: Bearer SessionKey/Access_Token',

API Parameters : 

{
  "PosSyncAttemptNum": 0,
  "PosSyncId": "string",
  "RequestMessage": {
    "storeId": "string",
    "terminalId": "string",
    "esKey": "string",

    "card": {
      "accountNumber": "string",
      "cvNumber": "string",
      "expirationMonth": "string",
      "expirationYear": "string",
      "nameOnCard": "string",
    },

    "purchaseTotals": {
      "currency": "string",
      "taxTotal": "string",
      "chargeAmount": "string"
    }
}

Details of the payment request including the payment key and FreeWay RequestMessage must be URL encoded prior to submission.

• The merchant must send this PosSyncId from their server to FreedomPay’s server. The PosSyncId is a unique payment identifier that helps Time-Out Requests get through to FreeWay during bad internet connectivity. This PosSyncId must never be made visible to the client browser, or anywhere outside of the merchant server to FreedomPay server communication. © 2021 FreedomPay | www.freedompay.com 36

• The merchant must also include the PosSyncAttemptNum. This value must start with “1” and it must be incremented by one every time the merchant wants to retry a payment request (it’s a counter for the number of attempts that have been made).

PosSyncId Format:

The PosSyncId is formatted like the following: Where:

• ISO8601 Timestamp – This must be the UTC timezone moment of the initial payment request to HPC. This should be at a millisecond precision.

• StoreId – The StoreId of the POS.

• TerminalId – The TerminalId of the POS.

• Guid – This value may be any unique string, but a GUID is recommended because it adds lots of randomness to the ID.

For example, if a merchant wanted to submit a payment request for an ecommerce application with a StoreId=123456 and TerminalId=2, the PosSyncId would look like the following:

2019-06-26T04:47:55.196Z;123456;2;434fffa8-5c66-465f-9882-eb5d3b8ee016

PHP Sample Code:

function API_Call($T)
{

  function GUID()
  {
    if (function_exists('com_create_guid') === true) {
      return trim(com_create_guid(), '{}');
    }

    return sprintf('%04X%04X-%04X-%04X-%04X-%04X%04X%04X', mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(16384, 20479), mt_rand(32768, 49151), mt_rand(0, 65535), mt_rand(0, 65535), mt_rand(0, 65535));
  }
  $guid = GUID();

  $url1 = "https://hpc.uat.freedompay.com/api/v1.5/payments";

  $Payment_data = array(
    'PosSyncAttemptNum' => 'PosSyncAttemptNum',
    'PosSyncId' => date("Y-m-d H:i:s", time() - date("Z")) . '.917Z;1511815019;2513533015;' . $guid,
    'RequestMessage' =>
    array(
      'storeId' => 'your_id_here',
      'terminalId' => 'your_id_here',
      'esKey' => 'your_key_here',
      'purchaseTotals' =>
      array(
        'currency' => 'USD',
        'taxTotal' => '0',
        'chargeAmount' => 'Total_Charges',
      ),
      'card' =>
      array(
        'accountNumber' => 'Credit_Card_Number',
        'cvNumber' => 'Security_Code',
        'expirationMonth' =>'Month',
        'expirationYear' => 'Year',
        'nameOnCard' => 'Name',
      ),
      'items' =>
      array(
        '0' =>  array(
          'discountAmount' => '0',
          'discountFlag' => 'N',
        )
      ),
      'merchantReferenceCode' => 'MRC101',
      'ccAuthService' =>
      array(
        'transType' => '',
        'enableAVS' => 'Y',
        'run' => 'true',
        'commerceIndicator' => 'moto',
      ),
      'billTo' =>
      array(
        'postalCode' => 'Postal_Code',
        'phoneNumber' => 'Telephone',
      ),
      'clientMetadata' =>
      array(
        'sellingMiddlewareName' => 'ARFASOFTECH',
        'sellingMiddlewareVersion' => '1.0',
      ),
    ),
  );

  $Response_json = http_build_query($Payment_data);

  $curll = curl_init();
  curl_setopt($curll, CURLOPT_URL, $url1);
  curl_setopt($curll, CURLOPT_POST, true);
  curl_setopt($curll, CURLOPT_POSTFIELDS, $Response_json);
  curl_setopt($curll, CURLOPT_HTTPHEADER, array(
    'Content-Type: application/x-www-form-urlencoded',
    'Authorization: Bearer ' . $T,
  ));
  curl_setopt($curll, CURLOPT_HEADER, 0);
  curl_setopt($curll, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($curll, CURLOPT_TIMEOUT, 1000);

  $new_res = curl_exec($curll);
  $AuthRequestID = json_decode($new_res);

  // print_r($new_res);

  if ("ACCEPT" != $AuthRequestID->FreewayResponse->decision) {
    $Payment_data["PosSyncAttemptNum"] = $Payment_data["PosSyncAttemptNum"] + 1;
    echo json_encode(["Error$", $AuthRequestID->FreewayResponse->decision]);
  } else {
    $RequestID = $AuthRequestID->FreewayResponse->ccAuthReply->authRequestID;
    echo json_encode(["AuthRequestID$", $RequestID]);
  }
  // echo $GLOBALS['PosSyncAttemptNum'];
  // echo "


API: ".$AuthRequestID -> FreewayResponse -> ccAuthReply -> authRequestID;

}

API_Call('eyJhbGciOiJBMjU2R0NNS1ciLCJlbmMiOiJBMjU2Q0JDLUhTNTEyIiwiaXYiOiJueEh4RUdiWVZHTVZ2eEdPI iwidGFnIjoiVmE0dDk2eEowV3B5MVp1bVgtLU1HdyIsInppcCI6IkRFRiJ9');

 

Note: if freeway decision reponse i accepted then you can check your transaction in freedompay enterprise dashboard. if decision is error or reject then you can try again to call payment api with increamented PosSyncAttemptNum.

After successfull transaction you can change the test url with live url.

(https://hpc2.freedompay.com/api/v2/session/initialize)

(https://hpc2.freedompay.com/api/v1.5/payments)

 

Thanks for reading this article.