Общая информация

Платежная платформа Paytransfer позволяет проводить оплату, выплату и возврат с использованием различных методов, а также выполнять другие действия, связанные с проведением платежей.

Выплата, возврат и оплата Host-to-Host проводятся с использованием Gate — программного интерфейса, который предназначен для приема запросов от вашей системы к платежной платформе Paytransfer. Gate отвечает принципам REST API, а также поддерживает обратную совместимость, благодаря которой выпуск каждой новой версии интерфейса не требует изменений программного кода на стороне вашей системы.

Организация взаимодействия

Платежная платформа связана с одной стороны с вашей системой, а с другой — с сервисами партнеров. Взаимодействие вашей системы с платформой основано на обмене HTTP-сообщениями по принципу «запрос-ответ»: ваша система направляет к платформе запросы и получает от платформы ответы и оповещения.

Платежная платформа принимает и обрабатывает запрос: сначала проверяет его корректность и наличие всех обязательных параметров, а затем выполняет все действия, необходимые для получения информации о результате, и направляет результат в вашу систему в виде оповещения.

Все взаимодействия с платежной платформой выполняются с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2, а данные в запросах и оповещениях должны кодироваться и обрабатываться с использованием кодировки UTF-8. При работе со страницей оплаты в качестве пользовательского браузера вы можете использовать актуальные версии таких браузеров, как Chrome, Safari, Opera, Firefox, Microsoft Edge, Internet Explorer, Yandex Browser, QQ, MIUI, Samsung Internet, 360 и ряда других. Подробную информацию о работе страницы оплаты в разных средах можно получить у специалистов технической поддержки Paytransfer.

Порядок подключения

В общем случае для подключения к платежной платформе Paytransfer необходимо:

1. Решить организационные вопросы, касающиеся взаимодействия с Paytransfer:

   1. Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с Paytransfer — отправьте заявку на подключение.
   2. Согласуйте со специалистами технической поддержки Paytransfer порядок и сроки интеграции и запуска в работу.
2. Выполнить подготовительные технические работы.

   Чтобы проводить оплату:

   1. Установите и подключите необходимые библиотеки.
   2. Реализуйте сбор параметров, необходимых для проведения оплаты, а также создания и отправки запросов на открытие страницы оплаты на стороне клиентской части вашей системы.
   3. Реализуйте подписывание данных и обработку оповещений на серверной стороне вашей системы.

   Чтобы проводить выплату:

   1. Обеспечьте возможности сбора параметров, необходимых для проведения выплаты, а также формирования и отправки запросов на ее инициирование.
   2. Обеспечьте подписывание данных и корректное реагирование на оповещения на стороне серверной части вашей системы.
3. Совместно со специалистами технической поддержки Paytransfer протестировать выполнение целевых действий и запустить техническое решение в работу.

Для начала работы с платежной платформой Paytransfer обращайтесь к курирующему менеджеру Paytransfer, а для решения технических вопросов — к специалистам технической поддержки (support@paytransfer.kz).

Оплата — это тип платежа, в рамках которого на основании исходного запроса осуществляется перевод денежных средств от пользователя в вашу систему.

Оплата Host-to-Host осуществляется через интерфейс Gate, и все взаимодействия с пользователями выполняются в вашей системе.

Далее представлена информация о проведении оплаты Host-to-Host.

Для проведения оплаты через Gate:

1. Отправьте запрос на оплату.
2. Примите от платежной платформы оповещение о результате оплаты.

Общая информация

Чтобы провести оплату, необходимо отправить к платежной платформе запрос — HTTP-сообщение заданной структуры — с использованием метода POST. В каждом запросе к платежной платформе должны передаваться следующие элементы в указанном порядке:

• Стартовая строка с указанием метода передачи запроса (POST) и конечной точки, протокола и его версии (HTTP/1.1). Доступные конечные точки:
  • /v2/payment/card/sale — для платежей с использованием банковских карт;
  • /v2/payment/mobile/sale — для платежей с использованием мобильной коммерции.
• Заголовок с полем Host, содержащим доменное имя для запросов к платформе.
• Пустая строка, отделяющая служебную информацию от тела сообщения.
• Тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним.

В дополнение к обязательному полю Host в заголовке можно использовать любые другие поля из числа допустимых в HTTP версии 1.1.

Параметры запроса на оплату

При формировании JSON-строки необходимо использовать следующие объекты и параметры:

Рис. 2. Пример данных из запроса на проведение оплаты на сумму 300000,00 KZT

{
  "general": {
    "project_id": 2990,
    "payment_id": "X03935",
    "signature": "YWb6Z20ByxpQ30hfTI"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
    },
  "card": {
    "pan": "1122334455667788",
    "year": 2030,
    "month": 10,
    "card_holder": "JOHN DOE"
  },
  "payment": {
    "amount": 30000000,
    "currency": "KZT"
  }
}

Кроме базового набора объектов и параметров в запросе нужно передавать и другие параметры. Эти параметры указаны в таблице:

Дополнительно в запросе рекомендуется указывать следующие дополнительные параметры:

В процессе оплаты платеж может иметь разные статусы, значение которых описано в следующей таблице:

Дополнение информации о платеже

Общая информация

Как правило, для проведения платежа достаточно тех данных, которые обязательны для запроса на инициирование этого платежа. Но в отдельных случаях — например, для дополнительной проверки — со стороны платежной системы или провайдера могут запрашиваться дополнительные данные. Для работы с такими ситуациями используется процедура дополнения информации: уведомление о том, что вам необходимо дополнить данные.

Вы можете обеспечить передачу полной информации во всех запросах на инициирование платежей (и уйти от необходимости в дополнении информации) либо настроить реагирование на ситуации с необходимостью дополнения (и поддерживать проведение платежей в таких случаях).

Схема работы

Информация о необходимости дополнить данные отправляется в оповещениях или ответах. Обычно эта информация отправляется в оповещениях — без предварительных запросов со стороны вашей системы, но в то же время ее можно получать в ответах на запросы о статусе платежа.

После получения такого оповещения или ответа, ваша система должна составить и отправить в платформу корректный запрос с недостающей информацией. Если время ожидания истекло и запрос в платформе не принят — платеж автоматически отклоняется.

Состав запрошенных данных в теле запроса может варьироваться: данные можно указывать в полном объеме, частично или не указывать совсем, но в любом случае в теле запроса должен содержаться объект additional_data. При приеме запроса без этого объекта запрос признается некорректным и в вашу систему отправляется ответ с информацией об ошибке.

Как только в платежную платформу поступают все запрашиваемые данные, проведение платежа продолжается дальше.

Для дополнения информации ваша система должна:

1. Получить список параметров в объекте clarification_fields в оповещении или ответе.
2. Отправить POST-запрос, содержащий требуемый набор данных с объектом additional_data и подпись, к конечной точке /v2/payment/clarification.
3. Получить и обработать ответ 200 OK о приеме запроса в обработку.

Ответ 200 OK отправляется, когда все запрашиваемые параметры указаны корректно и в полном объеме. При невыполнении хотя бы одного условия цикл повторяется, начиная с шага 1.

Оповещение (callback)

Рис. 3. Пример тела оповещения о необходимости предоставить индекс и адрес пользователя

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: example.com


{
    "sum_request": {
        "amount": 45000,
        "currency": "KZT"
    },
    "request_id": "80bdc0831c3f8e1",
    "payment": {
        "id": "payment_568485",
        "method": "card",
        "date": "2019-07-29T11:19:33+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "provider_id": 3
    },
    "sum_real": {
        "amount": 45000,
        "currency": "KZT"
    },
    "status": "awaiting clarification",   // Статус платежа
    "customer": {
        "id": "423432432432534222"
    },
    "clarification_fields": {            // Запрашиваемая информация
        "avs_data": [
            "avs_post_code",
            "avs_street_address"
        ]
    },
    "project_id": 11,
    "description": "",
    "operations": [
        {
            "id": 7282148104130,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T11:19:33+0000",
            "processing_time": null,
            "sum": {
                "amount": 45000,
                "currency": "KZT"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ],
    "signature": "99q4lpCEuNpxp3ugvxF1qPbinWUIwNSLaxcVbF0A=="
}

Оповещение о необходимости дополнить данные соответствует стандартной структуре оповещения, описанной в разделе Оповещение (callback), но содержит объект clarification_fields со списком запрашиваемых параметров.

Справа представлен пример тела оповещения о необходимости предоставить индекс и адрес пользователя.

Ответ

Рис. 4. Пример тела ответа о необходимости указать электронную почту, имя и фамилию, платежный адрес и дату рождения пользователя

HTTP/1.1 200 OK

Server: api.com
Date: Wed, 29 July 2019 09:27:45 GMT
Content-Type: application/json; charset=UTF-8
Content-Length: 875
Connection: keep-alive
Keep-Alive: timeout=60
Cache-Control: no-cache
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Origin: *
X-Powered-By: PHP/7.0.32
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent,
X-Requested-With,If-Modified-Since,Cache-Control,Content-Type


{
    "sum_request": {
        "amount": 500,
        "currency": "KZT"
    },
    "request_id": "563c42d4846d105e77",
    "payment": {
        "method": "card",
        "date": "2019-07-29T09:27:45+0000",
        "result_code": "9999",
        "result_message": "Awaiting processing",
        "status": "awaiting clarification",      // Статус платежа
        "is_new_attempts_available": false,
        "attempts_timeout": 0,
        "id": "E2E_01_0868",
        "cascading_with_redirect": false,
        "provider_id": 1145
    },
    "sum_real": {
        "amount": 500,
        "currency": "KZT"
    },
    "customer": {
        "id": "7826"
    },
    "clarification_fields": {
        "customer": [
            "email",              // Запрашиваемая информация
            "first_name",
            "last_name",
            "billing.address",
            "billing.city",
            "billing.country",
            "billing.postal",
            "day_of_birth"
        ]
    },
    "project_id": 245,
    "description": "",
    "operations": [
        {
            "id": 1315207090506,
            "type": "sale",
            "status": "awaiting clarification",
            "date": "2019-07-29T09:27:45+0000",
            "processing_time": null,
            "request_id": "563c42d4846d105e77",
            "sum": {
                "amount": 500,
                "currency": "KZT"
            },
            "code": "9999",
            "message": "Awaiting processing"
        }
    ],
    "signature": "MYiga7aoW0UBFBfeTdIiF0QFOokEfyuSA=="
}

Для ответа о необходимости дополнить информацию используется такая же структура, как и для оповещений.

Справа представлен пример тела ответа о необходимости указать электронную почту, имя и фамилию, платежный адрес и дату рождения пользователя.

Структура запроса

Рис. 5. Пример тела запроса с предоставлением индекса и адреса пользователя в качестве дополнительной информации

{
  "general": {
    "project_id": 11,
    "payment_id": "EPr-bf14",
    "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...=="
  },
  "additional_data": {
    "avs_data":{
        "avs_post_code": "230532",
        "avs_street_address": "01 Main Street, MB"
    }
  }
}

Запрос с предоставлением недостающей информации отправляется методом POST к конечной точке /v2/payment/clarification и должен содержать следующие объекты и параметры:

Справа представлен пример тела запроса с предоставлением индекса и адреса пользователя в качестве дополнительной информации.

Получение информации о состоянии платежа

Обзор

При работе с платежной платформой Paytransfer актуальную информацию о состоянии платежей можно получить через интерфейс Dashboard, а также в оповещениях (подробнее — в разделе Оповещение (callback)) или ответах на запросы о состоянии платежа. Такие запросы можно отправлять при любой необходимости — например, для проверки статуса оплаты, когда проведение платежа может занимать не один день, — но не ранее, чем через 10 секунд после отправки запроса на проведение платежа. При этом следует учитывать, что информацию о платеже можно получить только после того, как в платежной платформе был принят запрос на проведение этого платежа и платеж был зарегистрирован.

Запрос о состоянии платежа выполняется на стороне платежной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа (200) и запрошенная информация без указания статуса запроса. Информация об HTTP-кодах ответов представлена в разделе Ответ.

Структура запроса

Рис. 6. Пример тела запроса на получение информации о состоянии платежа

{
    "general":{
       "project_id": 50,
       "payment_id": "ORDER_ID_302bis",
       "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5yuSjq1GH7BYgmil8APKojXw=="
    }
}

Чтобы получить информацию о состоянии платежа, необходимо отправить запрос к конечной точке /v2/payment/status, при этом в теле запроса должен содержаться объект general с основными идентификационными сведениями:

Примеры ответов

Рис. 7. Пример тела ответа о платеже с итоговым статусом

HTTP/1.1 200 OK                                           //стартовая строка ответа
...                                                       //поля заголовка 
{ 
  "project_id":50,
  "payment":{ 
    "id":"ORDER_ID_302bis",
    "type":"purchase",                                     //тип платежа
    "status":"success",                                    //статус платежа 
    "date":"2019-12-12T15:46:51+0000",
    "method":"card",                                       //код платежного метода
    "sum_real":{ 
      "amount":3300,
      "currency":"KZT"
    },
    "description":"Purchase"
  },
  "customer":{ 
    "id":"6361696170"
  },
  "operations":[ 
    { 
      "id":9435219675496,
      "type":"sale",                                          //тип операции
      "status":"success",                                     //статус операции
      "date":"2019-12-11T15:46:37+0000",
      "created_date":"2019-12-11T15:46:35+0000",
      "request_id":"bcRFZRJkmfcf-178c3d843c99-00009436",
      "sum":{ 
        "amount":3300,
        "currency":"KZT"
      },
      "code":"0",                           //код, уточняющий статус операции sale
      "message":"Success",                  //пояснение к коду
      "eci":"07",
      "provider":{ 
        "id":1309,
        "payment_id":"2015611",
        "auth_code":"",
        "date":"2019-12-11T15:46:36+0000"
     }
    }
  ],
  "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg=="
}

Справа представлен пример данных о проведенной оплате. В этом примере указаны:

• код ответа о том, что запрос был успешно принят (200);
• статус платежа (success);
• код используемого платежного метода (card);
• сведения об операции sale в массиве operations.

Рис. 8. Пример тела ответа о платеже с промежуточным статусом

HTTP/1.1 200 OK                                             //стартовая строка ответа
...                                                         //поля заголовка
{ 
  "project_id":72,
  "payment":{ 
    "id":"ORDER_ID_tetan_M_2007_2012",
    "type":"purchase",                                       //тип платежа
    "status":"awaiting redirect result",                     //статус платежа
    "date":"2019-12-11T15:59:10+0000",
    "method":"card",                              //код платежного метода
    "sum":{ 
      "amount":25000,
      "currency":"KZT"
    },
    "description":"Book premium"
  },
  "customer":{ 
    "id":"Scott"
  },
  "operations":[ 
    { 
      "id":65747461,
      "type":"sale",                                           //тип операции
      "status":"awaiting redirect result",                     //статус операции
      "date":"2019-12-11T15:59:10+0000",
      "created_date":"2019-12-11T15:59:06+0000",
      "request_id":"97c7dd03080b4293603f28e64-0c415bc3e876c911f2d87-00006979",
      "sum_initial":{ 
        "amount":25000,
        "currency":"KZT"
      },
      "sum_converted":{ 
        "amount":25000,
        "currency":"KZT"
      },
      "code":"9999",                       //код, уточняющий статус операции sale
      "message":"Awaiting processing",     //пояснение к коду
      "provider":{ 
        "id":2080,
        "payment_id":"",
        "auth_code":""
      }
    }
  ],
  "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA=="
}

В представленном далее примере данных о незавершенной оплате содержится следующая информация:

• код ответа о том, что запрос был успешно принят (200);
• статус платежа (awaiting redirect result);
• код используемого платежного метода (card);
• сведения об операции sale в массиве operations.

Рис. 9. Пример тела ответа об ошибке в запросе

HTTP/1.1 400 Bad Request                         //стартовая строка ответа
...                                              //поля заголовка
{
   "status":"error",                             //статус обработки запроса
   "code":"2004",                                //код, уточняющий статус
   "message":"Required field not provided"       //пояснение к коду
}

Далее представлен пример ответа на некорректно составленный запрос. Если в запросе обнаружена ошибка, то в ответе указывается следующее:

• код ответа с описанием причины ошибки в стартовой строке (400 Bad Request);
• статус обработки запроса (error);
• уточняющая информация об ошибке: код ошибки (2004) и поясняющее описание к нему (Required field not provided).

Выплата — это тип платежа, в рамках которого на основании исходного запроса осуществляется перевод денежных средств от вашей системы к пользователю.

В платежной платформе поддерживается один вариант для работы с выплатой через Gate — разовая единичная выплата, но дополнительно обеспечивается возможность проведения массовой выплаты через Dashboard (с автоматическим формированием требуемого количества платежей).

Для проведения выплаты:

1. Сформируйте и отправьте в платежную платформу запрос на выплату.
2. Примите от платежной платформы оповещение (callback) о результате выплаты.

Схема проведения выплаты представлена далее.

Как правило, ответ на полученный запрос в любом из описанных случаев отправляется в вашу систему в течение 100 мс. Если ответ не получен, можно повторить отправку запроса с тем же идентификатором платежа. Если в ответе указаны сведения об ошибке, допущенной на стороне вашей системы, устраните эту ошибку и повторите отправку запроса с учетом правок.

// Пример запроса на выплату. PHP
require_once 'Signer.php';

$payoutUrl = 'http://gate.test/v2/payment/card/payout';
$projectId = 200;
$secretKey = '123';

$requestParams = [
    'general' => [
        'project_id' => $projectId,
        'payment_id' => microtime(),
    ],
    'payment' => [
        'amount'   => 100,
        'currency' => 'KZT',
    ],
    'customer' => [
        'id' => 'test_customer_id',
        'ip_address'=> '14.192.204.152',
        'email'=> 'janedoe@example.com',
    ],
    'account' => [
        'bank_id' => 14,
        'customer_name' => 'Jane Doe',
        'number' => '314159265358979',
    ],
];

$requestParams['general']['signature'] = Signer::sign($requestParams, $secretKey);

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, $payoutUrl);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($requestParams));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);

if (!$response) {
    print_r(curl_error($ch));
} else {
    print_r($response);
}

curl_close($ch);

# Пример запроса на выплату. Python
from datetime import datetime
from Signer import Signer
import requests
import json

payoutUrl = 'http://gate.test/v2/payment/card/payout'
secretKey = '123'
projectId = 200

params = {
    'general': {
        'project_id': 200,
        'payment_id': 'X03936'
    },
    'payment': {
        'amount': 122990,
        'currency': 'KZT'
    },
    'customer': {
        'id': 'customer_173',
        'ip_address': '1.2.3.4',
        'email': 'janedoe@example.com'
    },
    'account': {
        'bank_id': 114,
        'customer_name': 'Jane Doe',
        'number': '314159265358979'
    }
}

print(json.dumps(params))

signer = Signer()
params['general']['signature'] = signer.getSign(params, secretKey)

r = requests.post(
    payoutUrl,
    json=params
)

print(r.status_code, r.reason)
print(r.text[:300])

// Пример запроса на выплату. Java
const signer  = require('./Signer');
const request = require('request'); // npm install request

const secretKey = '123';
const params = {
    'general': {
        'project_id': 200,
        'payment_id': 'X03936'
    },
    'payment': {
        'amount': 122990,
        'currency': 'KZT'
    },
    'customer': {
        'id': 'customer_173',
        'ip_address': '1.2.3.4',
        'email': 'janedoe@example.com'
    },
    'account': {
        'bank_id': 114,
        'customer_name': 'Jane Doe',
        'number': '314159265358979'
    }
};

params['general']['signature'] = (new signer()).getSign(params, secretKey);

const opts = {
    uri: 'http://gate.test/v2/payment/card/payout',
    method: 'POST',
    json: params
};

request(opts, function (error, response, body) {
    if (error || response.statusCode !== 200) {
        console.log('request got an error:');
        console.log(body);
        return
    }

    console.log('request got OK');
    console.log(body);
});

Рис. 12. Пример данных из запроса на проведение выплаты на платежную карту

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "middle_name": "Paul",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 1000,
        "currency": "KZT"
    },
    "card": {
        "pan": "1122334455667788",
        "card_holder": "JOHN DOE"
    }
}

Чтобы провести выплату, составьте и отправьте в платежную платформу запрос — HTTP-сообщение заданной структуры — с использованием метода POST. В каждом запросе к платежной платформе должны передаваться следующие элементы в указанном порядке:

• Стартовая строка с указанием метода передачи запроса (POST) и конечной точки в интерфейсе Gate, протокола и его версии (HTTP/1.1). Доступные конечные точки:
  • /v2/payment/card/payout — для выплаты с использованием банковских карт;
  • /v2/payment/mobile/payout — для выплаты с использованием мобильной коммерции.

• Заголовок с полем Host, содержащим доменное имя для запросов к платформе.
• Пустая строка — разделитель, отделяющая служебную информацию от тела запроса.
• Тело запроса в формате JSON, которое должно содержать набор данных запроса и подпись. Допустимы только символы Unicode (UTF-8).

В дополнение к обязательному полю Host в заголовке можно использовать любые другие поля из числа допустимых в HTTP версии 1.1.

При формировании JSON-строки необходимо использовать базовый набор объектов и параметров:

Кроме базового набора объектов и параметров в запросе нужно передавать и другие параметры. Эти параметры указаны в таблице:

При проведении выплаты могут использоваться следующие статусы.

Платежные карты (Visa, Mastercard) — это популярный платежный метод, с помощью которого пользователи могут оплачивать в вашей системе различные услуги, а также получать денежные средства.

Точную минимальную и максимальную сумму оплаты и выплаты уточняйте у курирующего менеджера Paytransfer. Уточнить минимальную и максимальную сумму платежа, доступную в вашем проекте, вы также можете в Dashboard. Для этого в Dashboard перейдите в раздел Проекты и выберите вкладку Платежные методы.

Логотип платежного метода доступен для загрузки здесь.

«Мобильная коммерция» — это популярный платежный метод, с помощью которого пользователи могут оплачивать в вашей системе различные услуги, а также получать денежные средства.

Точную минимальную и максимальную сумму оплаты и выплаты уточняйте у курирующего менеджера Paytransfer. Уточнить минимальную и максимальную сумму платежа, доступную в вашем проекте, вы также можете в Dashboard. Для этого в Dashboard перейдите в раздел Проекты и выберите вкладку Платежные методы.

Логотип платежного метода доступен для загрузки здесь.

Особенности проведения платежей

Нужно помнить про некоторые особенности проведения платежей:

• Доступность возврата необходимо уточнять у курирующего менеджера в Paytransfer.
• При оплате пользователь получает от сервиса оператора связи сообщение с OTP-кодом для подтверждения оплаты.

  Пользователь вводит OTP-код в вашей системе, а вы должны отправить этот код в платежную платформу в новом запросе. Более подробную информацию см. в разделе Дополнение информации о платеже. В запросе вы должны передать объект additional_data, представленный в следующей таблице.

Поддержка со стороны операторов связи

Идентификаторы сервисов операторов связи для проведения платежей:

При работе с платежной платформой Paytransfer для получения актуальной информации о выполнении запросов на программном уровне служат следующие сущности:

• Ответ (response) Ответы отправляются синхронно, то есть в течение одного HTTP-сеанса, и содержат информацию о приеме запроса в платформе или об ошибке, если запрос не был принят.
• Оповещение (callback) Оповещения отправляются асинхронно и содержат информацию о промежуточном и итоговом результате выполнения запроса.

Также получать актуальную информацию о выполнении запросов можно через интерфейс Dashboard.

Платежная платформа подтверждает получение запроса, синхронно (то есть в течение того же сеанса) возвращая ответ (response) в виде HTTP-сообщения заданной структуры. В зависимости от результата обработки запроса и порядка взаимодействия между вашей системой и платформой содержимое ответа может отличаться и обычно содержит:

• сведения об успешном приеме запроса в обработку;
• расширенное описание ошибки, если запрос невозможно принять в обработку.

Далее рассказывается о структуре ответов, а также о кодах и статусах, используемых для передачи информации о состоянии запроса. Полный перечень кодов платежной платформы, используемых в расширенном описании ошибок, представлен в разделе Статусы операций и коды ответов.

Структура ответа

В каждом ответе от платформы содержатся следующие элементы в порядке перечисления:

• стартовая строка с указанием протокола и его версии (HTTP/1.1), кода ответа и поясняющей фразы к коду (например, 200 OK);
• поля заголовка;
• пустая строка — разделитель, отделяющая служебную информацию от тела ответа;
• тело ответа в формате JSON, содержащее данные ответа и подпись. В теле ответа используются только символы Unicode (UTF-8).

HTTP-коды ответов

HTTP-код ответа в стартовой строке любого ответа служит для передачи информации о результате приема или выполнения запроса либо о причине обнаруженной ошибки. Коды ответов и пояснительные фразы, используемые в ответах платформы, а также описание кодов приведены в следующей таблице.

Статус приема запроса

Статус приема запроса указывается в параметре status в теле синхронного ответа и информирует о том, приняла ли платежная платформа ваш запрос в обработку. Никакого другого смысла статус приема запроса не несет, поэтому никаких выводов о платеже, указанном в исходном запросе, делать нельзя!

Существуют всего два статуса приема запроса:

• success — запрос принят в обработку. Этот статус используется только в ответах с HTTP-кодом 200.
• error — платежная платформа не может принять запрос в обработку. Этот статус используется в ответах с кодами ошибок 400, 403, 404, 422 и 500.

Статус приема запроса не указывается в синхронном ответе, если исходный запрос обрабатывается по синхронной схеме и платежной платформе удалось успешно принять и обработать его. В таком случае в теле синхронного ответа платежная платформа возвращает запрошенную информацию.

Ответы о приеме или отказе в обработке асинхронно обрабатываемого запроса

Если запрос принят в обработку, то в первой строке ответа указывается код ответа 200, а в теле — статус success.

Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки (в примере — 400), а в теле — статус error и расширенная информация об ошибке: код ошибки в платежной платформе (в примере —2004) и описание к нему (в примере — Required field not provided). Запросы с ошибкой отбрасываются и не принимаются в обработку!

Общая информация

Рис. 14. Пример оповещения

 {
        "project_id": 200,
        "payment": {
            "payment_id": "cosmo_set_4589",
            "type": "purchase",
            "status": "success",
            "date": "2020-07-20T07:12:04+0000",
            "method": "card",
            "sum": {
                "amount": 131970,
                "currency": "KZT"
            },
            "description": "Sports equipment"
        },
        "customer": {
            "id": "customer_173",
            "ip_address": "198.51.100.47",
            "phone": "+60-3-xxxx-xxxx",
            "email": "jane.doe@example.com"
        },
        "operation":{
            "id": 003,
            "type": "sale",
            "status": "success",
            "date": "2020-07-20T07:12:04+0000",
            "sum_initial": {
                "amount": 131970,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
    }

Для передачи промежуточной и итоговой информации о результате обработки и выполнения запроса используются оповещения. Оповещения отправляются в случае завершении обработки операции на стороне платежной платформы.

В каждом оповещении от платформы содержатся следующие элементы в порядке перечисления:

• стартовая строка с указанием метода передачи запроса (POST), URL вашей системы для отправки оповещений о результатах (в примере — /notify/success), протокола и его версии (HTTP/1.1);
• поля заголовка, в том числе поле Host с указанием доменного имени вашей системы (в примере — webservice.com);
• пустая строка — разделитель, отделяющая служебную информацию от тела оповещения;
• тело оповещения в формате JSON, содержащее набор данных оповещения и подпись. В теле оповещения используются только символы Unicode (UTF-8).

Дополнительные сведения о подписи данных см. в Подписывание и проверка подписи.

Справа представлен пример оповещения с информацией о результате проведения платежа. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения.

Доставка оповещений

Оповещения отправляются сразу же после проведения операции.

Факт доставки оповещения в вашу систему фиксируется на стороне платежной платформы в ответе от вашей системы. Ответ должен содержать HTTP заголовок с кодом ответа 200 ОК.

В случае если необходимо отложить отправку оповещения, в запросе на проведение платежа следует передать параметр delay в объекте callback с необходимым значением в секундах. Максимальное значение задержки отправки составляет 600 секунд.

Если оповещение не было доставлено, со стороны платежной платформы выполняются повторные попытки отправки оповещения по следующему расписанию:

• 6 попыток с интервалом в 10 сек.;
• далее 62 попытки в течение четырех часов с увеличивающимся интервалом (интервал увеличивается в соответствии с формулой 70 + 10·1,12n-4, где n — порядковый номер попытки отправки);
• потом каждые 4 часа до достижения максимального количества попыток.

Максимально платежная платформа выполняет 120 попыток доставки оповещения в течение 11 суток. Расписание отправки может незначительно изменяться в зависимости от загруженности системы.

Адреса для приема оповещений

Рис. 15. Пример данных из запроса на открытие страницы оплаты, содержащий URL-адрес, на который будут отправляться оповещения по этому платежу

{
        project_id: 1234,
        payment_id: 'payment_47',
        customer_id: 'customer_123',
        customer_first_name: 'John',
        customer_last_name: 'Doe',
        customer_email: 'johndoe@example.com',
        merchant_callback_url: 'http://example.com/callback',
        payment_currency: 'KZT',
        payment_amount: 10000,
        signature: 'kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y19vySO\/RLUkDJrOcZzUCwX6R\/ekpZhkIQg=='
    }

Рис. 16. Пример данных из запроса на выплату, содержащий URL-адрес, на который будут отправляться оповещения по этому платежу

{
    "general": {
        "project_id": 1234,
        "payment_id": "payment_47",
        "merchant_callback_url": "http://example.com/callback",
        "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "account": {
        "number": "123456789"
    },
    "payment": {
        "amount": 10000,
        "currency": "KZT"
    }
}

Платежная платформа Paytransfer отправляет оповещения на URL-адрес, который вы предоставляете сотрудникам Paytransfer в процессе интеграции. Если у вас есть несколько проектов, вы можете предоставить для каждого проекта отдельный URL-адрес, на который платежная платформа будет отправлять оповещения.

Вы можете предоставить сотрудникам Paytransfer отдельные URL-адреса, чтобы получать оповещения с определенной информацией по платежу. Например, чтобы оповещения об успешном завершении платежа платежная платформа отправляла на один адрес, а об отклонении — на другой. Вы также можете предоставить отдельный URL-адрес для получения оповещений по платежам определенного типа.

Вы можете самостоятельно указать дополнительные адреса для приема оповещений в Dashboard. Для этого в Dashboard перейдите в раздел Проекты и выберите вкладку Оповещения. Инструменты в Dashboard позволят вам определить, в каких случаях и на какие адреса Paytransfer будет отправлять вашей системе оповещения.

Обратите внимание, что ваша система должна принимать оповещения только с IP-адреса, полученного от команды интеграции Paytransfer. Чтобы уточнить IP-адрес, с которого Paytransfer отправляет оповещения, обратитесь в службу поддержки Paytransfer.

Адреса для приема оповещений по конкретному платежу

Вы можете указать отдельный URL-адрес для приема оповещений по конкретному платежу. Для этого:

• в запрос на открытие страницы оплаты добавьте параметр merchant_callback_url и задайте в качестве его значения URL-адрес, на который Paytransfer будет отправлять оповещения;
• в запрос на выплату добавьте в объект general параметр merchant_callback_url и задайте в качестве его значения URL-адрес, на который Paytransfer будет отправлять оповещения.

После этого все оповещения по этому платежу (и только по нему) будут отправляться на указанный в этом параметре URL-адрес независимо от того, какой URL-адрес для приема оповещений задан для вашего проекта.

Обработка оповещений

При обработке оповещений ваша система должна следовать следующим правилам:

1. Принимать оповещения только с IP адреса, полученного от службы поддержки Paytransfer.
2. На успешно принятые оповещения ответ вашей системы должен быть HTTP 200 OK.
3. На оповещения, которые уже ранее были приняты вашей системой, ответ должен быть также HTTP 200 OK.
4. На оповещения, принятые с ошибкой, ответ вашей системы должен быть HTTP 400 Bad Request (например, если вам не удалось преобразовать строку параметров в массив) или HTTP 500 Internal Server Error (например, если оповещение пришло на неправильный URL-адрес).
5. Повторные оповещения, которые ранее не были приняты или были приняты с ошибкой, ваша система должна попытаться принять еще раз.
6. Ваша система не должна ограничивать время на доставку оповещений, доставка оповещений может происходить с задержкой.

О состоянии каждой операции, созданной в платежной платформе Paytransfer в рамках платежа, информирует ее статус. Этот статус передается в промежуточных и итоговых оповещениях о платежах в параметре operation.status, а также отображается в интерфейсе Dashboard.

Помимо статусов, в платежной платформе используются служебные коды и сообщения, которые уточняют информацию о выполнении или возможных причинах отклонения операции, в том числе со стороны внешних платежных систем. Для удобства представления информации все используемые коды ответов и ошибок, а также соответствующие им сообщения унифицированы и передаются в вашу систему в параметрах operation.code и operation.message. Также эти коды и сообщения можно увидеть в интерфейсе Dashboard в карточке платежа.

Рис. 18. Фрагмент оповещения с информацией о выполнении операции

"operation":{
            "id": 003,
            "type": "sale",
            "status": "success",
            "date": "2020-07-20T07:12:04+0000",
            "sum_initial": {
                "amount": 131970,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success"
        }

Если при обработке запроса на проведение платежа возникает ошибка, то в синхронном ответе от платежной платформы указывается статус запроса error. Так как операция в данном случае не создается, то информация об ошибке передается в параметрах code и message. Подробная информация и примеры синхронных ответов об ошибках представлены в разделе Ответ.

В зависимости от статуса и кода ошибки от вас могут потребоваться определенные действия. Возможные статусы операции и запроса и предусмотренные для них дальнейшие действия с вашей стороны приведены в таблице ниже.

Возможные коды ответов, соответствующие им сообщения, а также рекомендуемые вам дальнейшие действия, если они предусмотрены, приведены в таблицах далее.

Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей в разделе Аналитика.

Также Dashboard позволяет выгружать данные в формате CSV с помощью инструментов в разделе Отчеты. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки Paytransfer.

Общая информация

Для обеспечения защищенного обмена данными при работе с платежной платформой Paytransfer используется криптографический протокол TLS (Transport Layer Security; протокол защиты транспортного уровня) версии не ниже 1.2, а для подтверждения авторства и целостности передаваемых данных дополнительно применяется цифровая подпись. Она формируется и проверяется по заданным алгоритмам с использованием одинакового секретного ключа, доступного на двух сторонах: вашей системы и Paytransfer.

Для корректной работы перед отправкой в платформу любого запроса необходимо сформировать подпись и включить ее в состав этого запроса, а при получении от платформы оповещений и ответов, содержащих подпись, следует проверять целостность данных путем сличения расчетных подписей с полученными. Нарушения целостности данных могут быть вызваны разными причинами, но при обнаружении таких нарушений данные не могут и не должны считаться достоверными.

Далее описаны алгоритмы подписывания данных и проверки их целостности, а также представлены примеры выполнения этих алгоритмов.

Описание алгоритма

В качестве входных данных для подписывания выступают:

1. Данные запроса, которые требуется подписать.

   Как правило, это все параметры тела запроса за исключением подписи или JavaScript-объект configObj с параметрами без включения параметра signature.

2. Ключ, используемый для подписывания.

   Для отладки и тестирования алгоритма подписывания могут использоваться произвольные ключи. Для рабочих запросов в платформу следует применять только актуальный секретный ключ, полученный от службы поддержки Paytransfer.

Далее в описании и примере представлен часто используемый и наиболее показательный вариант реализации алгоритма: с JavaScript-объектом configObj на входе (без параметра signature) и на выходе (с параметром signature).

// Пример формирования подписи. PHP
class Signer
{
    const ALGORITHM = 'sha512';
    const ITEMS_DELIMITER = ';';
    const MAXIMUM_RECURSION_DEPTH = 3;


/**
     * Generate signature
     *
     * @param array  $params
     * @param string $secretKey
     * @param array  $ignoreParamKeys
     * @param bool   $doNotHash
     * @param bool   $useUnlimitedRecursionDepth
     *
     * @return string
     */
    public static function sign(array $params, string $secretKey, array $ignoreParamKeys = [], bool $doNotHash = false, bool $useUnlimitedRecursionDepth = false): string
    {
        $paramsPrepared = self::getParamsToSign($params, $ignoreParamKeys, 1, '', $useUnlimitedRecursionDepth);
        $stringToSign = implode(self::ITEMS_DELIMITER, $paramsPrepared);

return $doNotHash
            ? $stringToSign
            : base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $secretKey, true))
            ;
    }

/**
     * Get parameters to sign
     *
     * @param array $params
     * @param array $ignoreParamKeys
     * @param int $currentLevel
     * @param string $prefix
     * @param bool $useUnlimitedRecursionDepth
     *
     * @return array
     */
    private static function getParamsToSign(
        array $params,
        array $ignoreParamKeys = [],
        int $currentLevel = 1,
        string $prefix = '',
        bool $useUnlimitedRecursionDepth = false
    ): array
    {
        $paramsToSign = [];

foreach ($params as $key => $value) {
            if (in_array($key, $ignoreParamKeys, true)) {
                continue;
            }

$paramKey = ($prefix ? $prefix . ':' : '') . $key;

if (is_object($value)) {
                $value = get_object_vars($value);
            }

if (is_array($value)) {
                if (!$useUnlimitedRecursionDepth && ($currentLevel >= self::MAXIMUM_RECURSION_DEPTH)) {
                    $paramsToSign[$paramKey] = (string)$paramKey.':';
                } else {
                    $subArray = self::getParamsToSign($value, $ignoreParamKeys, $currentLevel + 1, $paramKey, $useUnlimitedRecursionDepth);
                    $paramsToSign = array_merge($paramsToSign, $subArray);
                }
            } else {
                if (is_bool($value)) {
                    $value = $value ? '1' : '0';
                } else {
                    $value = (string)$value;
                }

$paramsToSign[$paramKey] = (string)$paramKey.':'.$value;
            }
        }

if ($currentLevel == 1) {
            ksort($paramsToSign, SORT_NATURAL);
        }

return $paramsToSign;
    }
}

# Пример формирования подписи. Python
import hmac
import base64
import hashlib


class Signer:
    def getSign(self, params, key):
        byteKey = key.encode()
        paramsPrepared = self.getParamsToSign(params)
        toSignString = ';'.join(paramsPrepared.values())
        hmacObj = hmac.new(byteKey, toSignString.encode(), hashlib.sha512)

return base64.b64encode(hmacObj.digest())

def getParamsToSign(self, params, currentLevel = 1, prefix = '', useUnlimitedRecursionDepth = False):
        paramsToSign = dict()

for paramKey in params.keys():

newParamKey = (prefix + ':' if prefix else '') + paramKey

if isinstance(params[paramKey], (dict)):
                if useUnlimitedRecursionDepth is False and (currentLevel >= 3):
                    paramsToSign[newParamKey] = newParamKey + ':'
                else:
                    subDict = self.getParamsToSign(params[paramKey], currentLevel + 1, newParamKey, useUnlimitedRecursionDepth)
                    paramsToSign.update(subDict)
            else:
                if isinstance(params[paramKey], (bool)):
                    value = '1' if params[paramKey] == True else '0'
                else:
                    value = str(params[paramKey])

paramsToSign[newParamKey] = str(newParamKey + ':' + value)

sortedParams = dict()

for key in sorted(paramsToSign.keys()):
            sortedParams[key] = paramsToSign[key]

return sortedParams

// Пример формирования подписи. Java
const CryptoJS = require('crypto-js'); // npm install crypto-js


class Signer {
    getSign(params, key) {
        const paramsPrepared = this.getParamsToSign(params, 1);

const joinedString = Object.values(paramsPrepared).join(';');

const hash = CryptoJS.HmacSHA512(joinedString, key);

return hash.toString(CryptoJS.enc.Base64);
    }

getParamsToSign(params, currentLevel = 1, prefix = '', useUnlimitedRecursionDepth = false) {
        let paramsToSign = {};
        let value = '';

let keys = Object.keys(params);
        let key = '';
        for (let i = 0; i < keys.length; i++) {
            key = keys[i];

let paramKey = (prefix ? prefix + ':' : '') + key;

if (typeof params[key] === 'object') {
                if (!useUnlimitedRecursionDepth && (currentLevel >= 3)) {
                    paramsToSign[paramKey] = paramKey + ':';
                } else {
                    let subParams = this.getParamsToSign(params[key], currentLevel + 1, paramKey, useUnlimitedRecursionDepth);

Object.assign(paramsToSign, subParams);
                }
            } else {
                if (typeof params[key] === "boolean") {
                    value = params[key] === true ? '1' : '0';
                } else {
                    value = params[key].toString();
                }

paramsToSign[paramKey] = paramKey + ':' + value;
            }
        }

let orderedKeys = Object.keys(paramsToSign).sort();

let ordered = {};

for (let k = 0; k < orderedKeys.length; k++) {
            ordered[orderedKeys[k]] = paramsToSign[orderedKeys[k]];
        }

return ordered;
    }
}

module.exports = Signer;

Описание алгоритма

В качестве входных данных для проверки целостности выступают:

1. Подписанные данные, которые требуется проверить. Как правило, это тело оповещения или ответа в формате JSON с параметром signature в его составе.
2. Ключ, используемый для проверки. Это должен быть ровно тот же ключ, который был использован для подписывания проверяемых данных.

В качестве выходных данных при проверке целостности в зависимости от реализации алгоритма могут выступать расчетная подпись и информация о ее совпадении с проверяемой подписью, то есть информация о целостности проверяемых данных.

Далее в описании и примере представлен часто используемый и наиболее показательный вариант реализации алгоритма: с телом проверяемого сообщения (оповещения или ответа) в формате JSON на входе и с заключением о целостности этого сообщения на выходе.

В состав алгоритма в этом случае включаются следующие шаги:

Пример для оповещения

Допустим, что надо проверить подпись оповещения при следующих условиях:

Рис. 21. Тело оповещения

{
  "project_id": 200,
  "payment": {
    "id": "sports_eq_4589",
    "type": "purchase",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "method": "World banks",
    "sum": {
      "amount": 131970,
      "currency": "USD"
    },
    "description": "Sports equipment"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "phone": "+60-3-xxxx-xxxx",
    "email": "jane.doe@example.com"
  },
  "operation": {
    "id": 103,
    "type": "sale",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "sum_initial": {
      "amount": 131970,
      "currency": "USD"
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
}

• Ключ подписывания — secret
• Тело полученного оповещения выглядит, как показано в примере.

Чтобы проверить подпись:

Рис. 22. Вид набора параметров после выполнения шага 1

{
  "project_id": 200,
  "payment": {
    "id": "sports_eq_4589",
    "type": "purchase",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "method": "World banks",
    "sum": {
      "amount": 131970,
      "currency": "USD"
    },
    "description": "Sports equipment"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "phone": "+60-3-xxxx-xxxx",
    "email": "jane.doe@example.com"
  },
  "operation": {
    "id": 103,
    "type": "sale",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "sum_initial": {
      "amount": 131970,
      "currency": "USD"
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
}

Рис. 23. Вид набора параметров после выполнения шага 2

project_id:200
payment:id:sports_eq_4589
payment:type:purchase
payment:status:success
payment:date:2020-07-20T07:12:04+0000
payment:method:World banks
payment:sum:amount:131970
payment:sum:currency:USD
payment:description:Sports equipment
customer:id:customer_173
customer:ip_address:198.51.100.47
customer:phone:+60-3-xxxx-xxxx
customer:email:jane.doe@example.com
operation:id:103
operation:type:sale
operation:status:success
operation:date:2020-07-20T07:12:04+0000
operation:sum_initial:amount:131970
operation:sum_initial:currency:USD
operation:code:0
operation:message:Success

Рис. 24. Вид набора параметров после выполнения шага 3

customer:email:jane.doe@example.com
customer:id:customer_173
customer:ip_address:198.51.100.47
customer:phone:+60-3-xxxx-xxxx
operation:code:0
operation:date:2020-07-20T07:12:04+0000
operation:id:103
operation:message:Success
operation:status:success
operation:sum_initial:amount:131970
operation:sum_initial:currency:USD
operation:type:sale
payment:date:2020-07-20T07:12:04+0000
payment:description:Sports equipment
payment:id:sports_eq_4589
payment:method:World banks
payment:status:success
payment:sum:amount:131970
payment:sum:currency:USD
payment:type:purchase
project_id:200

Рис. 25. Вид набора параметров после выполнения шага 4

customer:email:jane.doe@example.com;customer:id:customer_173;customer:ip_address:198.51.100.47;customer:phone:+60-3-xxxx-xxxx;operation:code:0;operation:date:2020-07-20T07:12:04+0000;operation:id:103;operation:message:Success;operation:status:success;operation:sum_initial:amount:131970;operation:sum_initial:currency:USD;operation:type:sale;payment:date:2020-07-20T07:12:04+0000;payment:description:Sports equipment;payment:id:sports_eq_4589;payment:method:World banks;payment:status:success;payment:sum:amount:131970;payment:sum:currency:USD;payment:type:purchase;project_id:200

Рис. 26. Подпись, полученная после выполнения шага 5

k1P1qtiRjtFpwvU1JSVIVTIM/aEo7YxBBcOsPa6DyTmrfvdi/ti8dGlVzSrC6/T+C8JtIQfWeD7L2N15FnSEXw==

1. Удалите из тела оповещения параметр signature вместе с его значением.
2. Преобразуйте оставшиеся параметры в строки UTF-8 согласно алгоритму.
3. Упорядочите полученные строки по алфавиту.
4. Объедините упорядоченные строки в одну строку с использованием в качестве разделителя точки с запятой.
5. Вычислите HMAC полученной строки с использованием функции хеширования SHA-512 и ключа подписывания, после чего закодируйте двоичный HMAC-код с применением алгоритма Base64.
6. Сравните полученную подпись с проверяемой.

   В данном случае подписи не совпадают, а это значит, что такое оповещение недостоверно или ошибочно и должно быть отброшено.

// Пример проверки подписи. PHP
require_once 'Signer.php';


$secretKey = '123';

$requestBody = '{
  "project_id": 200,
  "payment": {
    "id": "sports_eq_4589",
    "type": "purchase",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "method": "World banks",
    "sum": {
      "amount": 131970,
      "currency": "USD"
    },
    "description": "Sports equipment"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "phone": "+60-3-xxxx-xxxx",
    "email": "jane.doe@example.com"
  },
  "operation": {
    "id": 103,
    "type": "sale",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "sum_initial": {
      "amount": 131970,
      "currency": "USD"
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
}';

$requestBodyArray = json_decode($requestBody, true);

$actualSignature = $requestBodyArray['signature'];
unset($requestBodyArray['signature']);
$expectedSignature = Signer::sign($requestBodyArray, $secretKey);

print_r('Actual signature: ' . $actualSignature . PHP_EOL);
print_r('Expected signature: ' . $expectedSignature . PHP_EOL);

if ($expectedSignature === $actualSignature) {
    print_r('Signatures are equal');
} else {
    print_r('Signatures are not equal');
}

print_r(PHP_EOL);

# Пример проверки подписи. Python
from Signer import Signer
import base64


secretKey = '123'
params = {
  "project_id": 200,
  "payment": {
    "id": "sports_eq_4589",
    "type": "purchase",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "method": "World banks",
    "sum": {
      "amount": 131970,
      "currency": "USD"
    },
    "description": "Sports equipment"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "phone": "+60-3-xxxx-xxxx",
    "email": "jane.doe@example.com"
  },
  "operation": {
    "id": 103,
    "type": "sale",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "sum_initial": {
      "amount": 131970,
      "currency": "USD"
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
}

signer = Signer()
actualSign = params['signature']
del params['signature']
expectedSign = signer.getSign(params, secretKey).decode()

print('Actual signature:' + actualSign)
print('Expected signature:' + expectedSign)

if (expectedSign == actualSign):
    print('Signature is correct')
else:
    print('Signature is incorrect')

// Пример проверки подписи. Java
const signer = require('./Signer');


const secretKey = '123';

const params = {
  "project_id": 200,
  "payment": {
    "id": "sports_eq_4589",
    "type": "purchase",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "method": "World banks",
    "sum": {
      "amount": 131970,
      "currency": "USD"
    },
    "description": "Sports equipment"
  },
  "customer": {
    "id": "customer_173",
    "ip_address": "198.51.100.47",
    "phone": "+60-3-xxxx-xxxx",
    "email": "jane.doe@example.com"
  },
  "operation": {
    "id": 103,
    "type": "sale",
    "status": "success",
    "date": "2020-07-20T07:12:04+0000",
    "sum_initial": {
      "amount": 131970,
      "currency": "USDUSD"
    },
    "code": "0",
    "message": "Success"
  },
  "signature": "qV2FRs/wxoOaywQS0GYQDi+6spZFbiRXxt8zG10zy9TNiJLT0P/+EOrpMkoW80mynkaQfSAUJpfQ=="
};

const actualSignature = params['signature'];
delete params.signature;
const expectedSignature = (new signer()).getSign(params, secretKey);

console.log('Actual: ' + actualSignature);
console.log('Expected: '+expectedSignature);

if (actualSignature == expectedSignature) {
    console.log('Signatures is correct');
} else {
    console.log('Signature is incorrect');
}

Общая информация

В этом разделе вы найдете ответы на вопросы, которые могут у вас возникать в процессе работы с платежной платформой Paytransfer.

Не нашли ответ на интересующий вас вопрос? Обратитесь к нашим специалистам:

• к курирующему менеджеру — с деловыми и финансовыми вопросами (о стоимости услуг, расчете комиссий, работе с балансами и т. д.);
• к менеджеру по имплементации — с техническими вопросами (о работе с разными интерфейсами, составлении запросов, настройке оповещений и т. д). Коммуникация с менеджером по имплементации ведется в техническом чате. Если чат ранее не был создан, пожалуйста, обратитесь к своему курирующему менеджеру, чтобы его создать.

Часто задаваемые вопросы

API (Application Programming Interface)

Набор правил, согласно которым программные системы взаимодействуют друг с другом и обмениваются данными. Для проведения платежей с использованием платежной платформы Paytransfer вам доступны следующие API:

• Gate API — программный интерфейс, с помощью которого вы можете проводить выплату пользователям. В Paytransfer выплата может быть инициирована с использованием Gate и Dashboard.

Dashboard

Пользовательский интерфейс, с помощью которого вы можете просматривать и анализировать информацию по проведенным платежам, инициировать оплату, возврат и выплату, контролировать и предотвращать попытки мошенничества и выполнять иные действия.

Gate

Компонент платежной платформы Paytransfer, обеспечивающий безопасное и эффективное взаимодействие между вашей системой и платежной платформой. В Paytransfer вы можете использовать Gate для проведения выплаты пользователям вашей системы. Взаимодействие с компонентом Gate осуществляется посредством Gate API.

Ваша система

Сайт, мобильное приложение или другой сервис, где вы предоставляете товары или услуги пользователям.

Оповещение (callback)

Техническое сообщение, которое платежная платформа отправляет на заданный URL-адрес вашей системы, чтобы сообщить определенную информацию, например о результате выполнения операции. Оповещение представляет собой HTTP-POST-запрос определенной структуры, но вы можете настроить структуру, параметры адресации и случаи, в которых отправляются оповещения, в соответствии с вашими потребностями.

Основная валюта

Валюта, заданная в качестве основной для платежного метода, настроенного в вашем проекте. В этой валюте будет обработана операция, если в запросе на проведение платежа вы передадите валюту, отличную от валюты, допустимой для платежного метода.

Платеж

Комплекс действий по выполнению запроса от вашей системы на перевод денежных средств между вашей системой и пользователем. В настоящий момент в Paytransfer поддерживаются следующие типы платежей:

• оплата (purchase) — перевод средств от пользователя в вашу систему;
• выплата (payout) — перевод средств от вашей системы к пользователю.

На стороне вашей системы каждому платежу присваивается свой идентификатор платежа. Убедитесь, что этот идентификатор не повторяется в рамках одного вашего проекта в Paytransfer.

Платежный метод

Способ, который выбирает пользователь для совершения платежа. Платежные методы могут относиться к разным типам и регионам, поддерживать определенные валюты и типы платежей, а также иметь различные пользовательские сценарии, особенности и ограничения.

Подпись

Строка данных, полученная заданным способом из набора подписываемых данных и секретного ключа. Подпись используется для обеспечения подлинности и целостности данных, передаваемых в технических запросах и оповещениях между вашей системой и Paytransfer. Подробнее о формировании подписи, см. раздел Подписывание и проверка подписи.

Пользователь

Лицо, которое оплачивает товары или услуги в вашей системе.

Проект

Сущность, созданная внутри платежной платформы и закрепленная за вашей системой. В Paytransfer у каждого проекта есть свой набор параметров, влияющих на проведение платежей и порядок взаимодействия платежной платформы с вашей системой (в частности, при работе с оповещениями).

Для каждого проекта вам выдается отдельный идентификатор проекта, который вы должны использовать при взаимодействии с платежной платформой.

Секретный ключ

Ключ симметричного шифрования данных. Секретный ключ уникален для каждого проекта и используется для формирования и проверки корректности цифровой подписи.

Тип платежного метода

Категория, которая включает в себя один или несколько платежных методов, одинаковых по способу проведения платежей.