Instant Payment Notification V2 (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 of implementation

<?php 

use Paygol\Notification;

/**
 * Merchant service ID
 *
 * @var int
 */
$service_id = "123";
/**
 * Merchant shared secret
 *
 * @var string
 */
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";

$ipn = new Notification($service_id, $shared_secret);

try {
    $ipn->validate();

    $params = $ipn->getParams();

    var_dump($params);
    
    // do something

    // Confirm reception
    $ipn->sendResponse(['OK'], 200);
} catch (\Exception $e) {
    $ipn->sendResponse(['error' => 'Validation error'], 400);
}

The above command returns JSON structured like this:

{
  "country": "ES",
  "currency": "USD",
  "custom": "Producto 1 - Producto 2 - Producto 3",
  "method": "teleingreso",
  "price": "10.00",
  "service_id": "123",
  "status": "completed",
  "transaction_id": "ZISS-A7Q8-RE2Z-S73W"
}

Notification handling

Handling notifications correctly is crucial to making sure your integration’s business logic works as expected.

 

Acknowledge notifications immediately

If your notification script performs complex logic, or makes network calls, it’s possible that the script would time out before Paygol sees its complete execution. Ideally, your notification handler code (acknowledging receipt of an event by returning a 2xx status code) is separate of any other logic you do for that event.

 

Handle duplicate notifications

IPN endpoints might occasionally receive the same notification more than once. We advise you to guard against duplicated notifications receipts by making your event processing idempotent. One way of doing this is logging the events you’ve processed, and then not processing already-logged events.

API Implementation

Overview
How to use the API Implementation
Parameter description
Payment methods
Search Payment Methods
Creating a Transaction
Transaction status
Status Definitions

 

Documentation for the implementation API v1.1.

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 JSON response. 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

https://www.paygol.com/api/v2/

Parameters description

Payment methods

Name Coverage Code Description

Search Payment Methods

This function returns a list of valid payment methods for the requested country.

<?php

use \Paygol\API;
use \Paygol\Exceptions\InvalidParameterException;

/**
 * Merchant service ID
 *
 * @var int
 */
$service_id = "123";

/**
 * Merchant shared secret
 *
 * @var string
 */
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";

try {
  $pg = new API($service_id, $shared_secret);

  $payment_methods = $pg->getPaymentMethods("de");

  var_dump($payment_methods);
} catch (\Exception $e) {
  die($e->getMessage());
}

Response

{
  "methods": {
    "creditcard": {
      "code": "creditcard",
      "name": "Credit Card",
      "image": "https://www.paygol.com/pay-now/images/method_button_creditcard.png"
    },
    "paysafecard": {
      "code": "paysafecard",
      "name": "Paysafecard",
      "image": "https://www.paygol.com/pay-now/images/method_button_paysafecard.png"
    },
    "bitcoin": {
      "code": "bitcoin",
      "name": "Bitcoin",
      "image": "https://www.paygol.com/pay-now/images/method_button_bitcoin.png"
    },
    "giropay": {
      "code": "giropay",
      "name": "Giropay",
      "image": "https://www.paygol.com/pay-now/images/method_button_giropay.png"
    }
  }
}


Creating a Transaction

Every single payment request in the API will generate a Transaction. Each Transaction is uniquely identified by Transaction ID. To obtain details about a Transaction you need to make a separate GET request.

<?php

use \Paygol\API;
use \Paygol\Models\Payer;
use \Paygol\Models\RedirectUrls;


/**
 * Merchant service ID
 *
 * @var int
 */
$service_id = "123";

/**
 * Merchant shared secret
 *
 * @var string
 */
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";

try {
    $pg = new API($service_id, $shared_secret);

    $redirectUrls = new RedirectUrls();
    $redirectUrls->setRedirects(
        "https://www.my-site.com/success", 
        "https://www.my-site.com/failure"
    ); // optional

    $pg->setRedirects($redirectUrls);

    $pg->setCountry('DE');
    $pg->setPrice(11.00, 'EUR');
    $pg->setPaymentMethod('bitcoin');

    $payer = new Payer();
    $payer->setFirstName('John');
    $payer->setLastName('Doe');
    $payer->setEmail('[email protected]');
    $payer->setBIC('123423432');

    $pg->setPayer($payer);

    $payment = $pg->createPayment();

    var_dump( $payment );

    if (!empty($payment['data']['payment_method_url'])) {
        // do something
    }
} catch (\Exception $e) {
    die($e->getMessage());
}

The above command returns JSON structured like this:

{
  "data": {
    "service_id": "123",
    "transaction_id": "ABCD-ZZZZ-BIKE-R000",
    "status": "created",
    "payment_method": "bitcoin",
    "amount": "11.00",
    "currency": "EUR",
    "payment_method_url": "https://www.paygol.com/api/pay-direct/ABCD-ZZZZ-BIKE-R000",
    "custom":"internalID=918273645",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "5699334453",
      "personal_id": "111111111",
      "country": "CL"
    },
    "redirect_urls": {
        "success_url": "https://www.my-site.com/success",
        "cancel_url": "https://www.my-site.com/failure"
      }
  },
}

Transaction status

<?php

use \Paygol\API;

/**
 * Merchant service ID
 *
 * @var int
 */
$service_id = "123";

/**
 * Merchant shared secret
 *
 * @var string
 */
$shared_secret = "7c1a6a24-7943-102d-92f8-29573711ad31";

try {
    $pg = new API($service_id, $shared_secret);

    $status = $pg->getPaymentStatus('1234-5678-ABCD-EFGH');

    var_dump( $status );
} catch (\Exception $e) {
    die($e->getMessage());
}

The above command returns JSON structured like this:

{
  "payment": {
    "service_id": "123",
    "transaction_id": "1234-5678-ABCD-EFGH",
    "status": "created",
    "payment_method": "bitcoin",
    "amount": "11.00",
    "currency": "EUR",
    "created_at": "2019-05-30 22:01:46",
    "completed_at": null,
    "custom":"internalID=918273645",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "5699334453",
      "personal_id": "111111111",
      "country": "CL"
    }
  }
}

Status Definitions

Status Code Definition
Webcheckout

Web checkout implementation
Parameters description
Available Payment methods.

Web checkout Implementation

Below you will find a sample code for your payment button. Simply replace the example values as required and you’ll be ready to start receiving payments.

Parameters description

Parameter Type Description Requirement
pg_serviceid integer Service ID of your account. Mandatory
pg_price numeric The price of the product/service. Mandatory
pg_currency string Type of currency specified in alphabetic code ISO 4217 you want to use (eg: EUR, USD, GBP, MXN, etc.). See the full list of the currency codes. Mandatory
pg_country string Country of the payer, in ISO 3166-2 format (e.g. GB, DE, ES).
See the list of the country codes.
Mandatory
pg_language string Language, in ISO 639-1 format (e.g. en, es). If the provided language is not available, defaults to english. optional
pg_method string Payment method. Please check the table below for a list of available payment methods and their codes. For more information regarding each payment method, please check our Pricing page. Mandatory only for whitelabel checkout
pg_name string Description of your product/service, which will be shown on the payment screen. optional
pg_custom string Custom field, can be used to identify customer, inventory, etc. optional
pg_email string Email address of the payer. Mandatory only for whitelabel checkout
pg_phone string Phone number of the payer. Mandatory only for whitelabel checkout for some payment methods.
pg_first_name string First name of the payer. Mandatory only for whitelabel checkout
pg_last_name string Last name of the payer. Mandatory only for whitelabel checkout
pg_personalid string Local personal ID number of the payer. Mandatory only for whitelabel checkout for some payment methods
pg_sub_merchant_url string optional
pg_sub_merchant_id string optional
pg_return_url string After the payment process your customers will be redirected here (e.g. https://www.mysite.com/thanks). optional
pg_cancel_url string Your customer will be redirected to after a cancelled or failed payment process (e.g. https://www.mysite.com/failed). optional

Available Payment methods:

Name Code Description

Credit Card

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Bitcoin

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Webpay

pg_country Mandatory
pg_email Mandatory

Multicaja

pg_country Mandatory
pg_email Mandatory

Servipag

pg_country Mandatory
pg_email Mandatory

PagoEfectivo

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory
pg_phone Mandatory

Pago Facil

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Rapipago

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Paysafecard

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Giropay

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory (Use this field for BIC)

iDEAL

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Sofort

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Przelewy24

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Bancontact

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory

Bradesco

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory
pg_phone Mandatory (Format E.g.: 5531123456789)

OXXO

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Itaú

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory
pg_phone Mandatory (Format E.g.: 5531123456789)

Davivienda

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Boleto

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Redpagos

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Santander Brasil

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory
pg_phone Mandatory (Format E.g.: 5531123456789)

Santander México

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Banco do Brasil

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory
pg_phone Mandatory (Format E.g.: 5531123456789)

PSE

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

Efecty

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
pg_personalid Mandatory

ViaBaloto

pg_country Mandatory
pg_email Mandatory
pg_first_name Mandatory
pg_last_name Mandatory
Instant Payment Notification (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'];
$country	          = $_GET['country'];
$custom	           = $_GET['custom'];
$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