API. Подключение

МФО — https://api.vepay.online/mfo
Мерчант/виджет — https://api.vepay.online/merchant
УПРИД — https://vepay.online/api/uprid.php

Адрес сервера для запросов — https://api.vepay.online/, тестовый — https://test.vepay.online

Данные передаются в теле POST запроса с JSON формате, кодировка UTF-8.
Идентификатор и ключ МФО/Мерчанта выдается после регистрации в системе.
В заголовке запроса передаются параметра авторизации:

X-Mfo (для API МФО) X-Login (API Краутфандинг, Мерчант)	string	Идентификатор МФО/Мерчанта
X-Token	string	Токен авторизации

Токен формируется по алгоритму:
sha1(sha1(ключ)+ sha1(тело запроса)), где sha1 возвращает 40-символьную строку с шестнадцатеричным числом хэша.

При успешной обработке запроса возвращается код ответа HTTP 200. При ошибке авторизации код HTTP 401 Unauthorized. При других ошибках возвращается ошибка 500 Internal Server Error или соответствующая.

Также в теле запроса возвращаются поля в формате JSON:

Имя параметра	Описание	Пример
name	HTTP описание ошибки	Unauthorized
message	Дополнительное сообщение об ошибке
code	Ошибка	0
status	HTTP код ошибки	401

Пример кода, подключения к API

<?php

          $data = json_encode(["id" => 123]);

          $login="123";

          $key="12345456780";

          $token=sha1(sha1($key).sha1($data));

          $link = "https://api.vepay.online/mfo/out/state";

          

          $curl=curl_init();

          curl_setopt($curl,CURLOPT_RETURNTRANSFER,true);

          curl_setopt($curl,CURLOPT_POSTFIELDS,$data);

          curl_setopt($curl,CURLOPT_CUSTOMREQUEST,'POST');

          curl_setopt($curl,CURLOPT_URL,$link);

          curl_setopt($curl,CURLOPT_HEADER,false);

          curl_setopt($curl,CURLOPT_HTTPHEADER, [

          'Content-type: application/json',

          'Accept: application/json',

          'X-Mfo: '.$login,

          'X-Token: '.$token

          ]);

          curl_setopt($curl,CURLOPT_SSL_VERIFYPEER,0);

          curl_setopt($curl,CURLOPT_SSL_VERIFYHOST,0);

          

          $out=curl_exec($curl);

          curl_close($curl);

          

          $Response=json_decode($out,true);

          print_r($Response);

Пример оплаты услуг через API мерчанта1. Оплата - через API отправляется запрос оплаты

/merchant/pay

          {

            "amount": 100,

            "extid": "123e4567-e89b-12d3-a456-426655440000",

            "descript": "test",

            "timeout": 11,

            "successurl": "https://example.org/success",

            "failurl": "https://example.org/fail",

            "cancelurl": "https://example.org/cancel",

            "regcard": 0,

            "postbackurl": "https://example.org/postbackurl",

            "postbackurl_v2": "https://example.org/postbackurl_v2"

          }

          

          Ответ:

          {

            "status": 1,

            "id": 11022,

            "url": "https://test.vepay.online/pay/form/11022",

            "message": ""

          }

2. Пользователь перенаправляется на страницу оплаты (по url из ответа)

3. Если не используется получение статуса через обратный запрос, то необходимо проверить его статус:

/merchant/state

          {

            "id": 11022

          }

          

          Ответ:

          {

            "status": 1,

            "message": "Успешно"

          }

В коде ответа может присутствовать параметр RC (response code). Справочник по rc-кодам:

Код	Значение	Действие	Описание	VISA	MC	Мир
00	Successful approval/completion or V.I.P. PIN verification is successful	Approved	Операция одобрена	+	+	+
01	Refer to card issuer	Decline	Связаться с банком, выпустившим карту	+	+
02	Refer to card issuer, special condition	Decline	Связаться с банком, выпустившим карту. Возможны особые условия.	+
03	Invalid merchant or service provider	Decline	Неверно указан мерчант или сервис	+	+	+
04	Pick up card	Decline	Изъятие карты	+	+	+
05	Do not honor	Decline	Не оплачивается	+	+	+
06	Error	Decline	Ошибка транзакции	+
07	Pick up card, special condition (other than lost/stolen card)	Decline	Изъятие карты, при иных условиях, чем потеря карты или украденная карта.	+
08	Honor with ID	Approved	Одобрение операции		+
10	Partial approval	Approved	Частичное одобрение	+	+
11	V.I.P. approval	Approved	Если генерируется, то заменяется для возвращения на код 00 по причине соблюдения безопасности.	+
12	Invalid transaction	Decline	Неверная транзакция	+	+	+
13	Invalid amount (currency conversion field overflow); or amount exceeds maximum for card program	Decline	Отклоняется, т.к. недостаточно средств на счете.	+	+	+
14	Invalid account number (no such number)	Decline	Неправильный номер счета	+
14	Invalid card number	Decline	Неправильный номер карты		+	+
15	No such issuer	Decline	Неизвестный банк, выпустивший карту.	+	+	+
19	Re-enter transaction	Decline	Повторная транзакция	+
21	No action taken (unable to back out prior transaction)	Decline	Транзакция не проводится, нет данных для ее отката.	+
25	Unable to locate record in file, or account number is missing from the inquiry	Decline	Не найдены данные в базе или неправильный номер счета в запросе.	+
28	File is temporarily unavailable	Decline	Данные временно недоступны	+
30	Format error	Decline	Неправильный формат запроса. Операция отклонена		+	+
39	No credit account	Decline	Ненадежный счет	+
41	Pick up card (lost card)	Decline	Изъятие карты, карта числится утерянной.	+	+	+
43	Pick up card (stolen card)	Decline	Изъятие карты, карта числится украденной.	+	+	+
51	Insufficient funds	Decline	Недостаточно средств	+	+	+
52	No checking account	Decline	Нет текущего счета	+
53	No savings account	Decline	Нет сберегательного счета	+
54	Expired card	Decline	Закончился срок действия карты	+	+	+
55	Incorrect PIN	Decline	Неверный PIN	+	+	+
57	Transaction not permitted to cardholder	Decline	Операция не разрешена владельцу карты	+	+	+
58	Transaction not allowed at terminal	Decline	Транзакция на терминале запрещена	+	+	+
59	Suspected fraud	Decline	Подозревается мошенничество	+
61	Activity amount limit exceeded	Decline	Превышено число попыток. Данный код может использоваться для переадресации,	+	+
62	Restricted card (for instance, in Country Exclusion table)	Decline	Запрет на карту	+	+	+
63	Security violation	Decline	Нарушение правил безопасности	+	+	+
64	Transaction does not fulfill AML requirement	Decline	Транзакция не удовлетворяет правилам контроля за "отмыванием" денег	+
65	Activity count limit exceeded	Decline	Превышен лимит количества действий	+	+
70	Contact Card Issuer	Decline	Требуется контакт с банком - эквайером			+
71	PIN Not Changed	Decline	PIN не изменен. Операция отклонена		+
75	Allowable number of PIN-entry tries exceeded	Decline	Превышено допустимое количество попыток ввода PIN- кода	+	+	+
76	Unable to locate previous message (no match on retrieval reference number)	Decline	Невозможно найти предыдущее сообщение (нет совпадений по поисковому номеру)	+
76	Invalid/nonexistent “To Account” specified	Decline	Операция отклонена		+
77	Previous message located for a repeat or reversal, but repeat or reversal data inconsistent with original message	Decline	Предыдущее сообщение находится в состоянии повторения или отмены,но повторение или отмена, несовместимых с текущим сообщением	+
77	Invalid/nonexistent “From Account” specified	Decline	Операция отклонена		+
78	“Blocked, first used”—Transaction from new cardholder, and card not properly unblocked	Decline	Карта была заблокирована и не разблокирована нормально.	+
78	Invalid/nonexistent account specified (general)	Decline	Операция отклонена		+
78	Invalid/nonexistent account specified	Decline	Введен неправильный/ несуществующий счет			+
79	Transaction reversed	Decline	Транзакция отменена	+
80	Visa transactions: credit issuer unavailable.Private label: invalid date	Decline	Операции VISA: кредитный эмитент недоступен. Примечание: недействительная дата	+
81	PIN cryptographic error found (error found by VIC security module during PIN decryption)	Decline	Обнаружена криптографическая ошибка PIN (ошибка найдена модулембезопасности VIC при расшифровке PIN-кода)	+
81	Domestic Debit Transaction Not Allowed (Regional use only)	Decline	Операция отклонена		+
82	Negative Online CAM, dCVV, iCVV, or CVV results Or Offline PIN authentication interrupted	Decline	Отрицательные результаты online проверок CAM, dCVV, iCVV или CVV или автономная аутентификация PIN прервана	+
84	Invalid Authorization Life Cycle	Decline	Неправильный процесс авторизации. Операция отклонена		+
85	No reason to decline request for account number verification, address verification, CVV2 verification, or credit voucher or merchandise return	+	Нет причин отклонять запрос на проверку номера счета, проверка адреса, CVV2 подтверждение или кредитный ваучер или возврату товара.	+	+
86	Cannot verify PIN	Decline	Невозможно проверить PIN	+	+	+
87	Purchase Amount Only, No Cash Back Allowed	Approved	Только покупки, кэшбек запрещен.		+
88	Cryptographic failure	Decline	Проблема декодирования. Операция отклонена		+	+
89	Unacceptable PIN— Transaction Declined—Retry	Decline	Недопустимый PIN, транзакция отклонена, повтор.		+
91	Issuer unavailable or switch inoperative (STIP not applicable or available for this transaction) Issuers can respond with this code, which V.I.P. passes tothe acquirer without invoking stand-in processing (STIP). Issuer processors use the code to indicate they cannot perform authorization on issuers’ behalf.Code causes decline at POS.	Decline	Эмитент недоступен или коммутатор не работает (STIP не применимо или доступно для этой транзакции) Эмитенты могут ответить этим кодом, по которому VIP клиент переходит к эквайеру без вызова stand-in обработки (STIP). Процессинги эмитента используют код для указания того, чтоони не могут выполнить авторизацию от имени эмитента. Код вызывает отклонение операции в POS.	+	+	+
92	Financial institution or intermediate network facility cannot be found for routing	Decline	Финансовая организация или сетевые ресурсы не могут найти маршрутизацию до объекта	+	+	+
93	Transaction cannot be completed; violation of law	Decline	Транзакция не может быть завершена; обнаружено нарушение законодательства	+
94	Duplicate transaction. Transaction submitted containing values in tracing data fields that duplicate values in a previous transaction.	Decline	Дублирующая транзакция. Сопровождающие данные аналогичны значениям в предыдущей транзакции.	+	+	+
96	System malfunction	Decline	Неисправность системы	+	+	+
B1	Surcharge amount not permitted on Visa cards(U.S. acquirers only)	Decline	Доплата не допускается на картах Visa(Только для США). Только для POS, для ATM можно.	+
N0	Force STIP	Decline	Задействовать STIP	+
N3	Cash service not available	Decline	Работа с наличными запрещена	+
N4	Cashback request exceeds issuer limit	Decline	Запрос кэшбека превысил лимит	+
N7	Decline for CVV2 failure	Decline	Отклонено т.к. CVV2 неверен	+
N8	Transaction amount exceeds pre - authorized approval amount	Decline	Сумма транзакции превышает предварительно авторизованную сумма	+
P2	Invalid biller information	Decline	Неверная информация биллера	+
P5	PIN change/unblock request declined	Decline	Запрос на изменение/разблокировку PIN отклонен	+
P6	Unsafe PIN	Decline	Небезопасный PIN	+
R0	Stop payment order	Decline	Остановлено платежное поручение	+
R1	Revocation of authorization order	Decline	Авторизация отозвана	+
R3	Revocation of all authorizations order	Decline	Все авторизации отозваны	+
Z3	Unable to go online; declined	Decline	Не возможно выполнить онлайн	+
XA	Forward to issuer	Decline	Отправить банку, выпустившему карту	+
XD	Forward to issuer	Decline	Отправить банку, выпустившему карту	+
Q1	Card authentication failed Or Offline PIN authentication interrupted	Decline	Ошибка аутентификации карты или прервана аутентификация с помощью PIN	+

Host to Host API v.1

Адрес сервера для запросов — https://api.vepay.online/h2hapi/v1

тестовый — https://test.vepay.online/h2hapi/v1

Описание методов

Метод: POST

url: /invoices

Создает Счет с указанными данными и возвращает его в ответе

Parameters: No parameters

Тело запроса:


                              {
                  "amountFractional": 50000,
                  "currencyCode": "RUB",
                  "documentId": "КА-123/12121212",
                  "externalId": "18a2f5e5-6548-4879-88db-b272c7d6b473",
                  "description": "Счет №1457",
                  "timeoutSeconds": 3000,
                  "successUrl": "https://www.site.com/example.html",
                  "failUrl": "https://www.site.com/example.html",
                  "cancelUrl": "https://www.site.com/example.html",
                  "client": {
                    "fullName": "Терентьев Михаил Павлович",
                    "address": "г. Москва, дом 5",
                    "email": "user@mail.com",
                    "login": "ExampleLogin",
                    "phone": "+7999123456",
                    "zip": "234234234",
                    "cardNumber": "123456******7890",
                    "cardType": "MASTERCARD",
                    "issuingBank": "BANK NAME"
                  }
                }

Ответ код 201 OK


                              {
                  "id": 2735093,
                  "uuid": "123e4567-e89b-12d3-a456-426655440000",
                  "amountFractional": 50000,
                  "currencyCode": "RUB",
                  "documentId": "КА-123/12121212",
                  "externalId": "18a2f5e5-6548-4879-88db-b272c7d6b473",
                  "description": "Счет №1457",
                  "timeoutSeconds": 3000,
                  "successUrl": "https://www.site.com/example.html",
                  "failUrl": "https://www.site.com/example.html",
                  "cancelUrl": "https://www.site.com/example.html",
                  "client": {
                    "fullName": "Терентьев Михаил Павлович",
                    "address": "г. Москва, дом 5",
                    "phone": "+7999123456",
                    "zip": "234234234",
                    "cardNumber": "123456******7890",
                    "cardType": "MASTERCARD",
                    "issuingBank": "BANK NAME"
                  },
                  "status": {
                    "id": 1,
                    "name": "Оплачен",
                    "bank": "FortaTech",
                    "errorInfo": "string",
                    "bankErrorCode": "string",
                    "clientFee": 0,
                    "merchantFee": 0,
                    "bankFee": 0
                  }
                }

Ответ код 409 Услуга не найдена / Шлюз не найден


                              {
                  "name": "Conflict",
                  "message": "Ошибка.",
                  "code": 0,
                  "status": 409
                }

Ответ код 422 Ошибки валидации. JSON-структура аналогичная запросу, где текст ошибки в значениях атрибутов объекта

Метод: GET

url: /invoices/{id}

Возвращает Счет

Parameters: ID или UUID счета, ID является устаревшим (string)

Ответ код 200 OK


                              {
                  "id": 2735093,
                  "uuid": "123e4567-e89b-12d3-a456-426655440000",
                  "amountFractional": 50000,
                  "currencyCode": "RUB",
                  "documentId": "КА-123/12121212",
                  "externalId": "18a2f5e5-6548-4879-88db-b272c7d6b473",
                  "description": "Счет №1457",
                  "timeoutSeconds": 3000,
                  "successUrl": "https://www.site.com/example.html",
                  "failUrl": "https://www.site.com/example.html",
                  "cancelUrl": "https://www.site.com/example.html",
                  "client": {
                    "fullName": "Терентьев Михаил Павлович",
                    "address": "г. Москва, дом 5",
                    "email": "user@mail.com",
                    "login": "ExampleLogin",
                    "phone": "+7999123456",
                    "zip": "234234234",
                    "cardNumber": "123456******7890",
                    "cardType": "MASTERCARD",
                    "issuingBank": "BANK NAME"
                  },
                  "status": {
                    "id": 1,
                    "name": "Оплачен",
                    "bank": "FortaTech",
                    "errorInfo": "string",
                    "bankErrorCode": "string",
                    "clientFee": 0,
                    "merchantFee": 0,
                    "bankFee": 0
                  }
                }

Ответ код 404 Счет не найден


                              {
                  "name": "Not Found",
                  "message": "Объект не найден.",
                  "code": 0,
                  "status": 404
                }

Метод: PUT

url: /invoices/{id}/payment

Проводит оплату Счета и возвращает объект с URL страницы для прохождения проверки 3DS

Parameters: ID или UUID счета, ID является устаревшим (string)

Тело запроса:


                              {
                  "ip": "108.177.16.21",
                  "card": {
                    "cardNumber": "4111111111111111",
                    "cardHolder": "Terentiev Mihail",
                    "expires": "0122",
                    "cvc": "123"
                  },
                  "headerMap": {
                    "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36",
                    "accept": "text/html",
                    "acceptLanguage": "ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7"
                  },
                  "browserData": {
                    "screenHeight": 800,
                    "screenWidth": 1200,
                    "windowHeight": 800,
                    "windowWidth": 1200,
                    "timezoneOffset": -180,
                    "language": "ru-RU",
                    "colorDepth": 24,
                    "javaEnabled": false
                  }
                }

Ответ код 200 OK


                              {
                  "acsRedirect": {
                    "status": "OK",
                    "url": "https://some-access-control-server.com/3ds?payId=123",
                    "method": "POST",
                    "postParameters": {
                      "pa_req": "K8QufpC0UQXOoYcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCk",
                      "md": "YcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCkGMifQ==",
                      "term_url": "https://api.vepay.online/pay/orderdone/12345"
                    }
                  },
                  "card": {
                    "cardNumber": "4111111111111111",
                    "cardHolder": "Terentiev Mihail",
                    "expires": "0122"
                  }
                }

Ответ код 404 Счет не найден


                              {
                  "name": "Not Found",
                  "message": "Объект не найден.",
                  "code": 0,
                  "status": 404
                }

Ответ код 409 Время ожидания оплаты вышло / Шлюз не найден / Ошибка проведения платежа...


                              {
                  "name": "Conflict",
                  "message": "Ошибка.",
                  "code": 0,
                  "status": 409
                }

Ответ код 500 Ошибка подключения к банку...


                              {
                  "name": "Internal Server Error",
                  "message": "Ошибка подключения к банку.",
                  "code": 0,
                  "status": 500
                }

Метод: GET

url: /invoices/{id}/payment

Возвращает Оплату Счета

Parameters: ID или UUID счета, ID является устаревшим (string)

Ответ код 200 OK


                              {
                  "acsRedirect": {
                    "status": "OK",
                    "url": "https://some-access-control-server.com/3ds?payId=123",
                    "method": "POST",
                    "postParameters": {
                      "pa_req": "K8QufpC0UQXOoYcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCk",
                      "md": "YcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCkGMifQ==",
                      "term_url": "https://api.vepay.online/pay/orderdone/12345"
                    }
                  },
                  "card": {
                    "cardNumber": "4111111111111111",
                    "cardHolder": "Terentiev Mihail",
                    "expires": "0122"
                  }
                }

Ответ код 404 Счет не найден, либо оплата по счету не произведена


                              {
                  "name": "Not Found",
                  "message": "Объект не найден.",
                  "code": 0,
                  "status": 404
                }

Объект Оплата Счета с данными карты и переадресации на проверку 3DS (ACS).

Переадресация

Если объект с данными переадресации (acsRedirect) не null, необходимо сделать переадресацию браузера клиента на страницу прохождения 3DS методом, указанным в поле method объекта.

Возможные значения поля method:

GET

Произвести переадресацию на страницу, указанную в поле url.

Пример объета acsRedirect:


                              {
                  "status": "OK",
                  "method": "GET"
                  "url": "https://some-access-control-server.com/3ds?payId=123"
                }

Пример реализации в коде на JavaScript, который нужно выполнить в браузере клиента:


                              window.location = acsRedirect.url;

POST

В данном случае нужно добавить в тело страницы оплаты и отправить (с помощью JavaScript) HTML-форму с методом POST и параметрами, указанными в объекте postParameters на адрес, указанный в поле url. Поля объекта postParameters не фиксированные и могут измениться (предоставляются банком).

Пример объета acsRedirect:


                              {
                  "status": "OK",
                  "method": "POST"
                  "url": "https://some-access-control-server.com/3ds?payId=123",
                  "postParameters": {
                    "pa_req": "K8QufpC0UQXOoYcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCk",
                    "md": "YcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCkGMifQ==",
                    "term_url": "https://api.vepay.online/pay/orderdone/12345"
                  }
                }

Пример в HTML:


                              <form id="myForm" method="POST" action="https://some-access-control-server.com/3ds?payId=123">
                  <input type="hidden" name="pa_req" value="K8QufpC0UQXOoYcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCk"/>
                  <input type="hidden" name="md" value="YcNlfT857Tvu15Wli12WXyvCyTX8AKY2QyMUCkGMifQ=="/>
                  <input type="hidden" name="term_url" value="https://api.vepay.online/pay/orderdone/12345"/>
                </form>
                <script>
                  document.getElementById('myForm').submit();
                </script>

Пример чистой (без HTML) реализации в коде на JavaScript, который нужно выполнить в браузере клиента:


                              // создаем и добавляем на страницу форму
                const form = document.createElement('form');
                form.method = 'POST';
                form.action = acsRedirect.url;
                document.body.appendChild(form);
                // добавляем в форму поля
                for (const key in acsRedirect.postParameters) {
                  const hiddenField = document.createElement('input');
                  hiddenField.type = 'hidden';
                  hiddenField.name = key;
                  hiddenField.value = acsRedirect.postParameters[key];
                  form.appendChild(hiddenField);
                }
                // отправляем форму
                form.submit();

Пример реализации на JavaScript с использованием jQuery:


                              const $form = $('')
                  .attr({'method': 'POST', 'action': acsRedirect.url})
                  .appendTo('body');
                for (const key in acsRedirect.postParameters) {
                  $('')
                    .attr({'type': 'hidden', 'name': key, 'value': acsRedirect.postParameters[key]})
                    .appendTo($form);
                }
                $form.submit();

Метод: POST

url: /invoices/{id}/payment/refunds

Производит возврат средств

Parameters: ID или UUID счета, ID является устаревшим

Тело запроса:


                              {
                  "amountFractional": 50000
                }

Ответ код 201 OK


                              {
                  "amountFractional": 50000,
                  "id": 1241423,
                  "status": 4,
                  "message": "Возврат произведен."
                }

Ответ код 404 Счет не найден


                              {
                  "name": "Not Found",
                  "message": "Объект не найден.",
                  "code": 0,
                  "status": 404
                }

Ответ код 409 Платеж не завершен / Сумма возврата превышена / Не найден шлюз при расчете комиссии / Ошибка расчета комиссии


                              {
                  "name": "Conflict",
                  "message": "Ошибка.",
                  "code": 0,
                  "status": 409
                }

Метод: GET

url: /refunds/{id}

Возвращает объект Возврата Средств по ID

Parameters: ID или UUID счета, ID является устаревшим

Ответ код 200 OK


                              {
                  "amountFractional": 50000,
                  "id": 1241423,
                  "status": 4,
                  "message": "Возврат произведен."
                }

Метод: PUT

url: /invoices/{id}/payment/reversed

Производит отмену платежа

Parameters: ID или UUID счета, ID является устаревшим

Ответ код 200 OK

Ответ код 404 Счет не найден


                              {
                  "name": "Not Found",
                  "message": "Объект не найден.",
                  "code": 0,
                  "status": 404
                }

Ответ код 409 Платеж не завершен


                              {
                  "name": "Conflict",
                  "message": "Ошибка.",
                  "code": 0,
                  "status": 409
                }

API. Подключение

Host to Host API v.1

Описание методов

Спасибо, чтовыбрали VEPAY!

Спасибо, что
выбрали VEPAY!