Перенос информации о повторяемых оплатах и токенах платёжных карт

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

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

Такой перенос сведений не облагается комиссиями со стороны ecommpay, но может облагаться комиссиями со стороны эквайера, передающего целевую информацию, и возможен только при поддержке с его стороны и при соблюдении ряда условий (подробнее — далее). С вопросами об организации такого переноса, как и с вопросами о возможности переноса информации в обратном направлении, от ecommpay к другим эквайерам, можно обращаться к курирующему менеджеру ecommpay.

В целях обеспечения конфиденциальности информации её следует переносить в зашифрованном виде. Как правило, при переносе данных в платформу ecommpay используется алгоритм шифрования PGP (Pretty Good Privacy), но в некоторых случаях по согласованию со специалистами ecommpay могут применяться и другие способы (например, если на стороне эквайера, передающего информацию, не поддерживается PGP-шифрование).

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

После того, как вся необходимая информация перенесена в платёжную платформу ecommpay и её корректность подтверждена со стороны мерчанта, с целевыми повторяемыми оплатами и токенами можно выполнять любые действия, доступные в платформе: списания в рамках повторяемых оплат (подробнее) и управление этими списаниями (подробнее), оплаты и выплаты по токенам (подробнее), проверку действительности карт (подробнее) и так далее. При этом всю информацию об операциях, выполненных через платёжную платформу ecommpay с использованием перенесённых сведений, можно получать через интерфейс Dashboard (в разделе Платежи, с информацией обо всех платежах, и в разделе Подписки, с информацией о регулярных оплатах), а также Data API и Gate API.

Прим.: Стоит учитывать, что для выполнения каких-либо действий с перенесённой информацией должны использоваться новые идентификаторы, зафиксированные в платформе ecommpay:

токены карт, указываемые в параметре token,
идентификаторы платежей, указываемые в параметре payment_id,
идентификаторы серий списаний, указываемые в параметре id объекта recurring.

Эти идентификаторы включаются в сверочный файл, отправляемый специалистам мерчанта для проверки и согласования корректности перенесённой информации, и все они применимы только в паре с идентификатором проекта (project_id), к которому изначально отнесены.

Условия и ограничения

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

Переносимая информация может относиться только к картам платёжных систем American Express, Mastercard и Visa.
Для работы по картам других платёжных систем следует формировать токены и регистрировать повторяемые оплаты непосредственно в платформе, используя поддерживаемые для этого способы.
Перенос допускается только напрямую от других эквайеров.
При работе через посредников следует оговаривать с ними возможности взаимодействия непосредственно с эквайерами.
Перенос возможен только в рамках рабочих проектов взаимодействия с платёжной платформой ecommpay.
Если мерчант ещё не является клиентом ecommpay, то с его стороны следует отправить заявку на подключение к платформе и решить последующие вопросы.
Ответственность за актуальность и корректность перенесённой информации возлагается на мерчанта.
После переноса специалистам мерчанта направляется сверочный файл, и если специалисты мерчанта подтверждают корректность информации в этом файле, то эта информация признаётся рабочей и ответственность за любые негативные последствия (например, оформление опротестования из-за списания средств не с того пользователя) возлагается на мерчанта.
Ответственность за отсутствие двойных списаний возлагается на мерчанта.
Перед началом переноса специалисты ecommpay согласовывают со специалистами мерчанта дату начала проведения платежей с использованием полученной информации. Чтобы избежать двойных списаний (через двух эквайеров), со стороны мерчанта следует обеспечить к указанной дате завершение всех операций с использованием переносимой информации через прежнего эквайера.

Порядок переноса

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

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

В общем случае со стороны мерчанта следует:

Согласовать возможность и условия переноса с эквайером, от которого актуально перенести целевую информацию.
Сообщить курирующему менеджеру ecommpay о желании перенести информацию и согласовать с ним сроки переноса и дату начала проведения платежей с использованием перенесённой информации.
В случае, если мерчант ещё не входит в число клиентов ecommpay, предварительно следует отправить заявку на подключение и решить последующие вопросы.
Согласовать со специалистами ecommpay следующее:
- Проекты, для которых актуален перенос информации.
  Если необходимо перенести информацию для нескольких проектов в платформе ecommpay, то перенос осуществляется для каждого проекта отдельно.
- Состав параметров, которые следует перенести в платёжную платформу ecommpay.
  Это могут быть только основные параметры, описанные далее и переносимые в обязательном порядке, или, если актуально, основные вместе с выбранными дополнительными (из числа поддерживаемых в платформе).
- Если необходимо перенести информацию о повторяемых оплатах — идентификаторы, которые следует присвоить этим оплатам (в качестве значений параметра scheduled_payment_id), а также записям о сериях списаний в рамках этих оплат (в качестве значений параметра register_payment_id).
  Это могут быть значения в формате, используемом по умолчанию (ecommpay–yyyymmddnnn), или в форматах, заданных мерчантом (с ограничением в 255 символов).
- Состав параметров, которые следует использовать для проверки специалистами мерчанта того, что целевая информация перенесена в платформу корректно и может использоваться при проведении платежей.
  В число этих параметров обязательно включаются новые идентификаторы (token и recurring_id), параметры из числа основных, отмеченные далее как required for verification, и, если актуально, дополнительные параметры из числа перенесённых.
- Контактную информацию ответственных специалистов мерчанта, эквайера, от которого необходимо получить информацию, и ecommpay — для организации взаимодействия и решения актуальных вопросов, в том числе по согласованию корректности перенесённой информации.

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

Как правило, перенос данных в платформу ecommpay выполняется с помощью алгоритма шифрования PGP (Pretty Good Privacy) и открытого ключа от ecommpay, но в некоторых случаях по согласованию со специалистами ecommpay могут применяться и другие способы.

Рис. 1. Открытый ключ от ecommpay для PGP-шифрования

При получении от специалистов ecommpay по указанному адресу электронной почты сверочного файла проверить полноту и корректность информации в нём.
Прим.: В сверочный файл включается информация по всем согласованным параметрам, при этом сам файл передаётся в формате CSV, а пароль для доступа к нему отправляется отдельно. Кроме того, если это было согласовано на шаге 2, могут составляться и отправляться отдельные сверочные файлы для токенов и повторяемых оплат.
Сообщить (ответным письмом) специалистам ecommpay о корректности информации или о выявленных несоответствиях.
В первом случае (если сведения в файле актуальны и корректны) после этого можно приступать к использованию перенесённой информации. Во втором случае (если обнаружены несоответствия или ошибки) специалисты ecommpay сверяют информацию из файла с информацией, полученной от прежнего эквайера, и (если информация не совпадает) исправляют её по согласованию с мерчантом или (если информация совпадает) рекомендуют обратиться к прежнему эквайеру для её актуализации, а затем сообщить специалистам ecommpay актуальные сведения.
Прим.: Проведение платежей через платформу ecommpay с использованием перенесённой информации возможно только после получения от мерчанта подтверждения корректности всех сведений.
Настроить на стороне веб-сервиса использование актуальной информации.
Так, для работы с токенами целесообразно обновить их значения (на сформированные в платёжной платформе), а для работы с повторяемыми оплатами — настроить использование новых идентификаторов платежей и списаний. После этого можно полноценно работать с перенесённой информацией.

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

Состав параметров для повторяемых оплат

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

Идентификаторы проекта и пользователя


Параметр	Описание
`project_id`	Идентификатор проекта в платёжной платформе ecommpay, к которому относится переносимая информация. Пример: `42`
`customer_id` required for verification	Идентификатор пользователя в веб-сервисе. Должен представлять собой строку длиной не более 255 символов. Пример: `customer_17008`

Сведения о платёжной карте


Параметр	Описание
`pan` required for verification	Номер платёжной карты. Переносится между эквайерами в явном виде, но в сверочном файле указывается в маскированном виде в параметре `card_number`. Пример: `4314220000000056`
`card_holder`	Имя держателя карты, в соответствии с указанным на карте и с учётом используемых ограничений. Пример: `SONYA KOVALEVSKY`
`card_expiration_month`	Порядковый номер месяца, в котором истекает срок действия карты, в виде числа от 1 до 12. Пример: `5`
`card_expiration_year`	Порядковый номер года, в котором истекает срок действия карты, в формате `ГГГГ`. Пример: `2025`
`card_type`	Указатель бренда платёжной карты со следующими вариантами значений: `amex` — American Express `maestro` — Maestro `mastercard` — Mastercard `visa` — Visa

Основные сведения о повторяемой оплате


Параметр	Описание
`description`	Описание повторяемой оплаты, в виде строки длиной не более 255 символов. Пример: `Subscription for Cosmoshop mini games pack`
`scheme_id`	Идентификатор операции, в рамках которой была зарегистрирована повторяемая оплата, на стороне международной платёжной системы (Mastercard или Visa). Может использоваться при регистрации повторяемой оплаты для карты, выпущенной в Европейской экономической зоне. Примеры: `MDS60JXCH0209` (для Mastercard) и `482269429345022` (для Visa)
`register_payment_id`	Идентификатор записи о серии списаний в веб-сервисе мерчанта, в виде строки длиной не более 255 символов. Если этот идентификатор не предоставлен мерчантом, он автоматически задаётся в платёжной платформе в формате `ecommpay–yyyymmddnnn` и передаётся мерчанту в сверочном файле. Пример: `ecommpay-20230515001`
`status`	Статус записи о серии списаний (подробнее): `active` — ожидаются дальнейшие списания `canceled` — дальнейшие списания отменены Если этот параметр не указан, серии присваивается статус `active`
`recurring_type`	Указатель типа повторяемой оплаты (подробнее): `U` — автооплата `R` — регулярная оплата

Параметры регулярных списаний


Параметр
`amount` required for verification	Сумма однократного списания. В дробных единицах валюты, если они применимы. В сверочном файле указывается в параметре `recurring_amount`. Пример: `999`
`currency` required for verification	Код валюты списаний в формате ISO 4217 alpha-3. В сверочном файле указывается в параметре `recurring_currency`. Пример: `USD`
`start_date` required for verification	Дата, с которой необходимо начать списания после переноса информации в платформу, в формате `dd-mm-yyyy`. Пример: `01-06-2023`
`start_time` required for verification	Время, в которое следует выполнять списания, в формате `hh–mm–ss`. Пример: `15-00-00`
`period` required for verification	Период, используемый как единица расчёта при определении интервала списаний (чтобы задавать списания по регулярной оплате каждые n дней, недель или иных периодов), со следующими вариантами значений: `D` — день `W` — неделя `M` — месяц `Q` — квартал `Y` — год В случае, если вместе с параметром `period` не указан параметр `period_interval`, списания выполняются ежедневно, еженедельно, ежемесячно, ежеквартально и ежегодно соответственно.
`period_interval`	Множитель, используемый по отношению к параметру `period` для определения интервала регулярных списаний (чтобы задавать списания по регулярной оплате каждые n дней, недель или иных периодов, где n задаётся как интервал) с допустимыми целочисленными значениями от 1 до 100. Например, значение `3` параметра `period_interval` и значение `W` параметра `period` определяют списания каждые 3 недели
`scheduled_payment_id`	Идентификатор платежа, в рамках которого следует выполнять списания, в виде строки длиной не более 255 символов. Если этот идентификатор не предоставлен мерчантом, он автоматически задаётся в платёжной платформе в формате `ecommpay–yyyymmddnnn` и передаётся мерчанту в сверочном файле. Пример: `ecommpay-20230515001`

Состав параметров для токенов

При переносе информации о токенах используются следующие основные параметры.


Параметр	Описание
`project_id`	Идентификатор проекта в платёжной платформе ecommpay, к которому относится переносимая информация. Пример: `42`
`customer_id` required for verification	Идентификатор пользователя в веб-сервисе. Должен представлять собой строку длиной не более 255 символов. Пример: `customer_17008`
`pan`	Номер платёжной карты. Переносится между эквайерами в явном виде. Пример: `4314220000000056`
`card_holder`	Имя держателя карты, в соответствии с указанным на карте и с учётом используемых ограничений. Пример: `SONYA KOVALEVSKY`
`card_expiration_month`	Порядковый номер месяца, в котором истекает срок действия карты, в виде числа от 1 до 12. Пример: `5`
`card_expiration_year`	Порядковый номер года, в котором истекает срок действия карты, в формате `ГГГГ`. Пример: `2025`
`card_type`	Указатель бренда платёжной карты со следующими вариантами значений: `amex` — American Express `maestro` — Maestro `mastercard` — Mastercard `visa` — Visa

Дополнительные материалы

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

Организация взаимодействия — статья с общей информацией о взаимодействии с платёжной платформой через Gate.
Повторяемые оплаты — группа статей о работе с повторяемыми оплатами.
Использование токенов — статья с информацией о работе с токенами платёжных карт.
Контроль и проведение платежей — статья с информацией о проведении и контроле проведения платежей и операций через Dashboard.
API Reference — спецификация интерфейса Gate API.