Gateway Workflow RU | Global Pay

Введение

Определение back-to-back интеграции

Настоящая инструкция разработана в АО «Global Solutions» и описывает порядок подключения и взаимодействия с платежным шлюзом «GLOBAL PAY GATE» в целях осуществления электронных денежных транзакций между поставщиком услуг и платежным шлюзом.

Все взаимодействие осуществляется по REST протоколу https:// посредством прямых вызовов HTTP (используя SSL).

Сервис обеспечивает возможность проведения оплат через карты Uzcard/Humo и Visa/Mastercard.

Термины и определения

Оператор - АО «Global Solutions»
Поставщик (или Мерчант) - Юридическое лицо, предоставляющее свои услуги посредством онлайн-платежей (магазины, кинотеатры, телекомы, коммунальные/налоговые службы и т.д.).
Пользователь - Лицо, за счет которого осуществляется платеж

{{base_url}} - Базовая часть URL системы GlobalPay Gateway для проведения HTTP запросов, например на создание токена платежа.
Для тестовой среды принимает значение https://gateway-api-dev.globalpay.uz
Для стейджинга - https://gateway-api-staging.globalpay.uz
Для продуктивной среды https://api.globalpay.uz

Шаги и условия до начала интеграции

АО «Global Solutions» получает запрос»;
После одобрения запроса от поставщика на рассмотрение к подключению к платежному шлюзу «GLOBAL PAY GATE, заключается договор и на его основании открываются EPOS терминалы в банке
Банк предоставляет EPOS терминал поставщику услуг, так и АО «Global Solutions»;

Поставщик предоставляет:

Официально зарегистрированное юридическое наименование организации;
Физический адрес организации с почтовым индексом;
IP-адреса, с которых будут производится вызовы методов платежного шлюза;
Web-адрес;
Код ИКПУ, ИНН.
После оформления договора, начинаются технические работы в тестовой среде.

Краткая схема взаимодействия.

Последовательность действий:

Нулевым шагом является аутентификация мерчанта в системе Оператора. Она может осуществляться на любом этапе взаимодействия.
cardCreateRequest - запрос на добавление карты со стороны системы Мерчанта.
requestOtp - запрос на ОТП код на номер СМС-информирования в процессинговый центр со стороны системы Оператора
response - ответ на запрос со стороны процессингового центра о правильности ввода данных
cardCreateResponse - ответ со стороны системы Операторао правильности ввода данных системе Мерчанта.

В случае верного ввода данных по карте Процессинговый центр отправляет ОТП код на номер смс-информирования карты.
OTP Code - пользователь вводит ОТП код из смс в систему Мерчанта.
cardConfirm - мерчант передает ОТП код в систему Оператора
verifyOtp - система GlobalPay передает ОТП код в Процессиноговый центр на проверку.
response - Процессинговый центр возвращает ответ на запрос
cardConfirmResponse - система Операторавозвращает ответ в систему мерчанта о правильности ввода ОТП кода.
paymentInit - создание платежа. Система Мерчанта передает в систему Оператораданные о платеже - сумму, внешний идентификатор и тп.
initResponse - Система Оператора возвращает ответ на запрос или ошибку в случае неверных вводных данных.
paymentPerform - система Мерчанта запрашивает выполнение платежа, прикрепив внутренний и внешний идентификатор и необходимые данные по платежной карте.
paymentResponse - система Операторавозвращает результат выполнения транзакции в системе Мерчанта.
getPayment - Запрос на информацию о транзакции. Мерчант отправляет идентификатор транзакции в системе Оператора
paymentResponse - система Оператора возвращает данные о транзакции, если таковая имеется в системе.

Подробное описание действий по авторизации и выполнению платежа.

Получение Токена авторизации.

Необходимо отправить POST на данный url: {base_url}/payments/v1/merchant/auth с телом запроса

где oauth_username и oauth_password - это логин и пароль, выданные мерчанту. В ответ придет структура следующего вида:

access_token - необходимо будет использовать для последующих запросов как Authorization: Bearer token в качестве header запроса. Срок его действия указан в поле expires_in в секундах.
refresh_token - можно использовать для обновления токена по адресу {base_url}/payments/v1/merchant/auth/refresh. Срок действия токена обновления указан в поле refresh_expires_in в секундах.

Добавление платежной карты.

Добавление платежной карты происходит с помощью вызова POST метода {base_url}/cards/v1/card со следующим телом запроса.

Где card_pan - это номер карты, например 8600310403504665, expiryDate - это срок действия карты в формате YYMM, например 2601. Это поля являются обязательными.
card_notification_number - это номер телефона, который должен совпадать с номером смс-информирования, привязанного к карте. При несовпадении будет возвращаться ошибка со стороны процессингового центра. Этот параметр обязательный в случае, когда планируется переиспользование карты для последующих платежей без отп-проверки. Без добавления данного поля, карта не может быть использована для повторных платежей, так как выдаваемый процессингом токен действует ограниченное время(для Хумо около 30 минут).
cardHolderName - Поле обязательное для международны платежных систем - например Visa/Mastercard. Это имя, как оно написано на самой карте. Без этого поля, проведение платежей по карте Visa/Mastercard будет невозможным.

Ответ на запрос будет в следующем формате:

Поле cardToken - токен карты, который будет использоваться для дальнейших запросов. Формат UUID.
smsNotificationNumber - номер смс-информирования, который был передан при запросе на добавление карты в замаскированном виде.
needsVerification - boolean поле, которое принимает значение true когда по карте процессинговым центром была отправлена смс с ОТП-кодом на номер смс-информирования. В этом случае необходимо сделать запрос на подтверждение карты.

Подтверждение карты.
Отправляется POST запрос на следующий адрес {{base_url}}/cards/v1/card/confirm/{{card_token}}, в котором card_token - это токен, полученный в ответ на запрос на добавление карты. Например:
{{base_url}}/cards/v1/card/confirm/d609c6fa-2ced-4306-864f-26842cf5fd25.
Тело запроса:

otp_code - значение ОТП-кода, полученного пользователем на номер смс-информирования.

В ответ придет структура следующего формата:

token - будет совпадать со значением cardToken из предыдущих запросов. Если смс-код был отправлен неверно, придет ошибка, код можно будет отправить повторно. Кол-во попыток ограничено со стороны процессингового центра.

Создание шаблона платежа.

При подключении мерчанта с методом проведения платежей DIRECT (не MUNIS или PAYNET), или любой другой системы, где не будет дополнительны обязательных полей для выполнения платежа помимо amount и currency, возможно пользование POST запроса версии 2 {{base_url}}/payments/v2/payment/init со следующей структурой запроса

externalId ID транзакции в системе поставщика (Мерчанта)
serviceId ID кассы предоставленной системой GlobalPay
amount Сумма для платежа в минимальной величие валюты (тийин для UZS)
currency Валюта платежа (На данный момент поддерживается только UZS)
account Идентификатор получателя в системе поставщика (Мерчанта)
merchantVMRedirectSuccessUrl URL для переадресации пользователя при успешном прохождении 3D-secure для карт Виза и Mastercard
merchantVMRedirectFailUrlURL для переадресации пользователя при неуспешном прохождении 3D-secure для карт Виза и Mastercard
description Описание платежа
items Данные по товару для ГНК. Может быть пустым в рамках единого платежа(товара), в противном случае поставщик(Мерчант) обязуется заполнить в соответствии с законодательством.
Способ init версии v2 должен использоваться по умолчанию!

При подключении мерчанта с системой MUNIS или PAYNET (в которых может быть больше 2 обязательных полей(amount и currency) для заполнения для проведения платежа) необходим вызов метода версии 1 {{base_url}}/payments/v1/payment/init

externalId ID транзакции в системе поставщика (Мерчанта)
serviceId ID кассы предоставленной системой GlobalPay
paymentFields Поля с информацией по платежу. Обязательные поля с названиями amount и currency.
Поля с названиями cvc2 clientIpAddress cardName и description обязательны для платежа совершаемого по картам Visa/Mastercard. Остальные поля должны заполняться в соответствии с обязательными полями для проведения платежа индивидуально для каждого поставщика(Мерчанта). Поле description имеет ограничение по длине согласно правилам процессингов Visa и Mastercard.

В ответ на оба метода init придет структура:

id - ID Транзакции в системе GlobalPay. Этот идентификатор будет использоваться далее для проведения платежа и проверки его статуса.
externalId - ID Транзакции в системе поставщика(Мерчанта)
status - статус транзакции. После операции init должен быть в состоянии “INIT“

Подтверждение платежа.

После создания платежа с помощью метода init версии v2 необходимо использовать метод подтверждения perform v2 вызвав POST запрос на {base_url}/payments/v2/payment/perform со структурой:

id - ID Транзакции в системе GlobalPay
externalId - ID Транзакции в системе поставщика(Мерчанта)
cardToken - токен карты, полученный при добавлении или подтверждении карты.
cardSecurityCode - необходимо для международных карт, имеющих код на оборотной стороне, например трехзначный CVV
clientIpAddress - также необходимо для международных карт, необходимо указать ип адрес вызывающего клиента.

После создания платежа с помощью метода Init версии v1 необходимо использовать метод подтверждения perform v1 вызвав POST запрос на {base_url}/payments/v1/payment/perform со структурой:

В ответ на оба метода придет структура вида:

Транзакция считается проведенной успешно, только в случае если в данном теле ответа поле status принимает значение APPROVED.
Где при успешной транзакции придет поле gnkFields описывающее ответ от ГНК. И остальные поля, названия которых говорят сами за себя.

ВАЖНО: при проведении оплаты по картам VISA/MASTERCARD в ответ придет поле securityCheckUrl в котором будет ссылка на перенаправления браузера пользователя на страницу аутентификации 3D-Secure.

После прохождения пользователем проверки 3D-Secure будет произведено перенаправление пользователя на ссылки, указанные в полях merchantVMRedirectSuccessUrl и merchantVMRedirectFailUrl при создании (init) платежа.

ВАЖНО помнить, что платежи по системам Visa/Mastercard осуществляются асинхронно в системе банка. Поэтому успешное проведение проверки 3D-Secure не означает успешное завершение всей транзакции. Для карт Visa и Mastercard необходимо подтверждение окончательного статуса платежа с помощью GET запроса, описанного в разделе "Получение статуса платежа." ниже.

Получение статуса платежа.

Может возникнуть необходимость сверить статус платежа между системами GlobalPay и системой поставщика(Мерчанта). Для этого может быть использован метод GET по адресу {{base_url}}/payments/v1/payment/{{tx_id}} где tx_id - это ID транзакции в системе GlobalPay.
Структура будет возвращена в ответ такая же, как и при проведении платежа.

Получаемые ошибки.

Возможны следующие HTTP коды ошибок:
400 - Неверные данные в запросе
401 - Запрос не авторизован
404 - Сущность не найдена в системе, или вызываемый URL не существует
500 - Непредвиденная ошибка сервера.

Тело ошибки приходит в следующем формате:

detail - Описание ошибки.
code - Код ошибки.
path - Адрес запроса, по которому возникла ошибка.
timestamp - Время возникновения ошибки.
trace - Идентификатор запроса для диагностики.