SDK for PHP

SDK for PHP is a software development kit for development of web services which are capable of integrating with the JetPay-based payment solutions to perform pay-ins by using Payment Page. This section describes how to use SDK for PHP to build pay-in experience from inside of your system.

SDK for PHP is compatible with PHP version up to 7.2. You can download SDK for PHP from GitHub or Packagist:

GitHub: https://github.com/Jetpay/paymentpage-sdk-php
Packagist: https://packagist.org/packages/jetpay/paymentpage-sdk

What can I do with SDK for PHP?

SDK for PHP allows you to do the following:

Calculate signature and generate request for opening the Payment Page checkout page
Check callback signature and extract payment details from callbacks

What's inside?

SDK for PHP contains the following:

src—the library for development
tests—the library for automatic testing
composer.json—the script for importing libraries
The service files

Using SDK for PHP

To start using SDK for PHP you need to complete the following tasks:

Make sure you have you have ready your merchant ID and secret key obtained from the JetPay:
1. If your company has never obtained any ID or secret key from JetPay, you need to submit an application for connecting to JetPay.
2. If your company already has an ID and a secret key to sign messages obtained from JetPay, you need to notify JetPay customer support that you want to use SDK for PHP and consult with the customer support on how to arrange a test run.
Integrate the JetPay payment solution in your system:
1. Install the SDK for PHP libraries into a directory inside your project.
2. Import the libraries you need into your system application.
Test and put your system in production mode.
- Use test merchant ID and test values for payment parameters from the tests library.
- Once testing is complete, request your production merchant ID from JetPay and put your system in production mode.

With any questions regarding usage of SDK for PHP contact the JetPay technical support specialists at support@jetpay.kz.

Installing and importing libraries

You can install the SDK for PHP libraries manually or automatically with Composer, a dependency manager for PHP programming language. Composer can download and install the libraries required for a project, as well as generate a script for importing the libraries.

The following steps describe how to install the SDK for PHP libraries by using Composer:

If you have not yet installed Composer, you need to download, install and check settings. For more information, see https://getcomposer.org/.
Navigate into the system source code directory in command line interface and run the following command:
```
composer require jetpay/paymentpage-sdk:dev-main
```
Composer automatically downloads the SDK for PHP in the vendor sub-directory and creates the autoload.php script required to enable you to use all the classes provided by the libraries.
Include the autoload.php script into your system project:
```
require __DIR__.'../../vendor.autoload.php';
```

Opening checkout page

The checkout page invocation request consists of a set of parameters, which are signed to secure the data transmitted to the JetPay payment platform. SDK for PHP allows you to seamlessly sign parameters and generate requests. To open the Payment Page checkout page by using SDK for PHP do the following:

Create an instance of the Payment class and specify payment details.

$payment = new jetpay\Payment('186', 'TEST_1555943554067');
    // Project ID and payment ID and payment ID must be unique within your project scope
$payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
    // Amount in minor currency units and currency in ISO-4217 alpha-3 format
$payment->setPaymentDescription('Test payment');
    // Payment description (optional)

All the parameters in this example are required to perform any payment. You can also use any optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Payment Page invocation parameters.

Create a gate instance and initiate it with the secret key you obtained from the JetPay technical support specialists. The secret key is required to sign invocation requests.
```
$gate = new jetpay\Gate('<secret_key>');
    // Secret key you obtained from technical support service
```

Generate the checkout page invocation request:

$url = $gate->getPurchasePaymentPageUrl(<pp_host>, $payment);

Correct the checkout page invocation request contains payment parameters and signature (abbreviated):

https://paymentpage.jetpay.kz/payment?signature=OEKRlLXKStyo
...%3D%3D&payment_id=1555943554067...123

Use the request in your system code to open the checkout page.

Here is an example of generating a URL for opening an English checkout page. The payment method selection page includes detailed payment information including amount, currency and short payment description while the data input page includes countdown timer.

Figure: Example of generating Payment Page invocation request

$gate = new jetpay\Gate('mySecret');
    // Secret key
$payment = new jetpay\Payment('186', 'TEST_1555943554067');
    // Project ID and payment ID and payment ID must be unique within your project scope
$payment->setPaymentAmount(1000)->setPaymentCurrency('EUR');
    // Amount in minor currency units and currency in ISO-4217 alpha-3 format
$payment->setPaymentDescription('Test payment');
    // Payment description
$payment->setBestBefore(new \DateTime('2050-01-01 00:00:00 +0000'));
    // Date and time for timer countdown
$payment->setCustomerId('Customer123');
    // Unique customer ID
$payment->setLanguageCode('en');
    // Language code to use in the checkout page
$url = $gate->getPurchasePaymentPageUrl('example.com', $payment);
    // Complete request with signature

Processing callbacks

The JetPay payment platform sends payment results to the callback URL you specified when connecting to JetPay. Callback is an HTTP POST request that contains response data in JSON format. To extract payment information from a JSON string do the following:

Create an instance of Gate with the secret key, if you did not it earlier.
```
$gate = new jetpay\Gate('<secret_key>');
```
Create an instance of Callback by using the JSON string from the callback obtained from the JetPay payment platform:
```
$callback = $gate->handleCallback($data);
```

Use the following methods to obtain the callback information. You can get either full payment information or request specific payment parameters:

Callback::getPaymentId();            // Getting payment ID
Callback::getPaymentStatus();        // Getting payment status
Callback::getPayment();              // Getting payment body

By using SDK for PHP, you can automatically check validity of callback signature. Below, you will find an example of callback that includes signature and payment results.

Figure: Sample payment callback

{
             "project_id": 186,       // Project ID
             "payment": {             // Payment details
             "id": "pid_1555943554067",       // Payment ID
             "type": "purchase",  // Payment type
             "status": "success", // Payment status
             "date": "2018-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  
             "sum": {           // Payment amount and currency
             "amount": 1000,
             "currency": "EUR"
             },
             "description": "Test payment"  // Payment description
             },
             "account": {           // Payment instrument details
             "number": "431422******0056",
             "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2",
             "type": "visa",
             "card_holder": "ADA LOVELACE",
             "id": 778804,
             "expiry_month": "11",
             "expiry_year": "2021"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2018-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2018-08-28T09:10:50+0000",
             "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Request ID
             "sum_initial": {    // Initial payment amount and currency 
             "amount": 1000,
             "currency": "EUR"
             },
             "sum_converted": {
             // Payment amount and currency as per applicable project conversion rules
             "amount": 1000,
             "currency": "EUR"
             },
             "provider": {     // Payment details in payment system
             "id": 6,
             "payment_id": "15354474886323",
             "date": "2018-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success" // User-readable response code
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }