Оплата услуг через апи терминалов

Оплата услуг через API терминалов

Общая информация, ссылки

API доступно на бете и в бою

1.1 Проверка возможности оплаты. Запрос

Перед оплатой через данный API желательно проверить возможность оплаты. Это делается через метод payForServicesCheck

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.allpay.kz/mfs/soap/TransactionManagement/1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:payForServicesCheck>
         <!--Optional:-->
         <PayForServicesCheckRequest>
            <header>
               <!--Optional:-->
               <lang>ru</lang>
               <timestamp>2018-04-12T13:20:00-05:00</timestamp>
               <requester>72222222221</requester>
            </header>
            <toUserName>77072734954</toUserName>
            <servicePublicCode>185</servicePublicCode>
            <utilityAccountNumber>1234567</utilityAccountNumber>
            <!--Optional:-->
            <amount>100</amount>
         </PayForServicesCheckRequest>
      </ns:payForServicesCheck>
   </soapenv:Body>
</soapenv:Envelope>

Описание параметров.

• toUserName - логин клиента от имени которого будет проведена операция. Клиент должен присутсвовать в системе. Представляет собой набор цифр: код страны и номер телефона. Без пробелов, плюсов и других спец. символов
• servicePublicCode - код сервиса уникально идентифицирующий его. Целое число.
• utilityAccountNumber - номер счета для пополнения. Например это может быть номер телефона, если servicePublicCode - это мобильный провайдер.
• amount - опциональное значение отражающее на сколько необходимо пополнить баланс.

1.2 Проверка возможности оплаты. Ответ

Ответом на этот запрос может быть пустой ответ:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.allpay.kz/mfs/soap/TransactionManagement/1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:payForServicesCheckResponse>
         <!--Optional:-->
         <return>
            <header>
               <userMessage>?</userMessage>
               <developerMessage>?</developerMessage>
               <status>?</status>
               <timestamp>?</timestamp>
            </header>
         </return>
      </ns:payForServicesCheckResponse>
   </soapenv:Body>
</soapenv:Envelope>

Или же soapFault с описанием ошибки.

2.1 Оплата услуги. Запрос

Для оплаты услуг необходимо вызвать метод: payForServicesPay

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.allpay.kz/mfs/soap/TransactionManagement/1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:payForServicesPay>
         <!--Optional:-->
         <PayForServicesPayRequest>
            <header>
               <lang>ru</lang>
               <timestamp>2018-04-12T13:20:00-05:00</timestamp>
               <requester>72222222221</requester>
            </header>
            <toUserName>77072734954</toUserName>
            <amount>100</amount>
            <servicePublicCode>185</servicePublicCode>
            <utilityAccountNumber>1234567</utilityAccountNumber>
            <valueDate>2018-04-12T13:20:00-05:00</valueDate>
            <rrn>597e9347-0d41-46ac-8086-20a8a123e413</rrn>
         </PayForServicesPayRequest>
      </ns:payForServicesPay>
   </soapenv:Body>
</soapenv:Envelope>

Описание параметров.

• toUserName - логин клиента от имени которого будет проведена операция. Используется клиент зарегистрированный в системе или же создается фоновый кошелек. Представляет собой набор цифр: код страны и номер телефона. Без пробелов, плюсов и других спец. символов
• servicePublicCode - код сервиса уникально идентифицирующий его. Целое число.
• utilityAccountNumber - номер счета для пополнения. Например это может быть номер телефона, если servicePublicCode - это мобильный провайдер.
• amount - сумма пополнения.
• valueDate - дата транзакции. Ее необходимо выставлять чтобы при сверке транзакции в системе allpay и системе агента были в одном отчетном периоде.
• rrn - строка уникально идентифицирующая транзакцию в агентской системе. Это может быть числом или UUID. Повторный запрос с тем же rrn вернет статус ранее созданной транзакции(если такая есть) и не продублирует существующую.

Описание.

При получении первого запроса на пей будет возвращен PENDING. Этот статус означает что все еще необходимо провести все необходимые бизнес-валидации, подготовив транзакцию, заблокировав деньги на счету отправителя и отправить запрос соответствующему провайдеру и дождаться разрешения платежа от провайдера. Это в среднем занимает полминуты-минуту в зависимости от времени обработки на стороне провайдера времени обработки на нашей стороне. Если система allpay все еще отвечает PENDING - то это может означать следущее:

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

Поскольку в данном API учавствуют провайдеры услуг с которыми Allpay имеет партнерские соглашения, автоматического отклонения по сроку давности нет и быть не может. Также платеж не может быть отменен администратором после того как запрос отправлен партнерам. И поэтому необходимо слать повторно запрос до тех пор пока статус не изменится на COMPLETED или DECLINED.

Отмененные транзакции никогда не станут завершенными и завершенные никогда не станут отмененными.

2.2 Оплата услуги. Ответ

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

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns="http://www.allpay.kz/mfs/soap/TransactionManagement/1.1">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:payForServicesPayResponse>
         <!--Optional:-->
         <return>
            <header>
               <userMessage>?</userMessage>
               <developerMessage>?</developerMessage>
               <status>?</status>
               <timestamp>?</timestamp>
            </header>
            <terminalPaymentTransactionStatus>?</terminalPaymentTransactionStatus>
            <!--Optional:-->
            <reason>?</reason>
         </return>
      </ns:payForServicesPayResponse>
   </soapenv:Body>
</soapenv:Envelope>

terminalPaymentTransactionStatus - статус. Возможные значение описаны в xsd: PENDING, DECLINED, COMPLETED reason - в случае если платеж был отклонен здесь может присутствовать причина.

Описание.

В ответе содержится статус ответа и опциональная причина.

Статус может быть один из:

• fail(+ reason. Причина здесь только для логов. Тут может быть техническое описание и/или хэш стэктрейса и тд. Это не для пользователя) - платеж завершился с ошибкой, деньги не были переведены и статус никогда не изменится по этому платежу по этому GUID’у. Финальный статус
• pending - нужно повторить платеж еще раз, пока что находится в обработке. Не финальный статус
• succeeded - платеж завершился, деньги переведены(или скоро будут переведены и доступны), статус тоже не изменится по этому GUID’у. Финальный статус.

В любом другом случае(например не смогли достучаться до нас, или наш балансер вам ответил статус 500 по какой-либо причине) считать что ответ = pending.