Paygol module for BoxBilling, version 1.2

 

Requirements

 

Installation

  • Download BoxBilling module.
  • Unzip paygol-for-boxbilling_1.2.zip file directly into your BoxBilling directory.
  • Install your Paygol module using your BoxBilling admin dashboard (Configuration -> Payment Gateways -> New payment gateway), look for “Paygol” and click on “Install“.
  • Once installed, setup the module (Configuration -> Payment Gateways), select “Paygol” and click on Edit Icon (Pencil Icon).
  • Log into your Paygol Dashboard and go to “Notifications” section, copy the Service ID and Secret Key from your account and paste them into the corresponding fields at the module’s setup page on your BoxBilling site.
  • Copy the “IPN Callback URL” from your Paygol’s module setup and paste it into the “IPN URL” field at the “Notifications” section of your Paygol dashboard, then save the changes.
  • Make sure the module is configured as follows:
    • “Enabled: Yes“.
    • “Allow one time payments: Yes“.
    • “Enable test mode: No
  • Click on “UPDATE” on your BoxBilling site to save the changes.

 

Testing

To test the newly installed module you can enable your service’s test mode clicking the button “Live/Test” at the upper-right corner of your screen in your Paygol’s dashboard website, Be sure to change it back before going live.

 

Paygol button image

To ensure all instances of the Paygol button will work correctly, please follow these instructions:

  • Edit “logos.css” from your BoxBilling installation. This file can be found at “bb-themes/huraga/assets/css/logos.css“.
  • Add the following lines to the end of the file “logos.css“ and save changes:
    .logo-PayGol{
         background: transparent url("../img/gateway_logos/PayGol.png") no-repeat scroll 0% 0%;
         background-size: contain;
         width:80px;
         height: 28px;
         border: 0;
         margin: 10px;
    }
    

Please note:

If you are not using the default theme “huraga“, you need to do the following:

  • Modify the CSS file in the right folder, not inside “huraga“. e.g. “bb-themes/theThemeImUsing/assets/css/logos.css“.
  • Copy the logo image from “bb-themes/huraga/assets/img/gateway_logos/Paygol.png” to a similar path for the other theme.                                            e.g: “bb-themes/theThemeImUsing/assets/img/gateway_logos/Paygol.png“.
  • There’s an alternative way to the previous steps, just rename the folder “huraga” and name it as your new theme folder. This change should be done before you copy the Paygol module to your BoxBilling directory.

 

Important Notes

  • While in test mode, an IPN request (payment notification) will be issued immediately to your platform after each test.
  • Once a payment is completed it will be shown as completed but with “Pending Setup” status, until you activate it at your BoxBilling panel.
  • Payments are usually notified immediately; however, certain payment methods may take longer to confirm the payment (e.g. methods that take a few minutes to notify the transaction, or voucher-based transactions that require the payer to print it in order to pay by cash at a given place). We strongly recommend that you inform your customers about this beforehand in order to avoid confusions.
Basic Implementation

 

How to use the Basic Implementation
Parameters description
How to test your service


 


How to use the basic implementation

The code below is ready to use. Just copy the piece of code into your web page, replace the values with your own and you will be ready to go.

<form name="pg_frm" method="post" action="https://www.paygol.com/pay" >
   <input type="hidden" name="pg_serviceid" value="123">
   <input type="hidden" name="pg_currency" value="EUR">
   <input type="hidden" name="pg_name" value="DEMO">
   <input type="hidden" name="pg_custom" value="">
   <input type="hidden" name="pg_price" value="1">
   <input type="hidden" name="pg_return_url" value="">
   <input type="hidden" name="pg_cancel_url" value="">
   <input type="image" name="pg_button" src="https://www.paygol.com/pay-now/images/payment-button.png" border="0" alt="Make payments with Paygol: the easiest way!" title="Make payments with Paygol: the easiest way!" >     
</form>

Parameters description

The following POST/GET parameters are required:

How to test your implementation

On top of your Paygol dashboard you will be able to switch between Live and Test mode. In Test mode you can simulate transactions with no need to spend real money (just click OK on your payment screen and a successful payment will be simulated).

Please note that you don’t need to perform any external actions (such as entering credit card information) in order to test transactions.

 

API Implementation

 

Overview
How to use the API Implementation
Parameters description
Checking the status of a payment


 

Documentation for the implementation API v1.2 is available.

Overview

Our API implementation offers a high level of customization, allowing you to implement an advanced white label payments solution directly on your platform in a fast and easy way.

This implementation is based in POST/GET requests to web-services which will return an XML or JSON response, according to your preference. The response will contain a URL you can redirect your customer to in order to start the payment process.

How to use the API implementation

To create a new payment you must make a request to the following URL:

https://www.paygol.com/pay

Parameters description

The following POST/GET parameters are required:

 

Codes for available payment methods:

Name Coverage Code Description

Example:

<?php

$endpoint_url = 'https://www.paygol.com/pay?';

$params = [
  'pg_mode'=>'api',
  'pg_serviceid'=>123,
  'pg_price'=>10.00,
  'pg_currency'=>'EUR',
  'pg_custom'=>'player123',
  'pg_country'=>'DE',
  'pg_language'=>'de',
  'pg_method'=>'creditcard',
  'pg_format'=>'json',
  'pg_ip'=>'123.13.12.13',
  'pg_email'=>'[email protected]',
  'pg_first_name'=>'josdhsn',
  'pg_last_name'=>'smitdh',
  'pg_personalid'=>'1234567238-6',
  'pg_return_url'=>'http://www.mysite.com/return.php',
  'pg_cancel_url'=>'http://www.mysite.com/cancel.php'
];

$buff = [];
foreach ($params as $k => $v) {
  array_push($buff, "{$k}={$v}");
}

$url = $endpoint_url . implode('&', $buff);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
$result = curl_exec($ch);
curl_close($ch);

$response = json_decode($result, true);

Reply JSON

{
    "data": {
        "service_id": "123",
        "transaction_id": "NDFF-PM4J-PVIA-CM1O",
        "status": "created",
        "payment_method": "creditcard",
        "amount": "10.00",
        "currency": "EUR",
        "payment_method_url": "https://www.paygol.com/api/pay-direct/NDFF-PM4J-PVIA-CM1O",
        "customer": {
            "first_name": "john",
            "last_name": "smith",
            "email": "[email protected]",
            "phone": "5531996145534",
            "personal_id": "58888854525",
            "country": "DE"
        },
        "redirect_urls": {
            "success_url": "http://www.mysite.com/return.php",
            "cancel_url": "http://www.mysite.com/cancel.php"
        }
    }
}

Reply in case of an error:

{
    "error": {
        "status": 400,
        "internal_code": "9702",
        "message": "Bad request - Invalid CPF"
    }
}

Reply (XML)

<transaction>
  <response>OK</response>
  <service>123</service>
  <payment_method>creditcard</payment_method>
  <payment_methods>creditcard,paysafecard,bitcoin,giropay,sofort</payment_methods>
  <id>NDFF-PM4J-PVIA-CM1O</id>
  <price>10.00</price>
  <currency>EUR</currency>
  <price_consumer>10.00</price_consumer>
  <currency_consumer>EUR</currency_consumer>
  <locale>es-CL</locale>
  <payment_method_url>https://www.paygol.com/api/pay-direct/NDFF-PM4J-PVIA-CM1O
</payment_method_url>
  <custom>player123</custom>
  <return_url>http://www.mysite.com/return.php</return_url>
  <cancel_url>http://www.mysite.com/cancel.php</cancel_url>
</transaction>

 

Reply in case of an error (example):

<transaction>
  <response>NOK</response>
  <error_message>Wrong country</error_message>
</transaction>

 

Reply parameters XML format.

Checking the status of a payment

To check the status of a payment you must make a request to the following URL:

https://www.paygol.com/api/check-payment

The following POST/GET parameters are required:

Example:

<?php

$endpoint_url = 'https://www.paygol.com/api/check-payment?';

$params = [
    'service'=>'123',
    'id'=>'N38K-WMP9-HUHM-Q6G7',
    'format'=>'json',
];

$buff = [];
foreach ($params as $k => $v) {
  array_push($buff, "{$k}={$v}");
}

$url = $endpoint_url . implode('&', $buff);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
$result = curl_exec($ch);
curl_close($ch);

var_dump(json_decode($result, true));

Reply (JSON)
Transaction ID was found, regardless of its current status:

{
    "data": {
        "service_id": "123",
        "transaction_id": "N38K-WMP9-HUHM-Q6G7",
        "status": "created",
        "payment_method": "itau",
        "amount": "5.00",
        "currency": "EUR",
        "created_at": "2019-04-08 00:21:00",
        "completed_at": null,
        "customer": {
            "first_name": "john",
            "last_name": "smith",
            "email": "[email protected]",
            "phone": "5531996145534",
            "personal_id": "58888854525",
            "country": "BR"
        }
    }
}

Reply in case of an error:

{
    "error": {
        "status": 404,
        "internal_code": "0302",
        "message": "Bad request - Transaction not found"
    }
}

Reply (XML)
Transaction ID was found, regardless of its current status (example):

<transaction>
  <response>OK</response>
  <status>completed</status>
</transaction>

Reply in case of an error (example):

<transaction>
  <response>NOK</response>
  <error_message>Transaction ID not found</error_message>
</transaction>

Reply parameters XML format.

Status Definitions

Completed-Consumer completed the payment process successfully and your account has been credited
Created-Consumer never completed the payment process, or the payment has not yet been registered by the payment method provider
Failed-Consumer attempted a payment but the payment method provider did not accept the payment 
Rejected-Paygol has rejected the payment, likely due to a notification from the payment method provider