Skip to content

_topup_card_spec_ru.html.md

Latest commit

 

History

History
147 lines (119 loc) · 14.8 KB

_topup_card_spec_ru.html.md

File metadata and controls

147 lines (119 loc) · 14.8 KB
Raw

Выплаты на карты банков РФ {#payment_card}

Операция используется для выплаты средств на банковские карты платежных систем. Выплата средств в системе QIWI Wallet представляет собой списание средств с авансового депозита агента и зачисление на банковские карты международных платежных систем «Visa International», «MasterCard International Incorporated», платежной системы «Мир», эмитированные кредитными организациями РФ. Платежная система определяется по номеру карты.

После выполнения запроса платеж начинает жизненный цикл в системе QIWI Wallet. Каждому этапу жизненного цикла соответствует определённый статус платежа. Цикл заканчивается после получения финального статуса платежа. Признак финального статуса указан в списке возвращаемых API статусов платежа.

Формат запроса {#cardpayment-req}

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

<?xml version="1.0" encoding="utf-8"?>
<request>
  <request-type>pay</request-type>
  <terminal-id>123</terminal-id>
  <extra name="password">***</extra>
  <auth>
    <payment>
      <transaction-number>12345678</transaction-number>
      <from>
        <ccy>RUB</ccy>
      </from>
      <to>
        <amount>1115.00</amount>
        <ccy>RUB</ccy>
        <service-id>32911</service-id>
        <account-number>+79991112233</account-number>
        <extra name="account1">4265111122334411</extra>
      </to>
    </payment>
  </auth>
</request>
Тег Описание
request Группирующий тег. Дочерние теги содержат параметры платежа.
request-type Тип запроса (идентификатор запроса выплаты: pay)
terminal-id Идентификатор агента в системе QIWI Wallet
extra name="password" Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet
auth Группирующий тег, описывает платежные данные
payment Группирующий тег, описывает единичный платеж. В запросе может присутствовать только один тег payment.
transaction-number Номер транзакции платежа в информационной системе агента. Его необходимо использовать при проверке статуса платежа. Номер транзакции и идентификатор terminal-id однозначно определяют платёж в системе QIWI Wallet.
from Группирующий тег, содержит информацию о сумме, полученной агентом от клиента
from/ccy Валюта счета агента, с которого будет произведено списание денежных средств (в качестве значения используется цифровой или буквенный код валюты по ISO 4217)
from/service-id Идентификатор источника (канала) пополнения (необязательный параметр). Параметр используется в случае необходимости разделения потоков пополнения, сохраняя единый баланс агента.
to Группирующий тег, содержит информацию о платеже
to/amount Сумма к зачислению на карту
to/service-id Идентификатор сервиса, на который производится зачисление средств при выплате (константа: 32911)
to/account-number Номер телефона клиента (в международном формате со знаком "+"). Указанный номер телефона не проходит проверку на валидность и на него не приходят подтверждающие SMS
to/extra name="account1" Экстра-поле, содержащее номер карты Visa / MasterCard / МИР (без пробелов) для зачисления средств при выплате. Только карты, эмитированные кредитными организациями РФ.
to/ccy Валюта выплаты (только RUB).

Обработка ответа {#cardpayment-process}

Если ответ на запрос выплаты содержит нефинальный статус платежа, то для проверки успешного прохождения платежа периодически (но не чаще одного раза в 10 минут) выполняйте запрос проверки статуса платежа до получения успешного или неуспешного финального статуса платежа.

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

  • Сетевая ошибка — таймауты при соединении или чтении ответа.
  • HTTP-ошибка сервера — HTTP-статус не равен 200, пустой ответ.
  • Некорректный ответ — XML-документ c отсутствующими обязательными тегами и/или атрибутами.
  • Ответ с ошибкой обработки запроса — сервер не смог обработать запрос.

Поскольку в этих случаях информация о статусе платежа не доступна, вы не должны отклонять платёж на своей стороне. Перейдите к периодическому запросу статуса до получения успешного или неуспешного финального статуса платежа.

Если вы не уверены в корректной расшифровке ответа API, обратитесь в Службу поддержки: bss@qiwi.com.

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

Ответ без ошибок обработки {#cardres_payment}

<?xml version="1.0" encoding="utf-8"?>
<response>
<result-code fatal="false">0</result-code>
<payment status='60' txn_id='6060' transaction-number='12345678' result-code='0' message='Ok' msg='Ok' final-status='true' fatal-error='false' txn-date='02.03.2011 14:35:46'  >
  <from>
    <amount>1115.00</amount>
    <ccy>643</ccy>
  </from>
  <to>
    <service-id>32911</service-id>
    <amount>1000.00</amount>
    <ccy>643</ccy>
    <account-number>+79991112233</account-number>
  </to>
</payment>
<balances>
<balance code="428">0.00</balance>
<balance code="643">200</balance>
<balance code="840">12.20</balance>
</balances>
</response>

Если запрос обработан корректно, то в ответе возвращаются сведения о платеже в теге <payment>.

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

Тег Описание Атрибуты
response Группирующий тег ответа. Отсутствуют.
result-code Код ошибки обработки запроса. fatal – логический признак фатальности ошибки обработки запроса.
payment Описание принятого платежа. status – статус платежа в системе QIWI Wallet;
txn_id – идентификатор транзакции платежа в системе QIWI Wallet. Если не заполнен, платёж не был зарегистрирован из-за временной ошибки. Попробуйте повторить запрос позже;
transaction-number – номер транзакции платежа в информационной системе Контрагента;
result-code – код ошибки обработки платежа;
message, msg — текстовое описание ошибки;
final-status – логический признак финального статуса платежа;
fatal-error — логический признак фатальности ошибки обработки платежа;
txn-date – дата приема платежа в систему QIWI Wallet.
from Группирующий тег, содержит информацию о списанных средствах. Отсутствуют.
from/amount Сумма, списанная со счета Контрагента. Отсутствуют.
from/ccy Валюта счета (в качестве значения используется цифровой или буквенный код валюты по ISO 4217). Отсутствуют.
from/service-id Идентификатор источника (канала) пополнения (необязательный параметр). Параметр используется в случае необходимости разделения потоков пополнения, сохраняя единый баланс агента.
to Группирующий тег, содержит информацию о платеже. Отсутствуют.
to/amount Сумма к зачислению на карту. Отсутствуют.
to/service-id Идентификатор сервиса, на который производится зачисление средств при выплате. Отсутствуют.
to/account-number Номер телефона Клиента. Отсутствуют.
to/ccy Валюта выплаты (цифровой или буквенный код валюты по ISO 4217). Отсутствуют.
balances Группирующий тег, содержит информацию о балансе всех активных счетов Контрагента в системе QIWI Wallet. Отсутствуют.
balances/balance Текущий баланс единичного счета Контрагента в системе QIWI Wallet code - цифровой код валюты счета (в формате ISO 4217).

Ответ с ошибками обработки {#cardres_tech}

Если сервер QIWI Wallet не смог обработать запрос на пополнение карты, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о платеже отсутствует в ответе, поэтому вы должны перейти к периодическому запросу статуса, не отклоняя платёж на своей стороне.

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false" message="Неизвестная ошибка" msg="Неизвестная ошибка">300</result-code>
</response>

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

Тег Описание Атрибуты
result-code Код ошибки обработки запроса. fatal – логический признак фатальности ошибки обработки запроса. Фатальность ошибки означает, что повторный запрос с теми же параметрами приведет к повторению той же ошибки. Фатальные ошибки обработки запроса, как правило, вызваны ошибками конфигурирования и требуют ручного вмешательства (обращения в службу поддержки сервиса QIWI Wallet по адресу bss@qiwi.com). При появлении таких ошибок вы можете либо не приостанавливать выполнение повторных запросов, либо приостановить до устранения ошибок конфигурирования;
message, msg — текстовое описание ошибки.

Дополнительная информация о платеже {#extra-info}

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

  • Идентификатор платежа в платёжной системе.
  • Идентификатор платежа на стороне банка получателя.

Для этого:

  1. Убедитесь, что платёж принял финальный статус.
  2. Отправьте запрос на выплату с параметрами, указанными в исходном платеже.
  3. Извлеките из XML-документа ответа тег payment/extra name="rrn". Его значение соответствует идентификатору платежа в платёжной системе карты. Если тег отсутствует, то идентификатор этого платежа в платежной системе недоступен.
  4. Извлеките из XML-документа ответа тег payment/extra name="billRegId". Его значение соответствует идентификатору платежа в информационной системе банка получателя. Если тег отсутствует, то идентификатор этого платежа у банка получателя недоступен.