Методы платежного шлюза
Создание ссылки на оплату
Переменные
Название переменной | Тип переменной | Описание переменной | Обязательность (да/нет) |
---|---|---|---|
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’a, т. е. содержащее metadata без изменений будет отправлено в callback после завершения обработки платежа в системе Онлайн-платежи | Нет |
orderId | string | Номер платежа в системе принимающей стороны. Только orderId проверяется на уникальность | Нет |
returnUrl | string | URL-адрес, на который будет перенаправлен пользователь после оплаты | Нет |
successUrl | string | URL-адрес, на который будет перенаправлен пользователь после оплаты, если транзакция была успешна. Если переменная передается вместе с returnUrl, то returnUrl не учитывается | Нет |
Данные переменные должны быть преданны через POST в формате JSON. Время жизни транзакции, в течение которой можно оплатить по ней, — 24 часа.
Пример JSON:
1 2 3 4 5 6 7 8 9
{ "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, к запросам необходимо добавлять заголовок следующего вида:
1
Authorization: Basic base64(login:password)
где login и password - это логин и пароль, полученные во время добавления нового сайта в Kassa24 Business
Пример отправляемых заголовков:
1
Authorization: Basic MTE1NjI4ODA2NDg5Mzc3OTc6cXdlcXdlMTIzMTIzMjEzMjEz
Пример отправляемых данных тело:
1 2 3 4
{ "merchantId": "11562880648937797", "amount":10000 }
В ответ на запрос придет JSON вида:
1 2 3 4
{ "url":"https://ecommerce.pult24.kz/payment/view?id=11111111111111", "id":"11111111111111" }
Название переменной | Описание переменной |
---|---|
URL | Ссылка, по которой необходимо перенаправить пользователя |
ID | Идентификатор транзакции в системе Онлайн-платежи |
Примеры кода
Пример отправки данных на PHP
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42
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; }
Технические требования для интеграции с сервисом «Онлайн-платежи»
- При интеграции с сервисом «Онлайн-платежи» необходимо реализовать возможность принимать Callback, имея домен или статичный IP.
- Также необходим SSL-сертификат (допускается самоподписанный).
- Сайт должен работать по протоколу HTTPS.
Получение данных (Callback)
После завершения обработки транзакции на адрес, переданный в поле callbackUrl (см. Создание ссылки на оплату) отправляется информация о состоянии транзакции. Основные состояния транзакции на этой ст адии:
- Транзакция проведена
- Время жизни транзакции закончилось
- Транзакция проведена не успешно
Данные приходят через POST в формате JSON. Данные приходят только с IP - 35.157.105.64, следует обязательно настроить фильтрацию по IP на стороне сервера мерчанта.
В случае успешной обработки ваш сервер должен ответить {"accepted":true}
в противном случае Callback будет отправлен повторно.
Пример данных ответа от системы Онлайн-платежи
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
{ "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” } }
Примеры коллбэков при отклонении транзакции
Транзакция не прошла по причине ошибки в самом кошельке
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "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" }
Транзакция отклонена, так как пользователь с таким телефоном не найден в системе кошелька
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "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" }
Транзакция отклонена, так как кошелек не идентифицирован
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "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" }
Транзакция отклонена из-за внутренней проблемы в системе
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
{ "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 | Содержит текст, кратко описывающий ошибку |
Статусы по транзакциям
Описание статусов и действия при двухэтапных транзакциях.
Коды статусов и действия при их получении.
Схема жизни транзакции
Запрос статуса транзакции
Ознакомиться с информацией о статусах транзакции можно по ссылке: Kassa24 Business запрос статуса транзакции.
Название статуса | Значение статуса | Описание статуса | Порядок действий |
---|---|---|---|
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 7.X
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
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
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21
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” для отмены транзакции соответственно. |
Пример тела запроса:
1 2 3 4
{ "ID":"1234567890123", "action":"approve" }
Пример успешного ответа:
1 2 3
{ "status":1 }
Пример неуспешного ответа.
В поле errorMessage будет содержатся описание ошибки.
1 2 3 4
{ "status":3, "error":"Карта клиента заблокирована" }