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/

Signature of message

All requests to the payment API must be signed using the merchant’s secret key with the HMAC SHA256 algorithm. The signature must be calculated using the payload of the request, sorted in ascending order and adding this result in a request header with the name X-PG-SIG.
<?php 

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

$payload = [...];

ksort($payload, SORT_NATURAL | SORT_FLAG_CASE);

$signature = hash_hmac('sha256', json_encode($payload), $shared_secret);

Request an authentication access token

GET /auth/token
<?php 

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

$payload = json_encode(['pg_serviceid' => $service_id]);

$signature = hash_hmac("sha256", $payload, $shared_secret);

// API URL
$url = 'https://www.paygol.com/api/v2/auth/token';

$opts = [
    'http' => [
        'method' => 'GET',
        'header' => [
            'Content-type: application/json',
            'X-PG-SIG: ' . $signature,
        ],
        'content' => $payload,
    ],
];

$context = @stream_context_create($opts);

$json_response = @file_get_contents($url, false, $context);

$result = json_decode($json_response, true);

$token = $result['token'];

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