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

Общая информация

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

В рамках платёжной платформы оплаты со списаниями по запросу проводятся в соответствии с моделью проведения платежей (Повторяемая оплата со списаниями по запросам).

Схема проведения

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

  1. Зарегистрировать повторяемую оплату.
  2. Передать запрос на проведение повторяемой оплаты с идентификатором записи о серии списаний.
  3. Принять от платёжной платформы оповещение о результате списания.

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

Рис.: Проведение экспресс-оплаты

  1. Пользователь на стороне веб-сервиса инициирует списание.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на списание.
  3. Этот запрос поступает в платёжную платформу.
  4. В платёжной платформе выполняется обработка запроса.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
  6. От платёжной платформы к платёжной системе направляется запрос на оплату.
  7. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту.
  8. На стороне эмитента выполняется обработка платежа и списание средств пользователя.
  9. От эмитента к платёжной системе направляется уведомление о результате оплаты.
  10. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты.
  11. От платёжной платформы к веб-сервису направляется оповещение о результате списания.
  12. От веб-сервиса пользователю направляется результат списания.
  13. Далее со стороны пользователя инициируются последующие списания и для каждого из них повторяются шаги 1—12.

Рис.: Проведение автооплаты

  1. От веб-сервиса на заданный URL ecommpay передаётся запрос на списание.
  2. Этот запрос поступает в платёжную платформу.
  3. В платёжной платформе выполняется обработка запроса.
  4. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
  5. От платёжной платформы к платёжной системе направляется запрос на оплату.
  6. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту.
  7. На стороне эмитента выполняется обработка платежа и списание средств пользователя.
  8. От эмитента к платёжной системе направляется уведомление о результате оплаты.
  9. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты.
  10. От платёжной платформы к веб-сервису направляется оповещение о результате списания.
  11. От веб-сервиса пользователю направляется результат списания.
  12. Далее со стороны веб-сервиса инициируются последующие списания и для каждого из них повторяются шаги 1—11.

Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API — в разделе Организация взаимодействия. Информацию о возможных статусах такой оплаты можно найти в соответствующей статье.

Формат запроса

Формат запросов в этом разделе представлен для инициирования повторяемых оплат со списаниями по запросу с использованием платёжных карт. При формировании запросов необходимо учитывать следующее:

  1. Должен использоваться POST-запрос к одной из следующих конечных точек:
    • /v2/payment/card/recurring — для всех категорий повторяемых оплат, вне зависимости от места хранения платёжных данных (на стороне платёжной платформы или на стороне веб-сервиса);
    • /v2/payment/card/sale — только для автооплат и регулярных оплат при хранении платёжных данных на стороне веб-сервиса;
    • /v2/payment/card/account_verification/token — только для автооплат при хранении платёжных данных на стороне веб-сервиса.
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным).
    • customer — объект, содержащий сведения о пользователе:
      • ip_address — используемый IP-адрес;
      • id — идентификатор пользователя в рамках проекта мерчанта;
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в дробных единицах валюты;
      • currency — валюта платежа в формате ISO-4217 alpha-3.
  3. В зависимости от конечной точки, к которой направляется запрос, в запросе также должны использоваться следующие объекты и параметры:
    • В запросах к конечной точке /v2/payment/card/recurring — идентификатор записи о серии списаний, полученный в оповещении с данными о регистрации, в параметре id объекта recurring.
    • В запросах к конечной точке /v2/payment/card/sale — объект card со следующими параметрами:
      • pan — номер карты;
      • year — год окончания срока действия карты;
      • month — месяц окончания срока действия карты;
      • card_holder — имя держателя карты (в соответствии с указанным на карте);
      • stored_card_type — указатель категории, к которой относится повторяемая оплата (4 для автооплаты и 6 для регулярной оплаты).
    • В запросах к конечной точке /v2/payment/card/account_verification/token — параметр stored_card_type объекта card со значением 4 (автооплата).
  4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму проведения платежа, а также идентификатор записи о серии списаний или данные платёжной карты и указатель категории повторяемой оплаты.

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

Рис.: Пример набора данных в запросе к конечной точке /v2/payment/card/recurring

{  
  "general":{  
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KNMp5D/aZAeb0VMdeR+CqGSm...=="
  },
  "customer":{  
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{  
    "amount":400,
    "currency":"USD"
  },
  "recurring":{
    "id":1079    // Идентификатор записи о серии списаний
  }
}

Рис.: Пример набора данных в запросе к конечной точке /v2/payment/card/sale

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "card": {
    "pan": "4314220000000056",
    "year": 2025,
    "month": 8,
    "card_holder": "JOHN SMITH",
    "stored_card_type": 4    // Проведение автооплаты
  }
}

Рис.: Пример набора данных в запросе к конечной точке /v2/payment/card/account_verification/token

{  
  "general":{
    "project_id":42,
    "payment_id":"456789",
    "signature":"v7KftZ5D/aZAdeR+qGrNxY...=="
  },
  "customer":{
    "ip_address":"202.144.196.0",
    "id":"customer_12"
  },
  "payment":{
    "amount":400,
    "currency":"USD"
  },
  "token":"pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7",
  "card":{
    "stored_card_type": 4    // Проведение автооплаты
  }
}

Формат оповещений

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

В данном случае оповещение свидетельствует о том, что в рамках проекта 42 было выполнено списание в размере 4,00 USD с платёжной карты № 424242******4243.

Рис.: Пример данных из оповещения о результате оплаты

{  
  "project_id":42,
  "payment":{  
    "id":"456789",
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "method":"card",
    "sum":{  
      "amount":400,
      "currency":"USD"
    },
    "description":""
  },
  "account":{  
    "number":"431422******0056",
    "type":"visa",
    "card_holder":"JUDY DOE",
    "id":45678,
    "expiry_month":"08",
    "expiry_year":"2025"
  },
  "recurring":{  
    "id":1079,
    "currency":"USD",
    "valid_thru":"2022-10-31T00:00:00+0000"
  },
  "operation":{  
    "id":39690002636,
    "type":"recurring",
    "status":"success",
    "date":"2019-09-04T12:57:57+0000",
    "created_date":"2019-09-04T12:57:53+0000",
    "request_id":"0b9f9e57a50-61da119c",
    "sum_initial":{  
      "amount":400,
      "currency":"USD"
    },
    "sum_converted":{  
      "amount":400,
      "currency":"USD"
    },
    "provider":{  
      "id":414,
      "payment_id":"0020000000072964",
      "date":"2019-09-04T12:58:03+0000",
      "auth_code":"634R",
      "endpoint_id":414
    },
    "code":"0",
    "message":"Success"
  },
  "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...=="
}