NAV
json

Введение introduction

Данный документ описывает программный интерфейс (API) web-сервиса ZPLAT PAYMENT GATEWAY, разработанного компанией ООО "ZPLAT".

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

Термины и сокращения terms-and-abbreviations

API (Application Programming Interface) - набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах.

Host-to-Host API - набор готовых методов, предоставляемых приложением (системой) для использования в межсерверных (внутренних) програмных продуктах.

JSON (JavaScript Object Notation) - текстовый формат обмена данными, основанный на JavaScript RFC 7159.

JSON-RPC (JavaScript Object Notation Remote Procedure Call) - протокол удалённого вызова процедур, использующий JSON для кодирования сообщений.

TLS (Transport Layer Security) - криптографические протокол, обеспечивающие защищённую передачу данных между узлами в сети Интернет.

HTTP (HyperText Transfer Protocol) - протокол прикладного уровня передачи данных.

HTTP заголовок - строки в HTTP-сообщении, содержащие разделённую двоеточием пару имя-значение. Формат заголовков соответствует общему формату заголовков текстовых сетевых сообщений ARPA (RFC 822).

Агент - Юридическое лицо, за исключением кредитной организации, или индивидуальный предприниматель, осуществляющие деятельность по приему платежей физических лиц.

Баланс Агента - депозитный счет Агента в расчетном банке ООО "ZPLAT".

Виджет – компактное приложение, которое выполняет одну функцию.

ОФД - оператор фискальных данных.

Платежный шлюз - аппаратно-программный комплекс, который позволяет автоматизировать процесс приема платежей в Интернете.

Поставщик - поставщик товаров и услуг по операциям с использованием банковских карт.

Сервис - платежный web-сервис ZPLAT PAYMENT GATEWAY.

Общие принципы general-principles

API построено на основе протокола удаленного вызова процедур JSON-RPC 2.0.

RPC Request

Пример RPC запроса

{
    "method": "method.name",
    "params": {
        "param1": "Any String",
        "param2": [
            "list",
            "of",
            "items"
        ]
    },
    "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4"
}

RPC Запрос - это JSON объект со следующими полями:

RPC Response

Пример RPC ответа

{
    "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4",
    "error": null,
    "result": {
        "param1": "Any String",
        "param2": [
            {
                "id": 123,
                "title": "item 123"
            },
            {
                "id": 124,
                "title": "item 124"
            }
        ]
    }
}

RPC Ответ - это JSON объект со следующими полями:

Пример RPC Request, завершенного ошибкой

Пример RPC запроса завершенного ошибкой

{
    "id": 202,
    "error": {
        "code": -32400,
        "message": "Системная (внутренняя ошибка)",
        "data": {
            "error": 504,
            "message": "Gateway Time Out"
        }
    },
    "result": null
}

Ответ содержит:

Эквайринг (виджет) acquiring-widget

Раздел описывает Эквайринг UzCard/HUMO через платежную форму ZPLAT (виджет оплаты).

Поставщик услуг размещает виджет оплаты на своем сайте. Сервис ZPLAT отправляет данные в формате JSON для проверки платежа у поставщика услуг.

Биллинг система поставщика услуг призвана сделать обработку платежей более быстрой и безопасной. Также она позволяет не допустить повторной оплаты заказа и своевременно информировать пользователя о проблемах оплаты.

URL для вызова методов API настраиваются в личном кабинете поставщика услуг. Перед использованием этого API для реальных платежей, имеется возможность протестировать вызовы API из личного кабинета поставщика услуг.

Формирование виджета widget-forming

На Вашем сайте вы можете разместить простой виджет оплаты услуг. Для этого необходимо правильно сформировать параметры запроса и подпись к нему внутри формы оплаты. Для формирования подписи используется алгоритм хеширования MD5.

Запрос формирования виджета собирается с данными и отправляется на URL https://zplat.uz/payment/payform{vendor_name}

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

Пример реализации кода виджета

{
  "VENDOR_ID" : "105328",
  "MERCHANT_TRANS_ID" : "22080452",
  "MERCHANT_TRANS_AMOUNT" : 10000,
  "MERCHANT_CURRENCY" : "UZS",
  "MERCHANT_TRANS_NOTE" : "Описание услуги",
  "MERCHANT_TRANS_RETURN_URL" : "https://merchant.zplat.uz/order/1/success",
  "MERCHANT_TRANS_ERROR_RETURN_URL" : "https://merchant.zplat.uz/order/1/error",
  "MERCHANT_LANG" : "UZ",
  "MERCHANT_TRANS_DATA" : "eyJrZXkxIjoidmFsdWUxIiwia2V5MiI6InZhbHVlMiJ9",
  "SIGN_TIME" : 1707912038213,
  "SIGN_STRONG": "790ff7acbba83de8592ad876ab5cfbd2"
}

Перечень параметров запроса для оплаты

Название параметра Формат Описание
VENDOR_ID integer Идентификатор поставщика услуг в системе ZPLAT
MERCHANT_TRANS_ID string(256) ID заказа на стороне поставщика услуг
MERCHANT_TRANS_AMOUNT float Сумма платежа
MERCHANT_CURRENCY string(10) Валюта платежа
MERCHANT_TRANS_NOTE string(256) Описание услуги, которое будет отображаться в списке транзакций в кабинете поставщика услуг
MERCHANT_TRANS_RETURN_URL string(256) Ссылка для возврата пользователя после оплаты
MERCHANT_TRANS_ERROR_RETURN_URL string(256) Ссылка для возврата пользователя в случае ошибки
MERCHANT_LANG string(256) Язык платежной формы
MERCHANT_TRANS_DATA string(256) Произвольные данные поставщика услуг, отправляются в endpoint url /pay для проверки заказа
SIGN_TIME integer Текущее время в миллисекундах
SIGN_STRING md5 Подпись запроса

Все параметры являются обязательными.

Формирование подписи запроса

Для формирования подписи запроса необходимо:

  1. Cформировать строку для подписи состоящую из: SECRET_KEY, VENDOR_ID, MERCHANT_TRANS_ID, MERCHANT_TRANS_AMOUNT, MERCHANT_CURRENCY, SIGN_TIME.
  2. Вычислить хеш MD5 этой строки.

Кодировка подписываемой строки – UTF-8. Подпись запроса устаревает через 15 минут с момента подписания и недействительна если установлено будущее время подписания.

Пример подписи запроса

md5(
   SECRET_KEY . 
   VENDOR_ID .
   MERCHANT_TRANS_ID . 
   MERCHANT_TRANS_AMOUNT .
   MERCHANT_CURRENCY .
   TIMESTAMP 
);

Перечень параметров подписи запроса

Название параметра Описание
SECRET_KEY Секретный ключ поставщика услуг
VENDOR_ID Идентификатор поставщика услуг в системе ZPLAT
MERCHANT_TRANS_ID ID заказа на стороне поставщика услуг
MERCHANT_TRANS_AMOUNT Сумма платежа
MERCHANT_CURRENCY Валюта платежа
TIMESTAMP Время подписания в миллисекундах

Информация о платеже payment-information

Название метода

Метод реализует получение информации о платеже перед его оплатой.

Пример запроса

{
  "MERCHANT_TRANS_ID": "7",
  "SIGN_TIME": 1503638389658,
  "SIGN_STRING": "5777e5ed6eda5b5cca3f56a90cf53e96"
}

Параметры запроса

Название поля Описание
MERCHANT_TRANS_ID Идентификатор платежа в биллинг системе партнера
SIGN_TIME Время подписания запроса в миллисекундах
SIGN_STRING Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . MERCHANT_TRANS_ID . SIGN_TIME ), где SECRET_KEY - секретный ключ поставщика услуг.

Пример ответа

{
  "ERROR": "0",
  "ERROR_NOTE": "Success",
  "PARAMETERS": {
    "full_name": "Test Test",
    "balance": "1000",
    "email": "test@test.uz"
  }
}

Параметры ответа

Название поля Описание
PARAMETERS Дополнительные параметры оплаты от биллинг системы. Может быть NULL.

Подтверждение платежа payment-confirmation

Название метода

Метод реализует проверку актуальности платежа в биллинг системе поставщика услуг, а именно:

На данный запрос поставщик услуг должен вернуть состояние заказа/логина/номера лиц.счета:

Пример запроса

{
  "ENVIRONMENT": "live",
  "VENDOR_ID": "100036",
  "PAYMENT_ID": 16,
  "PAYMENT_NAME": "ZPLAT",
  "AGR_TRANS_ID": "66cdaaaeeaf4c846568385b6",
  "MERCHANT_TRANS_ID": "BA-42545-DA",
  "MERCHANT_TRANS_AMOUNT": 244783400,
  "SIGN_TIME": 1724754765422,
  "SIGN_STRING": "c1b80d524108d22222fa4d639c7e169a"
}

Параметры запроса

Название поля Описание
ENVIRONMENT Окружение для выполнения метода: live-действительные платежи, sandbox-тестовые платежи
VENDOR_ID Идентификатор Поставщика в системе ZPLAT
PAYMENT_ID Идентификатор платежной системы в системе ZPLAT
PAYMENT_NAME Наименование платежной системы
AGR_TRANS_ID Идентификатор платежа в системе ZPLAT
MERCHANT_TRANS_ID ID заказа на стороне Поставщика
MERCHANT_TRANS_AMOUNT Сумма платежа в тийинах
SIGN_TIME Время подписания запроса в миллисекундах
SIGN_STRING Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_ID . PAYMENT_ID . PAYMENT_NAME . MERCHANT_TRANS_ID . MERCHANT_TRANS_AMOUNT . ENVIRONMENT . SIGN_TIME ) , где SECRET_KEY - секретный ключ Поставщика.

Пример ответа

{
  "ERROR": "-2",
  "ERROR_NOTE": "Incorrect parameter amount"
}

Параметры ответа

Название поля Описание
ERROR Код ошибки
ERROR_NOTE Описание ошибки

Уведомление о платеже payment-notification

Название метода

Данным запросом система ZPLAT уведомляет о смене статуса платежа. Только после получения этого запроса биллинг система поставщика должна завершить/отменить платеж.

Пример запроса

{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": "1503642925906",
  "STATUS": 2,
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Параметры запроса

Название поля Описание
AGR_TRANS_ID Идентификатор платежа в системе ZPLAT
VENDOR_TRANS_ID Идентификатор платежа в биллинг системе поставщика услуг
STATUS Статус платежа (integer): 2 - Платеж успешно проведен, 3 - Платеж отменен, -1 - Ошибка
MESSAGE Описание ошибки (string) (Поле добавляется только при статусе -1)
SIGN_TIME Время подписания запроса в миллисекундах
SIGN_STRING Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . STATUS . SIGN_TIME ) , где SECRET_KEY - секретный ключ поставщика услуг.

Пример ответа

{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Отмена платежа payment-cancellation

Название метода

Отмену оплаты возможно сделать максимум в течение 1 месяца после проведения транзакции. Если времени пройдет больше, то отмена будет невозможна.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.reverse",
    "id": 2,
    "params": {
        "receipt_id": "<receipt_id>",
        "reason": "<reason>"
    }
}

Параметры запроса

Название поля Описание
receipt_id ID чека
reason Код причины отмены транзакции

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.reverse",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.reverse
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card объект карты
         hash хешированный номер карты. Например: "1ae168da94f7a148e68b7c481e7e50becd428790"
         masked_pan Номер карты маскированной строкой
         expire Срок действия карты в формате “YYMM”
         status Статус карты (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
         full_name Полное имя владельца карты
         card_type Тип карты, например “Provate” или “Corporate”
         processing Процессинг, например: “uzcard” или “humo”
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product объект продукта
        key Ключ продукта (для услуг, позволяющих клиенту купить ключи продукта, например, PUBG keys)
    details Детали платежа
    commission Процент комиссии

Проверка на факт отмены checking-for-cancellation

Название метода

Метод CANCEL используется для уведомления Поставщика об отмене платежа в системе ZPLAT. После получения статуса Success в ответ на CANCEL система ZPLAT отправит Поставщику ответ на запрос receipt.reverse с уведомлением о завершении платежа со статусом Отменен.

Пример запроса

{
  "AGR_TRANS_ID": 1503642925905,
  "VENDOR_TRANS_ID": "1503642925906",
  "SIGN_TIME": 1503642926295,
  "SIGN_STRING": "5a30fbd0fab44be29310e4b493c9a287"
}

Параметры запроса

Название поля Описание
AGR_TRANS_ID Идентификатор платежа в системе ZPLAT
VENDOR_TRANS_ID Идентификатор платежа в биллинг системе поставщика услуг
SIGN_TIME Время подписания запроса в миллисекундах
SIGN_STRING Проверочная строка, подтверждающая подлинность отправляемого запроса md5( SECRET_KEY . AGR_TRANS_ID . VENDOR_TRANS _ID . SIGN_TIME ), где SECRET_KEY - секретный ключ поставщика услуг.

Пример ответа

{
  "ERROR": "0",
  "ERROR_NOTE": "Success"
}

Коды ошибок виджетов widget-error-codes

Код ошибки Значение Описание
0 Success Успешный запрос
-1 SIGN CHECK FAILED! Ошибка проверки подписи
-2 Incorrect parameter amount Неверная сумма оплаты
-3 Action not found Запрашиваемое действие не найдено
-4 Already paid Транзакция ранее была подтверждена (при попытке подтвердить или отменить ранее подтвержденную транзакцию)
-5 User does not exist Не найден пользователь/заказ (проверка параметра MERCHANT_TRANS_ID)
-6 Transaction does not exist Не найдена транзакция
-7 Failed to update user Ошибка при изменении данных пользователя (изменение баланса счета и т.п.)
-8 Error in request from ZPLAT Ошибка в запросе от ZPLAT (переданы не все параметры и т.п.)
-9 Transaction cancelled Транзакция ранее была отменена (при попытке подтвердить или отменить ранее отмененную транзакцию)
-10 The vendor is not found Поставщик не найден в системе

Эквайринг acquiring(host-to-host)

Раздел описывает Эквайринг UzCard/HUMO через платежную форму поставщика услуг (Host-to-Host API).

Возможны два сценария: с холдированием средств и без холдирования.

URL-адрес для работы запросов:

https://gateway.zplat.uz/api/jsonrpc

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

Порядок взаимодействия без холдирования средств:

Авторизация authorization

Базовая структура заголовков (Headers) включает в себя:

Пример:

Basic base64(login:key)

Логин и ключ для агента могут быть получены у администратора платежного сервиса.

Система использует статус коды HTTP для передачи информации об успешности или неуспешности запроса.

200 OK - означает что запрос успешно обработан системой и при выполнении запроса не произошло никаких сбоев.

Система регистрирует каждый входящий запрос уникальным ID запроса и сохраняет его в базе данных платежного сервиса. При успешном ответе системы данный ID запроса возвращается в соответствующем в поле ответа (x_request_id_create, x_request_id_pay, x_request_id_status). Рекомендуется сохранять данный ID в системе контрагента для более быстрого поиска запроса и решения возникающих проблем.

Создание платежа payment-creation

Название метода

С помощью этого метода создается онлайн платёж.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.create",
    "id": 123,
    "params": {
        "ext_id": "avia",
        "service": "avia-ticket",
        "params": {
            "amount": 1000000
        },
        "receiver_id": "receiver",
        "hold": { 
            "holding_time": 10,
            "after_expired": "accept"
        }
    }
}

Параметры запроса

Название поля Описание
ext_id ID транзакции, сгенерированный на стороне агента
service Название сервиса
receiver_id ID получателя
params Объект с параметрами для созданной транзакции
     amount Cумма оплаты в тийинах
hold Параметры холдирования
     holding_time Время холдирования в минутах
     after_expired Действие после истечения срока (списать "accept" или отменить "cancel")

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "avia",
        "method": "receipt.create",
        "receipt": {
            "id": "65cf2fd71390a295cc65cda6",
            "amount": 10000,
            "card": "56342b88467086165c52abb562377b28903b373d",
            "state": "4",
            "created_at": 1708077015764,
            "paid_at": 1708077042879,
            "canceled_at": 0,
            "operations": [
                {
                    "operation_type": "merchant",
                    "id": "65cf2fd7a50d380965ecd6c4",
                    "processing": null
                },
                {
                    "operation_type": "payment",
                    "id": "hold_humo_170807703187457",
                    "processing": "humo"
                }
            ],
            "product": {},
            "details": {},
            "commission": 100
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.create
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card sha1 номера карты
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product Объект продукта
    details Детали платежа
    commission Процент комиссии

Платеж с подтверждением payment-with-confirmation

Название метода

Этот метод позволяет оплатить созданный платеж картой с подтверждением OTP.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.web.pay",
    "id": 2,
    "params": {
        "receipt_id": "<id>",
        "card": {
            "pan": "<card>",
            "expire": "<expire>"
        }
    }
}

Параметры запроса

Название поля Описание
receipt_id ID чека
card Объект карты, с помощью которой осуществляется оплата
     pan Номер карты
     expire Срок действия карты в формате “YYMM”

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.web.pay",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.web.pay
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card объект карты
         hash хешированный номер карты. Например: "1ae168da94f7a148e68b7c481e7e50becd428790"
         masked_pan Номер карты маскированной строкой
         expire Срок действия карты в формате “YYMM”
         status Статус карты (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
         full_name Полное имя владельца карты
         card_type Тип карты, например “Provate” или “Corporate”
         processing Процессинг, например: “uzcard” или “humo”
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product объект продукта
        key Ключ продукта (для услуг, позволяющих клиенту купить ключи продукта, например, PUBG keys)
    details Детали платежа
    commission Процент комиссии

Передача OTP-кода otp-code-transmit

Название метода

Этот метод позволяет передать OTP-код для завершения подтверждения.

Пример запроса

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "receipt.web.verify",
    "params": {
        "receipt_id": "<receipt_id>",
        "otp": "<otp>"
    }
}

Параметры запроса

Название поля Описание
receipt_id ID чека
otp OTP-код

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "test-agent",
        "method": "receipt.web.verify",
        "receipt": {
            "id": "64a2aae138480f57b14d66ac",
            "amount": 10000,
            "state":  "0",
            "card": "<sha1_of_card_number>",
            "created_at": 1688382177500,
            "paid_at": 0,
            "canceled_at": 0
          }
    "id": 123
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.web.verify
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    state Статус платежа
    card sha1 номера карты
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах

Холдирование средств holding-funds

Название метода

С помощью этого метода можно подтвердить или отменить холдирование средств.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.hold", 
    "id": 2,
    "params": {
        "receipt_id": "65c9c8b2cd146a40f0c138bc",
        "action": "cancel"
    }
}

Параметры запроса

Название поля Описание
params Объект с параметрами
     receipt_id ID чека
     action Действие (списать "accept" или отменить "cancel")

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "avia",
        "method": "hold",
        "receipt": {
            "id": "65cf2fd71390a295cc65cda6",
            "amount": 10000,
            "card": "56342b88467086165c52abb562377b28903b373d",
            "state": "4",
            "created_at": 1708077015764,
            "paid_at": 1708077042879,
            "canceled_at": 0,
            "operations": [
                {
                    "operation_type": "merchant",
                    "id": "65cf2fd7a50d380965ecd6c4",
                    "processing": null
                },
                {
                    "operation_type": "payment",
                    "id": "hold_humo_170807703187457",
                    "processing": "humo"
                }
            ],
            "product": {},
            "details": {},
            "commission": 100
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение hold
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card sha1 номера карты
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product Объект продукта
    details Детали платежа
    commission Процент комиссии

Проверка статуса платежа checking-of-payment-status

Название метода

Этот метод позволяет получить информацию о платеже.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.status",
    "id": 2,
    "params": {
        "receipt_id": "<receiver_id>"
    }
}

Параметры запроса

Название поля Описание
receipt_id ID чека

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.status",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.status
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card объект карты
         hash хешированный номер карты. Например: "1ae168da94f7a148e68b7c481e7e50becd428790"
         masked_pan Номер карты маскированной строкой
         expire Срок действия карты в формате “YYMM”
         status Статус карты (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
         full_name Полное имя владельца карты
         card_type Тип карты, например “Provate” или “Corporate”
         processing Процессинг, например: “uzcard” или “humo”
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product объект продукта
        key Ключ продукта (для услуг, позволяющих клиенту купить ключи продукта, например, PUBG keys)
    details Детали платежа
    commission Процент комиссии

Отмена платежа payment-cancellation-2

Название метода

Отмену оплаты возможно сделать максимум в течение 1 месяца после проведения транзакции. Если времени пройдет больше, то отмена будет невозможна.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "receipt.reverse",
    "id": 2,
    "params": {
        "receipt_id": "<receipt_id>",
        "reason": "<reason>"
    }
}

Параметры запроса

Название поля Описание
receipt_id ID чека
reason Код причины отмены транзакции

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "agent": "<agent>",
        "method": "receipt.reverse",
        "receipt": {
            "id": "<id>",
            "amount": <amount>,
            "card": {
                "hash": "<hash>",
                "masked_pan": "<masked_pan>",
                "expire": "<expire>",
                "status": 1,
                "full_name": "<full_name>",
                "card_type": <card_type>,
                "processing": "<processing>"
            }, 
            "state": "<state>",
            "created_at": <created_at>,
            "paid_at": <paid_at>,
            "canceled_at": <canceled_at>,
            "operations": [
                {
                    "operation_type": "<operation_type>",
                    "id": "<id>",
                    "processing": "<processing>"
                },
                ...
            ],
            "product": {
              "key": "<key>"
            },
            "details": {},
            "commission": <commission>
        }
    },
    "id": 2
}

Параметры ответа

Название поля Описание
agent Название контрагента
method Тип запроса. При создании принимает значение receipt.reverse
receipt объект чека платежа
    id ID чека платежа
    amount Cумма оплаты в тийинах
    card объект карты
         hash хешированный номер карты. Например: "1ae168da94f7a148e68b7c481e7e50becd428790"
         masked_pan Номер карты маскированной строкой
         expire Срок действия карты в формате “YYMM”
         status Статус карты (1 - “Active”, 2 - “ActiveNoPhone”, 3 - “Blocked”)
         full_name Полное имя владельца карты
         card_type Тип карты, например “Provate” или “Corporate”
         processing Процессинг, например: “uzcard” или “humo”
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    cancelled_at Временная метка отмены платежа, в миллисекундах
    operations объект деталей операции
        operation_type тип операции
        id id операции
        processing описание обработки
    product объект продукта
        key Ключ продукта (для услуг, позволяющих клиенту купить ключи продукта, например, PUBG keys)
    details Детали платежа
    commission Процент комиссии

Витрина оплаты поставщиков supplier-payment-showcase

Описываемые в этом разделе методы позволяют Агентам реализовать платежи за различные услуги Поставщиков со своего баланса:

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

URL-адрес для работы запросов:

https://gw.zplat.uz/api/jsonrpc

Для проведения платежей необходимо пополнить Баланс Агента банковским переводом денежных средств на депозитный счет агента. Реквизиты для перечислений предоставит курирующий менеджер.

Возможность и сроки проведения отмены платежа зависят от Поставщика. Отмену оплаты возможно сделать максимум в течение 1 месяца после проведения транзакции. Если времени пройдет больше, то отмена будет невозможна.

Авторизация authorization-2

Базовая структура заголовков (Headers) включает в себя:

Пример:

Basic base64(login:key)

Логин и ключ для агента могут быть получены у администратора платежного сервиса.

Система использует статус коды HTTP для передачи информации об успешности или неуспешности запроса.

200 OK - означает что запрос успешно обработан системой и при выполнении запроса не произошло никаких сбоев.

Система регистрирует каждый входящий запрос уникальным ID запроса и сохраняет его в базе данных платежного сервиса. При успешном ответе системы данный ID запроса возвращается в соответствующем в поле ответа (x_request_id_create, x_request_id_pay, x_request_id_status). Рекомендуется сохранять данный ID в системе контрагента для более быстрого поиска запроса и решения возникающих проблем.

Получение списка услуг getting-list-of-services

Данный метод возвращает список доступных услуг.

Название метода

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "agents.getAvailableServices",
    "id": 2
}

Параметры запроса

Параметры запроса отсутствуют, а в ответе приходит перечень всех доступных сервисов.

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "services": [
            {
                "name": "netco",
                "title": {
                    "ru": "Netco",
                    "en": "Netco",
                    "uz": "Netco"
                },
                "category": {
                    "name": "internet-providers",
                    "title": {
                        "en": "Internet providers",
                        "ru": "Интернет провайдеры",
                        "uz": "Internet provayderlar"
                    }
                },
                "type": "service",
                "active": false,
                "fraud": false,
                "minAmount": 50000,
                "maxAmount": 200000000,
                "currency": "UZS",
                "fields": [
                    {
                        "name": "account",
                        "regexp": "",
                        "label": {
                            "uz": "Login",
                            "ru": "Логин",
                            "en": "Login"
                        },
                        "required": true
                    },
                    {
                        "name": "amount",
                        "regexp": "/[0-9]/",
                        "label": {
                            "uz": "To`lov summasi",
                            "ru": "Сумма",
                            "en": "Amount"
                        },
                        "required": true
                    }
                ]
            },
            {
                "name": "odnoklassnikiru",
                "title": {
                    "ru": "Odnoklassniki.ru",
                    "en": "Odnoklassniki.ru",
                    "uz": "Odnoklassniki.ru"
                },
                "category": {
                    "name": "social-networks",
                    "title": {
                        "en": "Social networks",
                        "ru": "Социальные сети",
                        "uz": "Ijtimoiy tarmoqlar"
                    }
                },
                "type": "product",
                "active": false,
                "fraud": false,
                "minAmount": 50000,
                "maxAmount": 200000000,
                "currency": "UZS",
                "fields": [
                    {
                        "name": "account",
                        "regexp": "",
                        "label": {
                            "uz": "Login",
                            "ru": "Логин",
                            "en": "Login"
                        },
                        "required": true
                    },
                    {
                        "name": "amount",
                        "regexp": "/[0-9]/",
                        "label": {
                            "uz": "To`lov summasi",
                            "ru": "Сумма",
                            "en": "Amount"
                        },
                        "required": true
                    }
                ]
            }
        ]
    },
    "id": 2
}

Параметры ответа

Название поля Описание
name Название сервиса
title Объект названий сервиса на трех языках (ru,en,uz)
category Объект категории сервиса
    name Название категории сервиса
    title Объект названий категории сервиса на трех языках (ru,en,uz)
type Тип поставщика (service - услуга, product - продукт)
active Активность услуги
fraud Активность антифрода по данной услуге
minAmount Минимальная сумма оплаты
maxAmount Максимальная сумма оплаты
currency Валюта поставщика
fields Объект полей для запроса
    name Название поля
    regexp Регулярное выражение для валидации поля
    label Объект названий поля на трех языках (ru,en,uz)
    required Обязательность поля

Получение баланса getting-balance

Название метода

Данный метод используется для проверки баланса на депозите агента.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "agents.getBalance",
    "id": 2,
    "params": {    
    }
}

Параметры запроса

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

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "balance": 0,
        "currency": "UZS",
        "max_overdraft": 0
    },
    "id": 2
}

Параметры ответа

Название поля Описание
balance Баланс денежных средств на депозите Агента
currency Валюта агента в ISO
max_overdraft Показывает, сколько денег осталось до достижения лимита

Получить сумму оплаты getting-payment-amount

Название метода

Данный метод используется для тех поставщиков, к которым имеет отношение фиксированная сумма оплаты.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "transactions.products.price",
    "id": 2,
    "params": {
        "service": "twitch-usd-50-us",
    }
}

Параметры запроса

Название поля Описание
service Название услуги для проверки стоимости

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "price": 5400,
        "currency": "USD",
    },
    "id": 2
}

Параметры ответа

Название поля Описание
price Стоимость сервиса (продукта или услуги)
currency Валюта агента в ISO

Создание транзакции transaction-creation

Название метода

При создании транзакции шлюз выполняет проверки, сводя к минимуму риск возникновения ошибки при подтверждении транзакции.

При вызове этого метода система создает новую транзакцию и сохраняет ее в базе данных со статусом "0" (Новая транзакция). После получения успешного ответа вы можете отправить запрос на подтверждение перевод.

Пример запроса

{
    "id": 123,
    "jsonrpc": "2.0",
    "method": "transactions.create",
    "params": {
        "service": "pubg-60-uc",
        "account": "<account>",
        "amount": 123456,
        "ext_id": "<agent-request-id>"
    }
}

Параметры запроса

Название поля Описание
service Код услуги
account Счет, на который запрашивается пополнение
amount Сумма пополнения счета в тийинах
ext_id ID транзакции агента

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "method": "create",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 0,
            "canceled_at": 0,
            "state": 0,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4"
        }
    },
    "id": 123
}

Параметры ответа

Название поля Описание
method Тип запроса
receipt объект чека платежа
    id Уникальный идентификатор транзакции, сгенерированный шлюзом
    numeric_id Альтернативный формат идентификатора, создаваемый шлюзом
    ext_id Уникальный идентификатор транзакции, созданный на стороне агента
    agent Логин агента, создавшего транзакцию
    service Уникальное имя сервиса
    service_account Счет/логин/номер телефона с указанием получателя средств
    agent_amount Сумма, отправленная в запросе агента
    agent_currency Валюта агента, указанная в договоре
    converted Указывает, была ли конвертирована сумма запроса на стороне самого платежного шлюза перед отправкой поставщику услуг
    exchange_rate Если валюта агента и валюта поставщика услуг различаются, в поле будет указан обменный курс, по которому произошла конвертация
    commission_rate Процент комиссии, вычитаемый из суммы запроса
    calculated_commssion Сумма в валюте агента, которая была вычтена из суммы запроса
    provider_amount Окончательная сумма, которая будет отправлена поставщику услуг после вычета всех комиссий в валюте поставщика
    provider_currency Валюта, принимаемая поставщиком услуг
    service_currency Валюта, с которой работает провайдер, может отличаться от валюты конечной услуги и в таких случаях конвертация происходит уже на стороне поставщика услуги. В этом поле указывается валюта конечной услуги
    service_exchange_rate Коэффициент конверсии на стороне провайдера
    service_to_accrual Конечная сумма в валюте услуги, которая будет зачислена на счет
    created_at Временная метка UNIX, дата создания транзакции в системе, в миллисекундах
    paid_at Временная метка UNIX, дата успешной обработки запроса поставщика, в миллисекундах
    canceled_at Временная метка UNIX, дата отмены транзакции, в миллисекундах
    state Код статуса транзакции
    mode Тестовая проверка (TEST) или боевая проверка (PROD)
    voucher Информация о купленном ваучере, если сервис их предоставляет
    commission_in_uzs Размер комиссии, получаемой шлюзом (требуется для агентов на территории Республики Узбекистан)
    x_request_id_create UUID запроса на создание транзакции от агента, зарегистрированного в шлюзе

Подтверждение транзакции transaction-confirmation

Название метода

В зависимости от времени ответа провайдера ответ на запрос платежа может варьироваться от 1-2 секунд до 60 секунд. Если ответ не был получен в течение 60 секунд, то необходимо проверить статус платежа с рекомендуемым интервалом в 30 секунд до получения окончательного статуса.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "transactions.pay",
    "id": 2,
    "params": {
        "receipt_id": "62b4d1046b3b706f362f7071",
        "card_hash": "FF998ABC1CE6D8F01A675FA197368E44C8916E9C"
    }
}

Параметры запроса

Название поля Описание
receipt_id Идентификатор метода, полученный по запросу transactions.create
card_hash SHA1-хэш номера карты или учетной записи Агента

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "method": "pay",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 1656017153678,
            "canceled_at": 0,
            "state": 4,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4",
            "x_request_id_pay": "6e6653fa-5694-435a-ac0e-358a08ac8f10",
            "fiscal_url": "https://ofd.soliq.uz/epi",
        }
    },
    "id": 123
}

Параметры ответа

Название поля Описание
method Тип запроса
receipt объект созданного платежа
    id Уникальный идентификатор транзакции, сгенерированный шлюзом
    numeric_id Альтернативный формат идентификатора, создаваемый шлюзом
    ext_id Уникальный идентификатор транзакции, созданный на стороне агента
    agent Логин агента, создавшего транзакцию
    service Уникальное имя сервиса
    service_account Счет/логин/номер телефона с указанием получателя средств
    agent_amount Сумма, отправленная в запросе агента
    agent_currency Валюта агента, указанная в договоре
    converted Указывает, была ли конвертирована сумма запроса на стороне самого платежного шлюза перед отправкой поставщику услуг
    exchange_rate Если валюта агента и валюта поставщика услуг различаются, в поле будет указан обменный курс, по которому произошла конвертация
    commission_rate Процент комиссии, вычитаемый из суммы запроса
    calculated_commssion Сумма в валюте агента, которая была вычтена из суммы запроса
    provider_amount Окончательная сумма, которая будет отправлена поставщику услуг после вычета всех комиссий в валюте поставщика
    provider_currency Валюта, принимаемая поставщиком услуг
    service_currency Валюта, с которой работает провайдер, может отличаться от валюты конечной услуги и в таких случаях конвертация происходит уже на стороне поставщика услуги. В этом поле указывается валюта конечной услуги
    service_exchange_rate Коэффициент конверсии на стороне провайдера
    service_to_accrual Конечная сумма в валюте услуги, которая будет зачислена на счет
    created_at Временная метка UNIX, дата создания транзакции в системе, в миллисекундах
    paid_at Временная метка UNIX, дата успешной обработки запроса поставщика, в миллисекундах
    canceled_at Временная метка UNIX, дата отмены транзакции, в миллисекундах
    reason Код причины отмены транзакции
    mode Тестовая проверка (TEST) или боевая проверка (PROD)
    state Код статуса транзакции
    voucher Информация о купленном ваучере, если сервис их предоставляет
    commission_in_uzs Размер комиссии, получаемой шлюзом (требуется для агентов на территории Республики Узбекистан)
    x_request_id_create UUID запроса на создание транзакции от агента, зарегистрированного в шлюзе
    x_request_id_pay UUID запроса подтверждения транзакции от агента, зарегистрированного в шлюзе
    fiscal_url URL для получения фискального чека

Получение статуса транзакции getting-transaction-status

Для получения статуса ранее созданной транзакции используется запрос, в котором в качестве параметра передается receipt_id — уникальный идентификатор транзакции в системе платежного шлюза.

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

Название метода

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "transactions.status",
    "id": 2,
    "params": {
        "receipt_id": "6227ff43c89320fb4e4c5e32"
    }
}

Параметры запроса

Название поля Описание
receipt_id Идентификатор метода, полученный по запросу transactions.pay

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "method": "status",
        "receipt": {
            "id": "62b4d1046b3b706f362f7071",
            "numeric_id": "1656017156613258196",
            "ext_id": "<agent-request-id>",
            "agent": "<agent-login>",
            "service": "<service>",
            "service_account": "<account>",
            "agent_amount": 123456,
            "agent_currency": "UZS",
            "converted": false,
            "exchange_rate": 1,
            "commission_rate": 10,
            "calculated_commission": 1235,
            "provider_amount": 122221,
            "provider_currency": "UZS",
            "service_currency": "UZS",
            "service_exchange_rate": 1,
            "service_to_accrual": 122221,
            "created_at": 1656017156613,
            "paid_at": 1656017153678,
            "canceled_at": 0,
            "state": 4,
            "mode": "PROD",
            "voucher": null,
            "commission_in_uzs": 1235,
            "x_request_id_create": "3d636101-61bc-4677-9ec9-795e140266a4",
            "x_request_id_pay": "6e6653fa-5694-435a-ac0e-358a08ac8f10",
            "fiscal_url": "https://ofd.soliq.uz/epi",
        }
    },
    "id": 123
}

Параметры ответа

Название поля Описание
method Тип запроса
receipt объект созданного платежа
    id Уникальный идентификатор транзакции, сгенерированный шлюзом
    numeric_id Альтернативный формат идентификатора, создаваемый шлюзом
    ext_id Уникальный идентификатор транзакции, созданный на стороне агента
    agent Логин агента, создавшего транзакцию
    service Уникальное имя сервиса
    service_account Счет/логин/номер телефона с указанием получателя средств
    agent_amount Сумма, отправленная в запросе агента
    agent_currency Валюта агента, указанная в договоре
    converted Указывает, была ли конвертирована сумма запроса на стороне самого платежного шлюза перед отправкой поставщику услуг
    exchange_rate Если валюта агента и валюта поставщика услуг различаются, в поле будет указан обменный курс, по которому произошла конвертация
    commission_rate Процент комиссии, вычитаемый из суммы запроса
    calculated_commssion Сумма в валюте агента, которая была вычтена из суммы запроса
    provider_amount Окончательная сумма, которая будет отправлена поставщику услуг после вычета всех комиссий в валюте поставщика
    provider_currency Валюта, принимаемая поставщиком услуг
    service_currency Валюта, с которой работает провайдер, может отличаться от валюты конечной услуги и в таких случаях конвертация происходит уже на стороне поставщика услуги. В этом поле указывается валюта конечной услуги
    service_exchange_rate Коэффициент конверсии на стороне провайдера
    service_to_accrual Конечная сумма в валюте услуги, которая будет зачислена на счет
    created_at Временная метка UNIX, дата создания транзакции в системе, в миллисекундах
    paid_at Временная метка UNIX, дата успешной обработки запроса поставщика, в миллисекундах
    canceled_at Временная метка UNIX, дата отмены транзакции, в миллисекундах
    reason Код причины отмены транзакции
    mode Тестовая проверка (TEST) или боевая проверка (PROD)
    state Код статуса транзакции
    voucher Информация о купленном ваучере, если сервис их предоставляет
    commission_in_uzs Размер комиссии, получаемой шлюзом (требуется для агентов на территории Республики Узбекистан)
    x_request_id_create UUID запроса на создание транзакции от агента, зарегистрированного в шлюзе
    x_request_id_pay UUID запроса подтверждения транзакции от агента, зарегистрированного в шлюзе
    fiscal_url URL для получения фискального чека

Проверка транзакций transactions-checking

Метод используется для запроса транзакций на определенную дату. В ответе приходит список транзакций, разделенный на группы (страницы) для отображения.

Название метода

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "transactions.check",
    "id": 2,
    "params": {
        "date": 1680524563287,
        "page": 0
    }
}

Параметры запроса

Название поля Описание
date Временная метка UNIX, дата проверки
page Начинается с "0"

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "pages": 15,
        "page": 0,
        "receipts": [
            {
                "_id": "642ac54d9017b321f8550bb7",
                "agent_transaction": "642ac5473cc6b94fc24ee816",
                "agent_amount": 614500000,
                "agent_currency": "UZS",
                "created_at": 1680524621948,
                "paid_at": 1680524627228,
                "canceled_at": 0,
                "mode": "PROD",
                "state": "4",
                "params": {
                    "account": "2586",
                    "amount": 6145000
                }
            },
            ….,
        ]
    },
    "id": 2
}

Параметры ответа

Название поля Описание
pages Общее количество транзакций в запросе
page Текущий номер транзакции по порядку
    _id Уникальный идентификатор транзакции, сгенерированный платежным шлюзом
    agent_transaction Уникальный идентификатор транзакции, сгенерированный на стороне агента
    agent_amount Сумма, отправленная в запросе агента
    agent_currency Валюта агента, указанная в договоре
    created_at Временная метка UNIX, дата создания транзакции в системе, в миллисекундах
    paid_at Временная метка UNIX, дата успешной обработки запроса поставщика, в миллисекундах
    canceled_at Временная метка UNIX, дата отмены транзакции, в миллисекундах
    mode В зависимости от поля is_test в самом сервисе, принимает значение TEST или PROD
    state Код статуса транзакции
    params Поля, отправленные агентом

Создание тестовой транзакции test-transaction-creating

Название метода

При создании тестовой транзакции не делается запрос к провайдеру, либо используется тестовая среда провайдера. Вся логика метода соответствует методу transactions.create, но платежи, совершенные с помощью этого метода, не включаются в сверку.

Подтверждение тестовой транзакции test-transaction-confirmation

Название метода

Вся логика этого метода соответствует методу transactions.pay.

Выплаты на UzCard/HUMO payments-to-uzcard-humo

Описываемые в этом модуле методы позволяют реализовать выплаты денежных средств на банковские карты, эмитированные в Республике Узбекистан.

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

URL-адрес для работы запросов:

https://gateway.zplat.uz/api/jsonrpc

Авторизация authorization-3

Базовая структура заголовков (Headers) включает в себя:

Пример:

Basic base64(login:key)

Логин и ключ для агента могут быть получены у администратора платежного сервиса.

Система использует статус коды HTTP для передачи информации об успешности или неуспешности запроса.

200 OK - означает что запрос успешно обработан системой и при выполнении запроса не произошло никаких сбоев.

Система регистрирует каждый входящий запрос уникальным ID запроса и сохраняет его в базе данных платежного сервиса. При успешном ответе системы данный ID запроса возвращается в соответствующем в поле ответа (x_request_id_create, x_request_id_pay, x_request_id_status). Рекомендуется сохранять данный ID в системе контрагента для более быстрого поиска запроса и решения возникающих проблем.

Подготовка выплаты payment-preparation

Название метода

Метод для создания предварительной операции выплаты на карту в Сервисе.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.create",
    "id": 2,
    "params": {
        "card": {
            "pan": "8600303655375959"
        },
        "ext_id": "local-1034",
        "amount": 1,
        "sender": "nizom",
        "sender_ip": "192.168.1.1"
    }
}

Параметры запроса

Название поля Описание
card объект карты
    pan Номер карты
ext_id ID транзакции, сгенерированный на стороне агента
amount Сумма зачисления в тийинах
sender Отправитель, включая все его параметры
sender_ip IP адрес отправителя

Пример ответа

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.create",
        "receipt": {
            "id": "65a7ae272a2e716059b6d276",
            "amount": 100,
            "state": "0",
            "created_at": 1705487911212,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard",
                    "masked_pan": "8600**********59"
                }
            }
        }
    }
}

Параметры ответа

Название поля Описание
receipt объект чека платежа
    id ID чека платежа
    amount Сумма оплаты в тийинах
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    canceled_at Временная метка отмены платежа, в миллисекундах
    receiver Объект данных получателя платежа
         card Объект карты получателя
            id Идентификатор карты
            processing Наименование процессинга карты (UZCARD, HUMO)
            masked_pan Номер карты маскированной строкой

Подтверждение выплаты payment-confirmation-2

Название метода

Метод для подтверждения операции выплаты на карту.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.confirm",
    "id": 2,
    "params": {
        "receipt_id": "659fb79b0080bb7867c03ad5"
    },
}

Параметры запроса

Название поля Описание
receipt_id Идентификатор платежа

Пример ответа

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.confirm",
        "receipt": {
            "id": "659fb79b0080bb7867c03ad5",
            "amount": 100,
            "state": "4",
            "created_at": 1704966043081,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard"
                }
            }
        }
    },
}

Параметры ответа

Название поля Описание
receipt объект чека платежа
    id ID чека платежа
    amount Сумма оплаты в тийинах
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    canceled_at Временная метка отмены платежа, в миллисекундах
    receiver Объект данных получателя платежа
        card Объект карты получателя
            id Идентификатор карты
            processing Наименование процессинга карты (UZCARD, HUMO)

Проверка статуса status-checking

Название метода

Метод для проверки статуса выплаты.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "epos2card.v2.status",
    "id": 2,
    "params": {
        "receipt_id": "659fb79b0080bb7867c03ad5"
    },
}

Параметры запроса

Название поля Описание
receipt_id Идентификатор платежа

Пример ответа

{
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
        "agent": "merchant-gw",
        "method": "epos2card.v2.status",
        "receipt": {
            "id": "659fb79b0080bb7867c03ad5",
            "amount": 100,
            "state": "4",
            "created_at": 1704966043081,
            "paid_at": 0,
            "cancelled_at": 0,
            "receiver": {
                "card": {
                    "id": "659fb6e0f3560a518842691d",
                    "processing": "uzcard"
                }
            }
        }
    },
}

Параметры ответа

Название поля Описание
receipt объект чека платежа
    id ID чека платежа
    amount Сумма оплаты в тийинах
    state Статус платежа
    created_at Временная метка создания платежа, в миллисекундах
    paid_at Временная метка оплаты платежа, в миллисекундах
    canceled_at Временная метка отмены платежа, в миллисекундах
    receiver Объект данных получателя платежа
         card Объект карты получателя
            id Идентификатор карты
            processing Наименование процессинга карты (UZCARD, HUMO)

Фискализация fiscalization

Фискализация представляет собой процесс регистрации финансовых транзакций в системе ГНК с целью обеспечения прозрачности, предотвращения налоговых уклонений и обеспечения соответствия законодательству в сфере налогообложения.

URL-адрес для работы запросов:

https://gw.zplat.uz/api/jsonrpc

Авторизация authorization-4

Базовая структура заголовков (Headers) включает в себя:

Пример:

Basic base64(login:key)

Логин и ключ для агента могут быть получены у администратора платежного сервиса.

Система использует статус коды HTTP для передачи информации об успешности или неуспешности запроса.

200 OK - означает что запрос успешно обработан системой и при выполнении запроса не произошло никаких сбоев.

Система регистрирует каждый входящий запрос уникальным ID запроса и сохраняет его в базе данных платежного сервиса. При успешном ответе системы данный ID запроса возвращается в соответствующем в поле ответа (x_request_id_create, x_request_id_pay, x_request_id_status). Рекомендуется сохранять данный ID в системе контрагента для более быстрого поиска запроса и решения возникающих проблем.

Регистрация чеков receipts-registration

Название метода

Метод позволяет выполнять фискализацию транзакций.

Пример запроса

{
    "jsonrpc": "2.0",
    "method": "ofd.register",
    "id": 123,
    "params": {
        "receipt_type": 0,
        "receipt_id": "64a2aae138480f57b14d66ac",
        "items": [
            {
                "ikpu_name": "Услуги по перевозке пассажиров воздушным транспортом на самолете (авиаперевозки) по международным направлениям",
                "ikpu": "11201001001000000",
                "package_code": "1500729",
                "inn": "60000000",
                "count": 2,
                "nds": "0",
                "amount": 100000
            }
        ]
    }
}

Параметры запроса

Название поля Описание
receipt_type Тип чека в ГНК (Продажа/Возврат = 0)
receipt_id ID транзакции в системе ZPLAT
items Группа параметров чека
    ikpu_name Название услуги в ГНК
    ikpu Номер ИКПУ кода в ГНК
    package_code Код упаковки в ГНК
    inn ИНН компании
    count Количество услуг в чеке ГНК
    nds НДС
    amount Сумма в тийинах

Пример ответа

{
    "jsonrpc": "2.0",
    "result": {
        "method": "register",
        "result": {
            "receipt_id": "64a2aae138480f57b14d66ac",
            "is_refund": 0,
            "message": "accepted",
            "receipt_type": 0,
            "receipt_name": "Продажа/Возврат",
            "terminal_id": "EP000000000000",
            "fiscal_sign": "60000000",
            "qr_code_url": "https://ofd.soliq.uz/epi?t=EP000000000000&r=0000000&c=000000000000&s=000000000000",
            "date_time": "20240228140406",
            "items": [
                {
                    "ikpuName": "Услуги по перевозке пассажиров воздушным транспортом на самолете (авиаперевозки) по международным направлениям",
                    "ikpu": "11201001001000000",
                    "packageCode": "000000000000",
                    "inn": "000000000000",
                    "count": 2,
                    "nds": "0",
                    "amount": 100000
                }
            ]
        }
    },
    "id": 123
}

Параметры ответа

Название поля Описание
receipt_id ID транзакции в системе ZPLAT
is_refund 0 не отмена, 1 отмена
message Текст ответа от ГНК
receipt_type Тип чека в ГНК - Продажа/Возврат = 0
receipt_name Название чека "Продажа/Возврат"
terminal_id Идентификация терминала
fiscal_sign Фискальное значение от ГНК
qr_code_url Ссылка на чек от ГНК
date_time Время фискализации
items Группа параметров чека
    ikpu_name Название услуги в ГНК
    ikpu Номер ИКПУ кода в ГНК
    package_code Код упаковки в ГНК
    inn ИНН компании
    count Количество услуг в чеке ГНК
    nds НДС
    amount Сумма в тийинах, переданная в ГНК

Статусы платежа payment-statuses

Описания статусов перечислены ниже:

Статус Значение Описание Признак фатальности
0 Создан Транзакция создана в Zplat нет
1 Оплачен Клиент перечислил деньги в Zplat, поставщик еще не получил платеж нет
2 Приостановлен Клиент перечислил деньги в Zplat, шлюз выполнил попытку перечислить деньги поставщику, но ответ от поставщика не получен. Транзакция в ожидании ручной проверки нет
3 В проведении Клиент перечислил деньги в Zplat, шлюз выполнил попытку перечислить деньги поставщику, но ответ от поставщика не получен. Транзакция в ожидании автоматического проведения нет
4 Успешно Транзакция успешно проведена. Поставщик получил платеж да
-1 Удален Платеж не был выполнен клиентом, транзакция удалена по таймауту да
-2 В процессе отмены Поставщику отправлен запрос на отмену платежа, но ответа от Поставщика по успешной отмене платежа не получено нет
-3 Отменен Успешная отмена платежа на стороне поставщика да
-4 Невозможно провести Транзакция не была создана для данного поставщика да
-5 Платеж возвращен Успешный возврат платежа на стороне поставщика да

Коды ошибок error-codes

Описания ошибок перечислены ниже:

Код ошибки Значение Описание
-32700 ParseError Сервер получил неверный JSON. На сервере произошла ошибка при анализе текста JSON
-32600 InvalidRequest Отправленный JSON не является допустимым объектом запроса
-32601 MethodNotFound Метод не существует / не доступен
-32602 InvalidParams Недопустимые параметры метода
-32603 InternalError Внутренняя системная ошибка
-32200 AccessDenied Доступ запрещен
-32210 AgentNotFound Агент не найден
-32211 AgentDisabled Агент не активен
-32212 AgentDepositNotEnough Баланс агента не достаточен для проведения данной операции. Пожалуйста, пополните баланс и повторите снова
-32220 ServiceNotFound Услуга не найдена
-32221 ServiceDisabled Услуга выключена
-32222 ServiceArchived Услуга в архиве
-32223 ServiceNotAllowed Услуга не разрешена для данного агента. Чтобы активировать услугу обратитесь к администратору
-32224 ServiceDisabledForAgent Услуга отключена для данного агента. Чтобы активировать услугу обратитесь к администратору
-32225 ServiceAmountIsLessThanAllowed Сумма платежа меньше допустимой
-32226 ServiceAmountIsHigherThanAllowed Сумма платежа больше допустимой
-32227 ServiceInvalidParams Данный сервис настроен некорректно. Свяжитесь с администратором системы
-32230 GatewayNotFound Шлюз не найден
-32231 GatewayDisabled Gateway отключен
-32232 GatewayNotResponding Шлюз не отвечает
-32233 GatewayRequestFailed Запрос шлюза не выполнен
-32234 GatewayTransactionFailed Gateway не смог создать успешную транзакцию
-32240 ReceiptNotFound Чек не найден
-32241 ReceiptModeIsWrong Вид чека не позволяет выполнить операцию
-32242 ReceiptStateIsWrong Некорректный статус чека для осуществления операции
-32243 ReceiptIsNotReversible Чек необратим
-32250 AntiFraudDailyAmountReached Превышен дневной лимит пополнения акканта по сумме
-32251 AntiFraudDailyTransactionsReached Превышен дневной лимит пополнения акканта по числу транзакций
-32252 AntiFraudMonthlyAmountReached Превышен месячный лимит пополнения акканта по сумме
-32253 AntiFraudMonthlyTransactionsReached Превышен месячный лимит пополнения акканта по числу транзакций
-32254 AntiFraudPauseTimeForSecondTransaction Между первым и вторым пополнением аккаунта должно пройти время
-32255 AntiFraudPauseTimeForOtherTransactions С момента последнего пополнения аккаунта не прошло достаточно времени
-32260 CardNotFound Карта не найдена. Возможно номер карты набран неверно
-32261 CardWrongNumber Неверный номер карты
-32262 CardBlocked Карта удалена или заблокирована
-32263 CardNotVerifiedForAgent Карта не верифицирована для этого агента
-32264 CardAlreadyVerifiedForAgent Карта уже верифицирована для этого агента
-32265 CardBlockedForTransfer Карта заблокирована. Перевод средств недоступен
-32266 CardPhoneNotMatch Номер телефона не подключен к этой карте
-32370 QuantityNotAvailable Количество недоступно
-32380 CurrencyRateRequestFailed Запрос на получение курса валют выдал ошибку
-32390 CalculationFailed Вычисление не удалось
-32391 CalculationAgentAmountError Ошибка расчета суммы агента
-32400 InternalSystemError Системная (внутренняя ошибка)
-32404 AccountNotFound Аккаунт не найден
-32410 ProcessingNotFound Процессинг не найден
-32411 ProcessingDisabled Процессинг отключен
-32412 ProcessingNotResponding Процессинг не ответил
-32413 ProcessingRequestFailed Запрос к процессингу выдал ошибку
-32414 ProcessingTransactionFailed Процессинг не смог создать успешную транзакцию
-32415 ProcessingAlreadyDone Процессинг уже проводил данную транзакцию
-32420 EposNotFound Epos не найден
-32421 EposModeIsWrong Вид epos не соотвествует запрашиваемой операции
-32430 TransactionStateIsWrong Некорректный статус transaction для осуществления операции
-32431 CanNotPerformTransaction Невозможно выполнить транзакцию
-32432 TransactionCancelled Транзакция была отменена
-32433 TransactionError Транзакция имеет ошибку
-32434 TransactionInProgress Попробуй позже! Транзакция находится в процессе
-32440 VerificationExpire Срок проверки истек
-32441 VerificationAttemptsLimitReached Достигнут лимит попыток подтверждения
-32442 VerificationAlreadyPassed Проверка уже прошла
-32443 VerificationNotMatch Проверка не соответствует
-32444 VerificationSmsAlreadySend СМС с подтверждением уже отправлено
-32446 CategoryNotFound Категория не найдена
-32447 CallAnotherMethod Вызовите другой метод
-32448 OTP resend limit per minute reached Достигнут лимит переотправки OTP в минуту
-32449 OTP resend limit attempts reached Достигнут лимит попыток переотправки OTP
-32450 PhoneNumberNoMatch Ошибка проверки номера телефона
json