API Implementation

 

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

 


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 plain text response (according to your preference) containing detailed information on how to start a new payment. This way you can easily provide your customers with payment instructions (for your convenience we even provide pre-built payment instructions along with this information, when possible). In the case of payment methods that rely on a third party payment screen (such as non-mobile payment methods that allow direct bank transfers or let the end-user print a payment voucher) we will provide a payment 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 Code Description

Example:

https://www.paygol.com/pay?pg_serviceid=123&pg_price=5.00&pg_currency=EUR&pg_custom=player123&pg_return_url=http://www.mysite.com/return.php
&pg_cancel_url=http://www.mysite.com/cancel.php&pg_mode=api&pg_country=ES&pg_language=es&pg_method=sms&pg_format=txt
&pg_ip=123.123.123.123&[email protected]&pg_personalid=12345678-6

Reply (plain text)
Reply for SMS payments:

OK|service|payment_method|payment_methods|id|keyword|pin|shortcode|sms|price|currency|price_consumer|currency_consumer|locale|locale_instructions
|disclaimer|custom|return_url|cancel_url

Example:

OK|123456|sms|sms,call|XXXX-YYYY-ZZZZ-1234|PAY|412537|3555|1|6.40|EUR|4.50|GBP|en-GB|Send PAY 412537 to 3555 (1 SMS)|Connection provided by ABC|player123
|http://www.mysite.com/return.php|http://www.mysite.com/cancel.php

Reply for call payments:

OK|service|payment_method|payment_methods|id|number|pin|time|price|currency|price_consumer|currency_consumer|locale|locale_instructions
|disclaimer|custom|return_url|cancel_url

Example:

OK|123456|sms|sms,call|XXXX-YYYY-ZZZZ-1234|0900 5500800|303012|00:00:47|6.40|EUR|4.50|GBP|en-GB|Call 0900 5500800 for 47 seconds. Keep your PIN 303012 at hand.
|Connection provided by ABC|player123|http://www.mysite.com/return.php|http://www.mysite.com/cancel.php

Reply for non-mobile payments.:

OK|service|payment_method|payment_methods|id|price|currency|price_consumer|currency_consumer|locale|payment_method_url|custom|return_url|cancel_url

Example:

OK|123456|webpay|sms,webpay|XXXX-YYYY-ZZZZ-1234|10.00|EUR|6800.00|CLP|es-CL|https://www.paygol.com/api/pay-direct/XXXX-YYYY-ZZZZ-1234
|player123|http://www.mysite.com/return.php|http://www.mysite.com/cancel.php

Reply in case of an error:

NOK|error_message

Example:

NOK|Wrong country

Reply (XML)
Reply for SMS payments (example):

<transaction>
  <response>OK</response>
  <id>XXXX-YYYY-ZZZZ-1234</id>
  <keyword>PAY</keyword>
  <pin>412537</pin>
  <shortcode>3555</shortcode>
  <sms>1</sms>
  <price>6.40</price>
  <currency>EUR</currency>
  <price_consumer>4.50</price_consumer>
  <currency_consumer>GBP</currency_consumer>
  <locale>en-GB</locale>
  <locale_instructions>Send PAY 412537 to 3555 (1 SMS)</locale_instructions>
  <disclaimer>Connection provided by ABC</disclaimer>
  <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 for call payments (example):

<transaction>
  <response>OK</response>
  <id>XXXX-YYYY-ZZZZ-1234</id>
  <number>0900 5500800</number>
  <pin>303012</pin>
  <time>00:00:47</time>
  <price>6.40</price>
  <currency>EUR</currency>    
  <price_consumer>4.50</price_consumer>
  <currency_consumer>GBP</currency_consumer>
  <locale>en-GB</locale>
  <locale_instructions>Call 0900 5500800 for 47 seconds. Keep your PIN 303012 at hand.</locale_instructions>
  <disclaimer>Connection provided by ABC</disclaimer>
  <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 for non-mobile payments. (example):

<transaction>
  <response>OK</response>
  <service>123456</service>
  <payment_method>webpay</payment_method>
  <payment_methods>sms,webpay</payment_methods>
  <id>XXXX-YYYY-ZZZZ-1234</id>
  <price>10.00</price>
  <currency>EUR</currency>
  <price_consumer>6800.00</price_consumer>
  <currency_consumer>CLP</currency_consumer>
  <locale>es-CL</locale>
  <payment_method_url>https://www.paygol.com/api/pay-direct/XXXX-YYYY-ZZZZ-1234</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>

 

The reply parameters are the same regardless of the format used.

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:

https://www.paygol.com/api/check-payment?service=123&id=XXXX-YYYY-ZZZZ-1234&format=txt

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

OK|status

Example:

OK|completed

Reply in case of an error:

NOK|error_message

Example:

NOK|Transaction ID 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>

The reply parameters are the same regardless of the format used.

IPN

What is IPN?
Instant Payment Notification (IPN) is a service that notifies you of events related to Paygol transactions. You can use it to automate back-office and administrative functions, such as fulfilling orders, inserting points or coins, upgrading membership, tracking customers, and providing status and other information related to a transaction.

Information about the payment
Paygol will make a GET request to your IPN file when your customer completes a transaction. You can use this notification to kick-off order fulfillment, enable digital media downloads, store information in a customer relationship management (CRM) or accounting system, and so on.

How to receive the IPN information in my web page?
Paygol provides samples of Instant Payment Notification (IPN) code for popular development environments. For custom IPN files, you can use the following sample code as a starting point.

Example:

<?php 

$secret_key = "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeee";  // Enter secret key for your service. 

// Secret key validation 
if ($secret_key != $_GET['key']) {
    echo "Validation error"; 
    exit;
}

// get the variables from Paygol system
$transaction_id	   = $_GET['transaction_id'];
$service_id	       = $_GET['service_id'];
$shortcode	        = $_GET['shortcode'];
$keyword	          = $_GET['keyword'];
$message	          = $_GET['message'];
$sender	           = $_GET['sender'];
$operator	         = $_GET['operator'];
$country	          = $_GET['country'];
$custom	           = $_GET['custom'];
$points	           = $_GET['points'];
$price	            = $_GET['price'];
$currency  	       = $_GET['currency'];

// Here you can do whatever you want with the variables, for instance inserting or updating data into your Database 

?>

IPN Parameters description