SDK for PHP

SDK for PHP is a software development kit for development of web services which are capable of integrating with the ecommpay payment solutions to perform purchase by using Payment Page. This section describes how to use SDK for PHP to build purchase experience from inside of your web service.

SDK for PHP is compatible with PHP version 7.0 or higher. You can download SDK for PHP from GitHub or Packagist:

What can I do with SDK for PHP?

SDK for PHP allows you to do the following:
  • Calculate signature and generate an URL for opening the Payment Page.
  • Check callback signature and extract payment details from callbacks.

What's inside?

SDK for PHP contains the following:

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

Using SDK for PHP

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

  1. Make sure you have ready your merchant ID and secret key obtained from ecommpay:
    1. If your company has never obtained any ID or secret key from ecommpay, you need to submit an application for connecting to the ecommpay payment platform at https://ecommpay.com/apply-now/.
    2. If your company already has an ID and a secret key to sign messages obtained from ecommpay, you need to notify ecommpay customer support that you want to use SDK for PHP and consult the customer support on how to arrange a test run.
  2. Integrate the ecommpay payment solution in your web service:
    1. Install the SDK for PHP libraries into a directory inside your web service project.
    2. Import the libraries you need into your web service application.
  3. Test and put your web service 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 ecommpay and put your web service in production mode.

With any questions regarding the use of SDK for PHP contact the ecommpay technical support specialists at support@ecommpay.com.

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:

  1. If you have not yet installed Composer, you need to download, install and check settings. For more information, see https://getcomposer.org/.
  2. Navigate into the web service source code directory in command line interface and run the following command:
    composer require ecommpay/paymentpage-sdk
    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.
  3. Include the autoload.php script into your web service project:
    require __DIR__.'../../vendor.autoload.php';

Opening payment form

A URL for opening Payment Page consists of a set of parameters, which are signed to secure the data transmitted to the ecommpay payment platform. SDK for PHP allows you to seamlessly sign parameters and generate URLs. To open the Payment Page payment form by using SDK for PHP do the following:

  1. Create an instance of the Payment class and specify payment details.
    $payment = new ecommpay\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 the ISO-4217 alpha-3 format
$payment->setPaymentDescription('Test payment');
    // Payment description (optional)

    All parameters in this example, except for the payment description, are mandatory for any purchase. You may also need to pass other parameters, for example, the customer's email or phone number when the 3‑D Secure authentication is required. Such parameters must be specified as follows.

    $payment->setCustomerPhone('The customer phone number. Must have from 4 to 24 digits');
$payment->setCustomerEmail('The customer email');

    In addition, for card purchases you are recommended to pass the customer's billing address information: the country code in ISO 3166-1 alpha-2 (details), the postal code, the city, and the street address. Such parameters are specified as follows.

    $payment->setBillingPostal('The postal code of the customer billing address');
$payment->setBillingCountry('The country of the customer billing address, in ISO 3166-1 alpha-2');
$payment->setBillingCity('The city of the customer billing address');
$payment->setBillingAddress('The street of the customer billing address');

    You can also use any other optional parameters available for Payment Page. For more information about the Payment Page invocation parameters, see Parameters for opening payment form.

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

  3. Generate the URL for opening the payment form:

    $url = $gate->getPurchasePaymentPageUrl($payment);

    The URL must contain payment parameters and signature (abbreviated):

    https://paymentpage.ecommpay.com/payment?signature=OEKRlLXQsa2..
               ..gWg%3D%3D&payment_id=pid_1555943554067...
  4. Use the generated URL for opening the payment form (details).

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

Figure 1. Example of generating the URL for opening Payment Page
$gate = new ecommpay\Gate('<secret_key>');
    // Secret key
$payment = new ecommpay\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->setLanguageCode('en');
    // Language code to use in payment form
$url = $gate->getPurchasePaymentPageUrl($payment);
    // Complete request with signature

Using the test mode

When working with the SDK for PHP, you can use the test mode. It allows you to check completeness and correctness of specified parameters and get information about errors if there were any.

Before using the test mode, make sure that the server of the web service can send the HTTP requests to sdk.ecommpay.com and that your PHP interpreter meets at least one of the following requirements:

  • It supports the curl library (more).
  • It supports the sockets library with the HTTP access to the URL (more).
  • The directive allow_fopen_url is set to true and the HTTP access to the URL is supported (more).

This will allow you to specify various parameters to open the payment form as part of the testing activities (you will be able to use both test and production parameters) and to analyse error information. Use the following code:

$payment = new Payment(<project_id>, '<payment_id_in_your_service>');
$payment->setPaymentAmount(1000)
    ->setPaymentCurrency('EUR')
    ->setPaymentDescription('Test payment')
$gate = new Gate('<secret_key>');
 
try {
    return $gate->getPaymentPageUrl($payment); 
    // Receiving the URL to open the payment form
} catch (ValidationException $e) { // Validating possible exceptions
    error_log($e->getFormattedMessage()); // Logging the error message
}
 
return null;

Information about the errors that occurred in testing is provided in error messages as follows:

One or more parameters is not valid:
 
Customer_id:
    Must be not null // The id of the customer, required for this request, was not specified
Account_token:
    Invalid account token  // Incorrect token value was specified

If there are no errors, then the generated URL for opening Payment Page is correct.

Processing callbacks

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

  1. Create an instance of Gate with the secret key, if you did not it earlier.
    $gate = new ecommpay\Gate('<secret_key>');

  2. Create an instance of Callback by using the JSON string from the callback obtained from the ecommpay payment platform: 

    $callback = $gate->handleCallback($data);

  3. 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 2. 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": "2021-08-28T09:11:28+0000",  // Payment date and time
             "method": "card",  // Payment method
             "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": "2024"
             },
             "operation": {     // The last operation within payment
             "id": 17839000001150,  // Operation ID
             "type": "sale",        // Operation type
             "status": "success",   // Operation status
             "date": "2021-08-28T09:11:28+0000", // Operation date and time
             "created_date": "2021-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": "2021-02-07T08:34:24+0000",
             "auth_code": "563253",
             "endpoint_id": 6
             },
             "code": "0",          // Unified response code
             "message": "Success", // User-readable response code
             "eci": "05"           // ECI code, result of 3-D Secure check
              },
              "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..."  // Signature
              }

Related links