NAV Navbar
shell ruby python javascript
  • Вступление
  • Оплата с переходом на сайт UPAY
  • Оплата без перехода на сайт UPAY
  • Ошибки
  • Вступление

    Инструкция по интеграции системы Партнеров к API системы UPAY

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

    Платежная система UPAY(далее UPAY) поддерживает 6 типов оплат:

    1. Через личный кабинет – cabinet.smst.uz;
    2. С помощью кода - USSD *850#;
    3. Отправка СМС на короткий номер 1400;
    4. Приложение - Android ;
    5. Приложение - iOS;
    6. Оплата без регистрации через сайт – pay.smst.uz

    Оплата с переходом на сайт UPAY

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

    I. Офлайн оплата (без настроенного биллинга) – если у поставщика услуг нет собственного биллинга через который поставщик может в реальном времени принимать запросы и отправлять ответы, то команда UPAY предоставляет поставщику свою биллинговую систему, а так же дает логин и пароль для входа в Мониторинг - UPAY (кабинет поставщика услуг) и полную поддержку в помощи отслежки транзакций и учета. Для быстрого информирования об оплате к услуги поставщика привязывается номер на который будет приходить смс.

    - Мониторинг системы UPAY. У поставщика услуг будет возможность просматривать информацию о всех оплатах через специальный личный кабинет доступ к которому технической поддержкой UPAY.

    - СМС-уведомление. По каждой оплате будет отправляться СМС сообщение на предоставленный поставщиком услуг номер.

    II. Онлайн оплата – в этом случае UPAY совместно с разработчиками поставщика услуг интегрируют онлайн систему ведение учета по средством отправке данных определенным методом и получением результата(ответа).
    Примеры отправки методов и отправляемых данных приведены в нижних в очередности запросах.

    Примечание: Если используется офлайн биллинговая система, то остальную часть инструкции можно не читать. Запросы II и III относятся только к онлайн биллинговым системам

    I-запрос

    I-запрос. Запрос должен сопровождаться HTTP методом POST или GET и должен быть отправлен на адрес
    https://pay.smst.uz/prePay.do по протоколу HTTP/1.1.

    Пример скрипта HTML формы для перенаправления клиента на сайт pay.smst.uz:

    
    <form action="https://pay.smst.uz/prePay.do" target="_blank" method="POST">
     <h4>Пополнить баланс</h4>
    
     <label>Идентификационный номер</label>
     <input name="personalAccount" type="text" /> <!-- Аккаунт или Id номер за который поизводиться оплата -->
    
     <label>Сумма платежа</label>
     <input name="amount" type="text" />   <!-- Сумма оплаты -->
     <input name="serviceId" value="8" type="hidden" />  <!-- Уникальный номер услуги в системе UPAY -->
     <input name="apiVersion" value="1" type="hidden" /> <!-- Версия UPAY = 1 -->
     <input type="submit" value="Оплатить через UPAY" />
     </form>
    
    

    В запросе должны присутствовать следующие параметры:

    Параметры Тип значения Описание
    serviceId Integer Уникальный код услуги поставщика. Выдается системой UPAY на этапе интеграции. Обязательный параметр.
    personalAccount String Логин, номер телефона или номер заказа куда будет проводиться оплата. По этому параметру поставщик услуг сможет определить от кого и для чего была осуществлена оплата. Например, при оплате услуг мобильных операторов personalAccount будет равен номеру, на который производиться оплата. Обязательный параметр.
    amount Integer Сумма оплаты. Обязательный параметр.
    apiVersion Integer Этот параметр обозначает версию API. В текущем релизе значение равно 1. Обязательный параметр.

    Пример: для пополнения счёта мобильного телефона абонент с сайта Ucell на сайт

    POST /prePay.do HTTP/1.1
    Host: pay.smst.uz
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 65
    personalAccount=998931112233&amount=1000&serviceId=8&apiVersion=1
    


    1-график. Пользователя нужно перенаправить на pay.smst.uz посредством POST или GET запроса

    Для простого восприятия в примере кода элементы дизайна не показаны. Так же, чтобы помочь пользователям вводить свои данные правильно, в коде должны присутствовать вспомогательные аттрибуты тэгов, такие как placeholder, maxlength или javascript валидаторы. Помогая пользователям вводить данные правильно, Вы обеспечите защиту от ошибочных платежей.

    II-запрос

    II-запрос. Если поставщик услуг интегрирует онлайн систему оплаты о каждой успешной транзакции проведённой со стороны UPAY, на заранее согласованный URL адрес отправляется информация о деталях транзакции. Система UPAY может отправить этот запрос на базе протокола HTTP/1.1 методами POST или GET. Значения параметров отправляются в формате JSON или в простом String.

    В запросе отправляются следующие параметры:

    Пример II-го запроса отправленный в формате JSON:

    {
     "upayTransId" : 1232145,
     "upayTransTime" : "2016-10-17 23:58:12",
     "upayPaymentAmount" : 1000,
     "personalAccount" : "998931112233",
     "accessToken" : "cf23df2207d99a74fbe169e3eba035e633b65d94"
     }
    

    Пример II-го запроса отправленный с помощью обычным String форматом:

     POST /upayPayment.php HTTP/1.1
     Host: billing.example.uz
     Content-Type: application/x-www-form-urlencoded
     Content-Length: 186
     upayTransId=1232145&upayTransTime=2016-10-17 23:58:12&upayPaymentAmount=1000&personal
     Account=998931112233&accessToken=cf23df2207d99a74fbe169e3
     eba035e633b65d94
    
    Параметры Тип значения Описание
    upayTransId Integer Уникальный номер транзакции в системе UPAY.
    upayTransTime String Время оплаты.Формат: YYYY-MM-DD HH:mm:ss.
    upayPaymentAmount Integer Сумма оплаты.
    personalAccount String Логин, номер телефона или номер заказа за который была произведена оплата. По этому параметру поставщик услуг сможет определить куда и откуда была осуществлена оплата. Например, при оплате услуг мобильных операторов personalAccount будет равен номеру на который произведена оплата.
    accessToken String Сгенерированный ключ для безопасности отправки данных (оговаривается интеграторами)

    URL адрес предоставленный со стороны поставщика услуг, на который будет отправляться запрос, должен полностью быть защищён от посторонних запросов. Во время интеграции с системой UPAY поставщик услуг может воспользоваться одной или несколькими видами защиты: С помощью accessToken. С каждым запросом отправляется особый шифр – accessToken. Детали генерации данного шифра согласуются с поставщиком услуг на этапе интеграции (заранее): ◦ При генерации шифра можно использовать алгоритмы MD5 или SHA1. ◦ Для генерации уникального шифра система UPAY может использовать параметры отправляемые в теле запроса и другие статические параметры (специальный код, пароль и т.д.).

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


    2-график. Обмен данными между биллингом поставщика услуг и системой UPAY для регистрации оплаты

    III-ответ

    III-ответ. На II-запрос биллинговая система поставщика услуг должна ответить следующим образом: В полученном ответе код HTTP статуса должен быть равен 200. Если получено иное значение кода, то транзакция будет отменена и будет отмечена как ошибочная, со статусом "Системная ошибка". Ответ должен быть обязательно в формате JSON и с данными параметрами:

    Пример:

    {
     "status" : 1,
     "message" : "Успешно"
     }
    
    
    Параметры Тип значения Описание
    status Integer Этот параметр означает успешность или неудачность регистрации оплаты у поставщика услуг. 1 – оплата зарегистрирована успешно. В ином случае – регистрация дала сбой. В таком случае оплата будет отменена в системе UPAY.
    message String В случае ошибки, короткое описания ошибки должно быть указана в данном параметре на русском языке.

    Пример:

    {
     "status" : 0,
     "message" : "Клиент с таким номером не найден."
     }
    

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

    Небольшой наглядный пример того как выглядит сайт pay.smst.uz и как проходит оплата:


    После перехода на сайт pay.smst.uz клиент должен заполнить правильно параметры пластиковой карты, 16 значный номер и срок действия в формате ГГММ, а так же указать номер телефона привязанный к данной пластиковой карте.


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

    Оплата без перехода на сайт UPAY

    (Реализация методов разовой оплаты за услугу поставщика, без перехода на страницу платежной системы)

    URL для обращение к API системы UPAY: https://IP:PORT/STAPI/STWS?wsdl

    STPimsApiPartnerKey => Уникальный ключь который выдается платежной системой для использование методов
    login => Логин выдается платежной системой для генирации accessToken
    password => Пароль так же выдается платежной системой для генирации accessToken

    Для более подробного изучения рекомендуем использовать программу SOAP UI

    При разовой оплате за услугу поставщика используются два метода:

    1. Method prepayment (Подготовка данных к оплате)
    2. Method confirmPayment (Подтверждение оплаты)

    Схема действия оплаты:

    Alternate image text

    Method prePayment

    Метод позволяющий подготовить данные к оплате (метод формирующий оплату)

    Request Params Example

    <PrepaymentRequest>
        <StPimsApiPartnerKey>хххХХХхХхХхХХХхХХХХхХхХХхХХхХХ</StPimsApiPartnerKey>
        <PhoneNumber>911912424</PhoneNumber>
        <CardNumber>8600********2020</CardNumber>
        <CardExpireDate>1902</CardExpireDate>
        <ServiceId>1</ServiceId>
        <ServiceType>3</ServiceType>
        <PaymentType></PaymentType>
        <PaymentDateFrom></PaymentDateFrom>
        <PaymentDateTo></PaymentDateTo>
        <RegionId></RegionId>
        <SubRegionId></SubRegionId>
        <PersonalAccount>he-2217861</PersonalAccount>
        <PaymentAmount>5000</PaymentAmount>
        <Lang>ru</Lang>
    </PrepaymentRequest>
    

    Request Params

    Property Type Description
    STPimsApiPartnerKey String Секретный ключ партнера для использования API.(Выдается платежной системой)
    PhoneNumber String Номер телефона у которого включена услуга «СМС-Информирование» по карте UzCard Online. (Example: 911902424)
    CardNumber String 16-значный номер карты UzCard Online.
    CardExpireDate String Срок годности карты, формат (YYMM => ГОД МЕСЯЦ)
    ServiceId int Идентификационный номер Услуги зарегистрированной в Платежной Системе.(Выдается платежной системой)
    ServiceType ID категории в которой располагается услуга поставщика
    PaymentType String Параметр определения наличия счетчика
    PaymentDateFrom String Период Даты/Показания счетчика с какого числа Формат Даты: dd.mm.yy / Формат Счетчика: number
    PaymentDateTo String Период Даты/Показания счетчика по какое число Формат Даты: dd.mm.yy / Формат Счетчика: number
    RegionId String Идентификационныи номер Области
    SubRegionId String Идентификационныи номер Района
    PersonalAccount String Логин или Идентификационныи номер пользователя
    PaymentAmount String Сумма оплаты
    Lang String Языковой параметр (ru, uz, en)

    Response Result Example

    <ns2:prepaymentResponse xmlns:ns2="http://st.apus.com/">
        <return>
            <ServiceCategoryName>Интернет провайдеры</ServiceCategoryName>
            <ServiceName>Sarkor Telecom</ServiceName>
            <PersonalAccount>he-2217861</PersonalAccount>
            <PaymentAmount>5000</PaymentAmount>
            <TransactionId>12345</TransactionId>
            <Result>
                <code>OK</code>
                <Description>Нет ошибок</Description>
            </Result>
        </return>
    </ns2:prepaymentResponse>
    
    

    Response Result

    Property Type Description
    ServiceCategoryName int Наименование категории в которой располагается услуга
    ServiceName String Наименование услуги поставщика
    PersonalAccount String Логин или Идентификационныи номер пользователя
    PaymentAmount int Оплачиваемая сумма
    TransactionId int Разовый номер транзакции для метода проверки
    Result array Массив данных с параметрами о результате выполнения операции
    Result -> Code String Код ответа для текущей операции ОК – success, ERROR – fail
    Result -> Description String Описание ошибки

    Method confirmPayment

    Метод позволяющий подтвердить оплату

    Request Params Example

    
    <confirmPaymentRequest>
        <StPimsApiPartnerKey>XXxxxXXxXXXXxXxxxXXxxxxXXXxX</StPimsApiPartnerKey>
        <TransactionId>12345</TransactionId>
        <OneTimePassword>225599</OneTimePassword>
        <Lang>ru</Lang>
    </confirmPaymentRequest>
    
    

    Request Params

    Property Type Description
    TPimsApiPartnerKey String Секретный ключ партнера для использования API.(Выдается платежной системой)
    TransactionId int Разовый номер транзакции для подтверждения проверки, полученный из метода prepayment
    OneTimePassword int Разовый код подтверждения (отправленный пользователю после выполнения метода prepayment) (Водимый пользователем)
    Lang String Языковой параметр (ru, uz, en)

    Response Result Example

    <ns2:confirmPaymentResponse xmlns:ns2="http://st.apus.com/">
        <return>
            <ServiceId>1</ServiceId>
            <CardNumber>************2020</CardNumber>
            <PersonalAccount>he-2217861</PersonalAccount>
            <PaymentAmount>5000</PaymentAmount>
            <PaymentTransactionId>1965435</PaymentTransactionId>
            <UserName>15911902424</UserName>
            <PaymentPerformedTime>05/05/2017 11:30</PaymentPerformedTime>
            <Terminal>
                  <BankAccount>20214000400504751004</BankAccount>
                  <CompanyName>Sarkor Telecom</CompanyName>
                  <INN>202071401</INN>
                  <MFO>00444</MFO>
                  <OKONX>82100</OKONX>
            </Terminal>
            <Result>
                  <code>ОК</code>
                  <Description>Нет ошибок</Description>
            </Result>
    </return>
    </ns2:confirmPaymentResponse>
    
    

    Response Result

    Property Type Description
    ServiceId int Идентификационный номер Услуги в системе
    CardNumber 16-значный номер карты UzCard Online
    PersonalAccount String Логин или Идентификационныи номер пользователя
    PaymentAmount int Сумма оплаты
    PaymentTransactionId int Номер транзакции в платежной системе
    UserName String Номер пользователя привязанный к карте UzCard Online
    PaymentPerformedTime Дата совершения оплаты
    Terminal array Массив данных EPOS
    Terminal -> BankAccount Расчетный счет поставщика
    Terminal -> CompanyName Наименование поставщика
    Terminal -> INN ИНН поставщика
    Terminal -> MFO МФО поставщика
    Result array Информация о результате выполнения операции
    Result -> Code String Код ответа для текущей операции ОК – success, ERROR – fail
    Result -> Description String Описание ошибки

    Небольшой наглядный пример того как выглядит оплата с сайта поставщика:


    Клиент должен заполнить правильно параметры пластиковой карты, 16 значный номер и срок действия в формате ГГММ, а так же указать номер телефона привязанный к данной пластиковой карте.


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

    Ошибки

    ИД ошибки язык код ошибки описание
    65 RU STPIMS-ERR-001 Ведутся тех. работы, пожалуйста обратитесь в тех поддержку или попробуйте позже
    68 RU STPIMS-ERR-003 Неправильный партнер
    69 RU STPIMS-ERR-004 Карта не найдена
    70 RU STPIMS-ERR-005 Карта не подключена к номеру
    73 RU STPIMS-ERR-008 Карта не зарегистрирована
    74 RU STPIMS-ERR-009 Неправильные параметры
    77 RU STPIMS-ERR-012 Неправильный id транзакции
    78 RU STPIMS-ERR-013 Неправильные данные пользователя
    79 RU STPIMS-ERR-014 Неправильная попытка входа
    82 RU STPIMS-ERR-017 Неактивный партнер
    83 RU STPIMS-ERR-018 Отказано в соединении
    86 RU STPIMS-ERR-021 Неправильный номер телефона
    89 RU STPIMS-ERR-024 Нет соединения с банком
    98 RU STPIMS-ERR-033 Телефонный номер не соответствует
    108 RU STPIMS-ERR-043 Банковская Карта не найдена
    112 RU STPIMS-ERR-047 СМС информер не включен
    122 RU STPIMS-ERR-057 Недостаточно средств
    193 RU STPIMS-ERR-064 Оплата отменена
    196 RU STPIMS-ERR-065 Оплата в процессе
    203 RU STPIMS-ERR-067 Срок действия вашей карты истек. Просим обратиться в банк.
    239 RU STPIMS-ERR-079 Ваша карта заблокирована (не активированная). Просим обратиться в банк.
    275 RU STPIMS-ERR-091 Оплата уже произведена ранее
    311 RU STPIMS-ERR-106 Истек срок действия карты
    323 RU STPIMS-ERR-110 Оплата на корпоративные и юридические счета не поддерживается. Обратитесь к поставщику услуг.
    326 RU STPIMS-ERR-111 Недостаточно средств. Пожалуйста, обратитесь в свой банк.