Перейти к основному контенту

Методы платежного шлюза

Создание ссылки на оплату

Переменные

Название переменной  Тип переменной  Описание переменной  Обязательность (да/нет)
amount int Сумма платежа в тиынах (1 тенге = 100 Тиын) Да
callbackUrl string URL-адрес, на который будет отправлена информация после изменения статуса платежа Нет
customerData object Параметр, в котором могут содержаться элементы email (необязательно), phone (необязательно), которые будут автоматически подставлены в форму оплаты Нет
demo boolean Если true, то платеж будет произведен в демо-режиме, при котором средства не списываются со счета пользователя и не перечисляются на счет коммерсанта. По умолчанию false Нет
description string Параметр, являющий собой короткое описания платежа. Если указан, то будет отображен пользователю на форме оплаты Нет
failUrl string URL-адрес, на который будет перенаправлен пользователь после оплаты, если транзакция была неуспешна. Если переменная передается вместе с returnUrl, то returnUrl не учитывается Нет
merchantId string Продублировать логин в это поле Да
metadata object Параметр, в котором могут содержаться любые поля и значения, необходимые мерчанту для приема и обработки платежа на своей стороне при получении callback’а, т. е. содержимое metadata без изменений будет отправлено в callback после завершения обработки платежа в системе Онлайн-платежи Нет
orderId string Номер платежа в системе принимающей стороны. Только OrderID проверяется на уникальность
Нет
returnUrl string URL-адрес, на который будет перенаправлен пользователь после оплаты Нет
successUrl string URL-адрес, на который будет перенаправлен пользователь после оплаты, если транзакция была успешна. Если переменная передается вместе с returnUrl, то returnUrl не учитывается Нет

Данные переменные должны быть преданны через POST в формате JSON. Время жизни транзакции, в течение которой можно оплатить по ней, — 24 часа.

Пример JSON:

{
    "merchantId": "123123123123123",
    "callbackUrl": "http://example.com/callback",
    "description": "описание",
    "returnUrl": "http://example.com",
    "amount": 10000,(Транзакция на 100 тенге. Сумма транзакции указывается в тиин(1 тенге = 100 тиин))
    "orderId": "123",
    "demo": true
}

Отправка данных

Ссылка на создание платежа: https://ecommerce.pult24.kz/payment/create. Данные защищены Basic access authentication. Для авторизации используется механизм Basic access authentication, к запросам необходимо добавлять заголовок следующего вида:

Authorization: Basic base64(login:password)

где login и password - это логин и пароль, полученные во время добавления нового сайта в Kassa24 Business

Пример отправляемых заголовков:

Authorization: Basic MTE1NjI4ODA2NDg5Mzc3OTc6cXdlcXdlMTIzMTIzMjEzMjEz

Пример отправляемых данных тело:

{
    "merchantId": "11562880648937797",
    "amount":10000
}

В ответ на запрос придет JSON вида:

{
  "url":"https://ecommerce.pult24.kz/payment/view?id=11111111111111",
  "id":"11111111111111"
}
Название переменной  Описание переменной
URL Ссылка, по которой необходимо перенаправить пользователя
ID Идентификатор транзакции в системе Онлайн-платежи

Примеры кода

Пример отправки данных на PHP
function createPayment (array $data){
 
        if($data["amount"]<=0){
            throw new Exception('цена не указана или меньше 0');
        }
        $dataArray=array(
            "merchantId"=>      strval($data["merchantId"]),
            "callbackUrl"=>     strval($data["callback"]),
            "orderId"   =>      strval($data['orderId']),
            "description"=>     strval($data['description']),
            "demo"      =>      $data['demo']=== 'false'? false: true,
            "returnUrl" =>      strval($data['returnUrl']),
            "amount"  =>        (int)$data["amount"]
        );
 
        if (isset($data['email'])|| isset($data['phone'])){
            $dataArray['customerData']=array(
                "email"     =>      isset($data['email'])?$data['email']:"",
                "phone"     =>      isset($data['phone'])?$data['phone']:""
            );
        }
        if (isset($data['metadata'])){
            $dataArray["metadata"]=$data['metadata'];
        }
 
        $data_string = json_encode ($dataArray, JSON_UNESCAPED_UNICODE);
        $curl = curl_init( "https://ecommerce.pult24.kz/payment/create");
        curl_setopt($curl, CURLOPT_CUSTOMREQUEST, "POST");
        $headers = array(
            "Content-Type: application/json",
            "Authorization: Basic " . base64_encode($data["login"].':'.$data["pass"]),
            'Content-Length: ' . strlen($data_string)
        );
        curl_setopt($curl, CURLOPT_POSTFIELDS, $data_string);
        curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
         
        $result = curl_exec($curl);
        curl_close($curl);
        $result=json_decode($result);
        return $result;
    }

Технические требования для интеграции с сервисом «Онлайн-платежи»

  1. При интеграции с сервисом «Онлайн-платежи» необходимо реализовать возможность принимать Callback, имея домен или статичный IP.
  2. Также необходим SSL-сертификат (допускается самоподписанный).
  3. Сайт должен работать по протоколу HTTPS.

Получение данных (Callback)

После завершения обработки транзакции на адрес, переданный в поле callbackUrl (см. Создание ссылки на оплату) отправляется информация о состоянии транзакции. Основные состояния транзакции на этой стадии:

  1. Транзакция проведена
  2. Время жизни транзакции закончилось
  3. Транзакция проведена не успешно

Данные приходят через POST в формате JSON. Данные приходят только с IP - 35.157.105.64, следует обязательно настроить фильтрацию по IP на стороне сервера мерчанта.

В случае успешной обработки ваш сервер должен ответить {"accepted":true} в противном случае Callback будет отправлен повторно.

Пример данных ответа от системы Онлайн-платежи

{
    "orderId":"123",
    "id":"11111111111111",
    "amount":10000,
    "commission":100,
    "commissionIncluded":true,
    "attempt":1,
    "returnUrl":"http://example.com/",
    "callbackUrl":"http://example.com/callback",
    "date":"2006-01-02T15:04:05",
    "dateOut":"2006-01-02T15:04:05",
    "status":1,
    "errCode":0,
    "errMessage":"Ошибок нет",
    “metadata”:{
        “session”:” 3135c7fe-272f-46d0-a5f8-1ab2a59ac17c”
    }
}

Примеры коллбэков при отклонении транзакции

Транзакция не прошла по причине ошибки в самом кошельке
 {
 "orderId": "1",
 "id": "12673068480987148",
 "description": "Выплата на кошелёк Plus24",
 "amount": 500000,
 "commission": 14250,
 "commissionIncluded": true,
 "attempt": 1,
 "returnUrl": "https://olimpbet.kz",
 "merchantId": "12137055080906936",
 "invoiceId": "",
 "callbackUrl": "https://betapi.kz/payin/kassa24card",
 "date": "2021-08-18T00:55:57",
 "dateOut": "2021-08-18T00:57:11",
 "demo": false,
 "status": 0,
 "errCode": "220",
 "errMessage": "Транзакция отклонена внешней системой",
 "email": "",
 "phone": "77714955747"
  }
Транзакция отклонена, так как пользователь с таким телефоном не найден в системе кошелька
{
   "orderId":"2",
   "id":"12673068480987148",
   "description":"Выплата на кошелёк Plus24",
   "amount":500000,
   "commission":14250,
   "commissionIncluded":true,
   "attempt":1,
   "returnUrl":"https://olimpbet.kz",
   "merchantId":"12137055080906936",
   "invoiceId":"",
   "callbackUrl":"https://betapi.kz/payin/kassa24card",
   "date":"2021-08-18T00:55:57",
   "dateOut":"2021-08-18T00:57:11",
   "demo":false,
   "status":0,
   "errCode":"220",
   "errMessage":"Пользователь не найден",
   "email":"",
   "phone":"77714955747"
    }
Транзакция отклонена, так как кошелек не идентифицирован
{
"orderId":"3",
   "id":"12673068480987148",
   "description":"Выплата на кошелёк Plus24",
   "amount":500000,
   "commission":14250,
   "commissionIncluded":true,
   "attempt":1,
   "returnUrl":"https://olimpbet.kz",
   "merchantId":"12137055080906936",
   "invoiceId":"",
   "callbackUrl":"https://betapi.kz/payin/kassa24card",
   "date":"2021-08-18T00:55:57",
   "dateOut":"2021-08-18T00:57:11",
   "demo":false,
   "status":0,
   "errCode":"220",
   "errMessage":"Кошелёк пользователя не идентифицирован",
   "email":"",
   "phone":"77714955747"
   }
Транзакция отклонена из-за внутренней проблемы в системе
 {
 "orderId":"3",
   "id":"12673068480987148",
   "description":"Выплата на кошелёк Plus24",
   "amount":500000,
   "commission":14250,
   "commissionIncluded":true,
   "attempt":1,
   "returnUrl":"https://olimpbet.kz",
   "merchantId":"12137055080906936",
   "invoiceId":"",
   "callbackUrl":"https://betapi.kz/payin/kassa24card",
   "date":"2021-08-18T00:55:57",
   "dateOut":"2021-08-18T00:57:11",
   "demo":false,
   "status":0,
   "errCode":"230",
   "errMessage":"Срок жизни платежа истек",
   "email":"",
   "phone":"77714955747"
   }

Описание значений полей ответа от системы Онлайн-платежи

Описание значения поля status
Значение статуса Описание статуса
0 Неуспешная транзакция
1 Успешная транзакция
2 Сумма успешно заблокирована (для двухэтапных транзакций)
3 Транзакция отменена или был совершен возврат
Описание значения поля errCode
Значение статуса Описание статуса
0 Ошибки нет
220 Транзакция обработана в ошибку, информация об ошибке находится в поле errMessage
230 Время жизни транзакции истекло
Описание второстепенных полей, возвращаемых в Callback
Название переменной Описание переменной
attempt Номер попытки оплаты
commission Комиссия с транзакции указана в тиынах
commissionIncluded Тип комиссии. Если true, то комиссия была взята с клиента, иначе — с мерчанта
errMessage Содержит текст, кратко описывающий ошибку

Статусы по транзакциям

Описание статусов и действия при двухэтапных транзакциях.

Коды статусов и действия при их получении. 

Схема жизни транзакции

Схема_жизни_транзакции_11.png

Название статуса Значение статуса Описание статуса Порядок действий
CREATED 0 Транзакция создана
RECREATED 1 Транзакция создана заново (повторная попытка)
PROCESSING_STARTED 110 Пользователь получил форму эквайринга. Отправка Callback не требуется
PROCESSING_IN_PROGRESS 111 Получен нефинальный статус эквайринга
PROCESSING_WAIT_CONFIRM 112 Ожидается ввод кода подтверждения
FINALIZING_IN_PROGRESS 113 Транзакция в процессе финализации
CANCELLING_IN_PROGRESS 114 Транзакция в процессе отмены
ATTEMPT_FAILED 130 Попытка провалилась в процессе оплаты Повторите запрос подтверждения
PROCESSING_HOLDED 120 Пользователь успешно забронировал платеж (холд/блок денег на карте) Подтвердите либо отклоните транзакцию
PH_CALLBACK_SUCCESS 121 Отправка коллбэка по захолдированному платежу успешна Система ждет действий с вашей стороны
PH_CALLBACK_FAILED 122 Отправка коллбэка по захолдированному платежу ошибочна Повторите запрос статуса транзакции. Далее подтвердите либо отклоните платеж.
PH_FINISHED 240 Транзакция успешно финализирована
PH_FINISH_ERROR 242 Транзакция финализирована с ошибкой. Повторная финализация невозможна/не имеет смысла
PROCESSING_SUCCESS 210 Транзакция успешно проведена. Отправка Callback не требуется Пометьте в вашей системе транзакцию как неуспешную
PS_CALLBACK_SUCCESS 211 Транзакция проведена. Callback отправлен и успешно обработан В вашей системе транзакция должна пометиться как успешно проведенная
PS_CALLBACK_FAILED 212 Транзакция проведена. Callback отправлен, но не обработан со стороны мерчанта Проверьте интеграцию, так как наша система не получила корректный ответ от вашей системы
PROCESSING_FAILED 220 Транзакция отклонена банком. Callback не отправлялся Пометьте в вашей системе транзакцию как неуспешную
PF_CALLBACK_SUCCESS 221 Транзакция отклонена банком. Callback отправлен и успешно обработан Ваша система ответила корректно и пометила транзакцию как неуспешную
PF_CALLBACK_FAILED 222 Транзакция отклонена банком. Callback отправлен, но не обработан со стороны мерчанта Проверьте интеграцию, так как наша система не получила корректный ответ от вашей системы
TIMEOUT 230 Срок ввода данных в форме оплаты истек. Callback не отправлялся Пометьте в вашей системе транзакцию как неуспешную
T_CALLBACK_SUCCESS 231 Срок ввода данных в форме оплаты истек. Callback отправлен и успешно обработан Ваша система ответила корректно и пометила транзакцию как неуспешную
T_CALLBACK_FAILED 232 Срок ввода данных в форме оплаты истек. Callback отправлен, но не обработан со стороны мерчанта Проверьте интеграцию, так как наша система не получила корректный ответ от вашей системы
PAYMENT_CANCELLED 250 Двухэтапная транзакция отменена. Callback не отправлялся Пометьте транзакцию как неуспешную или отмененную
PAYMENT_CANCELLED 251 Двухэтапная транзакция отменена. Callback отправлен и успешно обработан Ваша система пометила транзакцию как неуспешную или отмененную
PAYMENT_CANCELLED 252 Двухэтапная транзакция отменена. Callback отправлен, но не обработан со стороны мерчанта Проверьте интеграцию, так как наша система не получила корректный ответ от вашей системы
PAYMENT_REFUNDED 260 По транзакции был осуществлен возврат. Callback не отправлялся Пометьте возврат как неуспешный или отмененный
PAYMENT_REFUNDED 261 По транзакции был осуществлен возврат. Callback отправлен и успешно Ваша система пометила возврат как успешный
PAYMENT_REFUNDED 262 По транзакции был осуществлен возврат. Callback отправлен, но не обработан со стороны мерчанта Проверьте интеграцию, так как наша система не получила корректный ответ от вашей системы

Примеры кода

Пример на PHP

Пример на PHP 7.X
if ($_SERVER["REMOTE_ADDR"]!="35.157.105.64") {//проверяем ip адрес с которого пришел ответ
    echo "noop";
    die();
}
$json = json_decode (file_get_contents('php://input'));
$out=true;
if ($json->status==1){
    file_put_contents("123.txt", "оплата прошла\n", FILE_APPEND | LOCK_EX);
}else{
    file_put_contents("123.txt", "оплата не прошла\n", FILE_APPEND | LOCK_EX);
}
header( 'HTTP/1.1 200 OK' );
if(gettype($out)=="boolean"){
    echo '{"accepted":'.(($out) ? 'true' : 'false').'}';
}else{
    throw  new  Exception($out);
}
Пример на PHP 5.X
if ($_SERVER["REMOTE_ADDR"]!="35.157.105.64") {//проверяем ip адрес с которого пришел ответ
    echo "noop";
    die();
}
$json = json_decode (file_get_contents('php://input'));
$out=true;
if ($json["status"]==1){
    file_put_contents("123.txt", "оплата прошла\n", FILE_APPEND | LOCK_EX);
}else{
    file_put_contents("123.txt", "оплата не прошла\n", FILE_APPEND | LOCK_EX);
}
header( 'HTTP/1.1 200 OK' );
if(gettype($out)=="boolean"){
    echo '{"accepted":'.$out.'}';
}else{
    throw  new  Exception($out);
}

Финализация платежа

Данная операция применяется для следующих операций: двухэтапный платеж и двухэтапная выплата.

Формат данных:

Название переменной  Тип переменной Описание переменной
ID string Идентификатор транзакции в системе Онлайн-платежи. Может быть получен 2 способами при создании транзакции или при получении Callback из поля id.
action string Тип действия. Может принимать значения “approve” для подтверждения и “reject” для отмены транзакции соответственно.

Пример тела запроса:

{
    "ID":"1234567890123",
    "action":"approve"
}

Пример успешного ответа:

{
    "status":1
}

Пример неуспешного ответа.

В поле errorMessage будет содержатся описание ошибки.

{
    "status":3,
    "error":"Карта клиента заблокирована"
}
Наверх