Checkout Workflow RU | Global Pay

Введение

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

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

Оператор - АО «Global Solutions»

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

Платежный сервис «GLOBAL PAY CHECKOUT» - Автоматизированный платежный сервис, принадлежащий АО «Global Solutions», автоматизирующий прием платежей в пользу поставщиков

Пользователь- Лицо, за счет которого осуществляется платеж

Платежная система - Процессинговые центра Uzcard, Humo, Visa, Mastercard и тп.

{{base_checkout_url}} - Базовая часть URL системы Checkout для проведения HTTP запросов, например на создание токена платежа.

Для тестовой среды принимает значение https://checkout-api-dev.globalpay.uz/checkout

Для стейджинга - https://checkout-api-staging.globalpay.uz/checkout

Для продуктивной среды - https://checkout-api.globalpay.uz/checkout

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

АО «Global Solutions» получает запрос»;

После одобрения запроса от поставщика на рассмотрение к подключению к платежному шлюзу «GLOBAL PAY CHECKOUT» оформляется договор

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

После предоставление всех необходимых учетных данных поставщику, поставщик начинают разработку и тестирование в тестовой среде.

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

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

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

createServiceToken - Запрос на создание токена платежа со стороны системы Мерчанта
serviceTokenResponse - ответ на запрос на создание токена от системы Оператора
redirectUrl - переадресация браузера пользователя на страницу платежа
cardDetails - ввод пользователем данных о платежной карте
requestOtp - запрос на ОТП код со стороны Оператора в Процессинговом центре
SMS - отправка СМС с ОТП кодом на номер смс-информирования платежной карты
OTP code - ввод полученного ОТП кода пользователем
verifyOtp - отправка ОТП кода Оператором в сторону Процессингового центра
response - ответ на запрос на верификацию ОТП кода и проведение платежа
callback - запрос со стороны системы Поставщика в сторону системы Мерчанта с данными о результате транзакции по адресу, согласованному с Мерчантом (коллбека)
paymentResponse - уведомление пользователя о результате проведения транзакции и переадресация пользователя на страницу Мерчанта (если таковая указана при создании токена платежа)
getPayment - Запрос на информацию о транзакции. Мерчант отправляет токен платежа
paymentResponse - система Оператора возвращает данные о транзакции, если таковая имеется в системе.

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

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

POST Запрос на адрес {{base_checkout_url}}/v1/merchant/auth
с телом запроса

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

access_token- необходимо будет использовать для последующих запросов как Authorization: Bearer token в качестве header запроса. Срок его действия указан в поле expires_in в секундах.

refresh_token- можно использовать для обновления токена путем POST запроса на адрес {base_checkout_url}/v1/merchant/auth/refresh. Срок действия токена обновления указан в поле refresh_expires_in в секундах.

Получение Токена Платежа

Системой мерчанта осуществляется POST запрос на адрес следующей структуры:

name- название токена. Должно быть глобально уникальным. Требуется для того, чтобы не путать Пользователя.

description- Описание платежа

externalId- ID транзакции в системе Мерчанта

accountИдентификатор получателя в системе поставщика (Мерчанта)

tokenLifespan- Необязательное поле. Время жизни токена платежа в секундах. По умолчанию 900, минимальное 300, максимальное 86400. Если указывается значение меньше 300 (5 минут), то будет установлено 300. Если указывается значение более 86400 (24 часа) - то будет установлено 86400.

externalServiceId- Предоставленный Мерчанту serviceId, представляющий идентификатор касса для проведения платежы

itemsДанные по товару для ГНК. Может быть пустым в рамках единого платежа(товара), в противном случае поставщик(Мерчант) обязуется заполнить в соответствии с законодательством.

requestFields- Поля для предоставления дальнейшей информации по платежу. Обязательными являются поля с названиями amount и currency, означающие сумму платежа в минимальной величине валюты (тийинах для узбекских сомов) и валюту соответственно.

successRedirectUrl - ссылка, на которую будет осуществляться переадресация браузера Пользователя в случае успешно проведенного платежа

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

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

Новым здесь является поле id - это токен платежа, который будет использоваться далее для переадресации пользователя на страницу ввода данных платежной карты и соверешния платежа.

При получении ответа данной структуры необходимо сделать redirect пользователя на веб-страницу, адрес которой указан в поле userRedirectUrl.

Действия пользователя и ОТП код

Для осуществления платежа Пользователь должен будет ввести данные платежной карты и нажать на кнопку Оплатить. Если карта относится к Платежным системам UZCARD или Humo, то ими будет запрошен ОТП-код и откроется форма для ввода полученного кода из СМС. Если же карта принадлежит Платежным системам Visa/Mastercard то ОТП код на данном этапе запрошен не будет.

Если карта принадлежит Платежным системам Visa/Mastercard, то пользователю будет показана форма ввода ОТП кода для прохождения проверки 3DSecure. Форма принадлежит банку и ее содержимое контролируется банком.

После ввода всех данных пользователь получит уведомление о проведенном платеже и в браузере откроется страница успешного или неуспешного платежа. Если при создании токена платежа были указаны поля successRedirectUrl и failRedirectUrl то при успешном или неуспешном проведении платежа соответственно будет переадресация браузера на страницы указанные в этих полях.

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

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

При завершении платежа, система Оператора может выполнить callback запрос в систему Мерчанта с данными о проведенном платеже в формате

Где statusможет принимать значения APPROVED - для успешной транзакции, или FAILED - для неуспешной. При неуспешной транзакции будет заполняться поле error (например значением “INSUFFICIENT_FUNDS“ для неуспешных транзакций по причине недостатка средств).

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

Также на любом этапе работы возможен запрос на получение актуальной информации о платеже, посредством выполнения GET запроса на адрес {{base_checkout_url}}/v1/payment/servicetoken/{{user_service_token}}

Где user_service_token - должно принимать значение идентификатора токена платеж ( поле “id“ из ответа на запрос POST user-service-tokens выше).

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

Если с момента создания токена прошло больше времени в секундах, чем было указано в поле tokenLifespan (по умолчанию 900, или 15 минут) и система не получила от пользователя данные по карте и запрос на выполнение платежа, то платеж получит статус status = FAILED с полем error = “PAYMENT_EXPIRED“.

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

Возможны следующие HTTP коды ошибок:

400 - Неверные данные в запросе

401 - Запрос не авторизован

404 - Сущность не найдена в системе, или вызываемый URL не существует

500 - Непредвиденная ошибка сервера.

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

detail - Описание ошибки.

code - Код ошибки.

path - Адрес запроса, по которому возникла ошибка.

timestamp - Время возникновения ошибки.

trace - Идентификатор запроса для диагностики.