s4y/paycom-integration-php

Set of classes to easy integration with Paycom (Payme) payment system

Paycom integration template

This is not a complete implementation of the Marchant API, instead a basic template. One MUST implement all the todo: entries found in the source files according his/her own requirements., _(*1)

Table of Content

• Prerequisites
• Installation
• Transactions table
• Orders table
• Additional resources
• Endpoint
• File Structure
• Set Up and Run Merchant API implementation on Docker Containers
• Contributing

Prerequisites

• PHP 5.4 or greater
• MySQL or MariaDB latest stable version
• PDO extension
• Composer dependency manager

Installation

Clone this repository:, _(*2)

$ git clone https://github.com/PaycomUZ/paycom-integration-php-template.git

Change working directory:, _(*3)

$ cd paycom-integration-php-template

Generate auto-loader, this step will create vendor/ folder with autoloader:, _(*4)

$ composer dumpautoload

Copy the sample config file as paycom.config.php and adjust the settings according to your needs:, _(*5)

$ cp paycom.config.sample.php paycom.config.php

Edit paycom.config.php and set your settings there:, _(*6)

• Set merchant_id;
• Do not change the login, it is always Paycom;
• Set a path to the password file in the keyFile;
• Adjust connection settings in the db key to your mysql database.

Following is an example paycom.config.php configuration file content:, _(*7)

<?php
return [
    'merchant_id' => '69240ea9058e46ea7a1b806a',
    'login'       => 'Paycom',
    'keyFile'     => 'password.paycom',
    'db'          => [
        'host'     => 'localhost',
        'database' => 'db_shop',
        'username' => 'db_shop_admin',
        'password' => 'bh6U8M8tR5sQGsfLVHdB'
    ],
];

and an example password.paycom file content:, _(*8)

fkWW6UNrzvzyV6DhrdHJ6aEhr3dRcvJYkaGx

If you need to adjust other database settings, such as character set, you can do that in the Paycom/Database.php file., _(*9)

Transactions table

This template requires transactions table at least with the following structure:, _(*10)

CREATE TABLE `transactions` (
  `id`                    INT(11)      NOT NULL AUTO_INCREMENT,
  `paycom_transaction_id` VARCHAR(25)  NOT NULL COLLATE 'utf8_unicode_ci',
  `paycom_time`           VARCHAR(13)  NOT NULL COLLATE 'utf8_unicode_ci',
  `paycom_time_datetime`  DATETIME     NOT NULL,
  `create_time`           DATETIME     NOT NULL,
  `perform_time`          DATETIME     NULL     DEFAULT NULL,
  `cancel_time`           DATETIME     NULL     DEFAULT NULL,
  `amount`                INT(11)      NOT NULL,
  `state`                 TINYINT(2)   NOT NULL,
  `reason`                TINYINT(2)   NULL     DEFAULT NULL,
  `receivers`             VARCHAR(500) NULL     DEFAULT NULL COMMENT 'JSON array of receivers' COLLATE 'utf8_unicode_ci',
  `order_id`              INT(11)      NOT NULL,

  PRIMARY KEY (`id`)
)

COLLATE='utf8_unicode_ci'
ENGINE=InnoDB
AUTO_INCREMENT=1;

Additional fields can be added into this table or above data types and sizes can be adjusted., _(*11)

Orders table

You also need a table to store info about orders. Here is a sample table definition:, _(*12)

CREATE TABLE orders
(
  id          INT AUTO_INCREMENT PRIMARY KEY,
  product_ids VARCHAR(255)   NOT NULL,
  amount      DECIMAL(18, 2) NOT NULL,
  state       TINYINT(1)     NOT NULL,
  user_id     INT            NOT NULL,
  phone       VARCHAR(15)    NOT NULL
) ENGINE = InnoDB;

Additional fields can be added into this table or above data types and sizes can be adjusted., _(*13)

Additional resources

• To test your Merchant API implementation we highly recommend using the following tools:
  • Test Merchant Cabinet;
  • Merchant Sandbox.
• For production use Merchant Cabinet.

Endpoint

In the merchant cabinet on the cashbox settings point the endpoint to your Merchant API implementation. Assuming your domain is https://example.com, and your Merchant API implementation is located under api/ folder or a URL rewriting is configured to access API by https://example.com/api/, then endpoint should be set as https://example.com/api/index.php., _(*14)

File Structure

Following is the brief description of the files:, _(*15)

Set Up and Run Merchant API implementation on Docker Containers

In cases that there is no PHP/Apache/Nginx/MySQL on your production platforms you can easily and quickly setup and run the Merchant API implementation using docker containers., _(*16)

Here we will build docker images for Paycom Merchant API and optionally for MySQL., _(*17)

Dockerfile contains statements to build an image for Merchant API. This image is based on PHP v7 and Apache 2.4, but also includes PDO and PDO_MYSQL extensions. There are also statements to install the latest version of Composer., _(*18)

By editing docker-compose.yml file you can adjust exposed ports, volumes., _(*19)

If you need more info about base images and docker commands look at the following links:, _(*20)

• Official php:7-apache docker image;
• Official mysql docker image;
• Dockerfile reference;
• Docker Compose file reference;
• Docker Compose CLI reference;
• Docker CLI reference.

Build the images:, _(*21)

docker-compose build

Run the containers:, _(*22)

docker-compose up -d

Show the logs:, _(*23)

docker-compose logs -f

Stop the containers:, _(*24)

docker-compose stop

Stop and remove the containers:, _(*25)

docker-compose down

Test the endpoint via cURL command:, _(*26)

curl -X POST \
  http://localhost:8888/ \
  -H 'Authorization: Basic UGF5Y29tOktleUZyb21NZXJjaGFudENhYmluZXQ=' \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "method" : "CheckPerformTransaction",
    "params" : {
        "amount" : 50000,
        "account" : {
            "phone" : "901304050"
        }
    }
}'

Authorization header contains Base64 decoded Paycom:KEY_FROM_CABINET login and password., _(*27)

For testing purposes you can quickly Base64 decode the login & password with this online tool., _(*28)

You should get something like the following response (below the response is formatted, but you will get raw responses):, _(*29)

{
    "id": 1,
    "result": null,
    "error": {
        "code": -31050,
        "message": {
            "ru": "Неверный код заказа.",
            "uz": "Harid kodida xatolik.",
            "en": "Incorrect order code."
        },
        "data": "order_id"
    }
}

Contributing

PRs are welcome. GL&HF!, _(*30)