# Платформа {#ru_platform_about} раздел с общими материалами о платёжной платформе, её устройстве и работе Этот раздел посвящён общим вопросам, касающимся работы с платёжной платформой Ecommpay. Он может быть полезен для понимания принципов работы и специфики платформы, а также для организации работы с ней через один или несколько интерфейсов.Например, при организации оплат с использованием платёжной формы от Ecommpay, возвратов через API, а также контроля информации специалистами мерчанта через пользовательскую панель управления, в этом разделе можно узнать о подходящих интерфейсах и компонентах, об общем процессе подключения к платформе, о схемах проведенияактуальных типов платежей и их статусах, о порядке работы с цифровой подписью и о способах получения информации о платежах — и использовать эти сведения для настройки наиболее подходящих решений. В состав этого раздела входят следующие материалы: - [Общая информация](ru_platform_overview.md)— вводная статья с информацией о платёжной платформе, её интерфейсах, компонентах и ключевых возможностях. - [Подключение](ru_platform_registration.md)— статьи об общем порядке подключения к платформе и о специализированных решениях для отдельных групп мерчантов. - [Проведение платежей](ru_platform_payment_model.md)— статьи о типах платежей, которые можно проводить через платформу, схемах их проведения и возможных статусах этих платежей и выполняемых при их проведении операций. - [Работа с подписью к данным](ru_platform_signature.md)— материалы о том, как можно организовать подписывание и проверку подлинности данных, необходимые в работе с любым из программных интерфейсов платформы. - [Работа с информацией о платежах](ru_platform_payment_information.md)— материалы о том, как можно получать и обрабатывать информацию о платежах, проводимых в платформе, чтобы организовывать необходимые со стороны мерчанта процессы контроля, реагирования и анализа. В дополнение к материалам этого раздела для знакомства с возможностями платформы и организации работы с ней могут быть полезны статьи о работе с конкретными интерфейсами и компонентами платформы \(в разделе **Инструменты**\), материалы [о работе с рисками](ru_dbl_risks.md)и [с опротестованиями](ru_faq_chargebacks.md), ответы на различные вопросы в разделе [FAQ](ru_faq.md) и другие материалы настоящей документации. Кроме того, при возникновении вопросов всегда можно обращаться к курирующему менеджеру и специалистам технической поддержки Ecommpay. - **[Общая информация](ru_platform_overview.md)** статья с вводной информацией о платёжной платформе, её интерфейсах, компонентах и ключевых возможностях - **[Подключение](ru_platform_registration.md)** статьи об общем порядке подключения к платформе и о специализированных решениях для отдельных групп мерчантов - **[Проведение платежей](ru_platform_payment_model.md)** статьи о типах платежей, которые можно проводить через платформу, схемах их проведения и допустимых операциях и статусах - **[Работа с подписью к данным](ru_platform_signature.md)** статья о порядке создания и проверки подписи, используемой в программных запросах, ответах и оповещениях для обеспечения защищённого обмена данными при взаимодействии с платёжной платформой - **[Работа с информацией о платежах](ru_platform_payment_information.md)** статьи о том, как можно получать информацию о платежах, проводимых через платформу, чтобы организовывать необходимые процессы контроля, реагирования и анализа --- # Общая информация {#ru_platform_overview} статья с вводной информацией о платёжной платформе, её интерфейсах, компонентах и ключевых возможностях ## Введение {#section_gwd_wqr_qnb .section} Платёжная платформа Ecommpay позволяет проводить платежисамых разных типовпрактически во всех уголках Земли, с использованием широкого спектра валют,методов и сценариев.Это неизбежно требует качественной организации процессов и мощных вычислительных ресурсов, и технически платформа представляет собой передовую информационную систему — современную, высоконадёжную и производительную — чтобы все необходимые на её стороне действия выполнялись в доли секунд и позволяли мерчантам и их пользователям раздвигать горизонты услуг и наслаждаться качеством сервиса. ![](images/ecommpay/ru_platform_functional.svg "Проведение платежей через основные интерфейсы платформы") Вместе с тем, универсальность платёжной платформы Ecommpay, с изобилием её возможностей и вариантов использования, ведёт и к широкому выбору способов работы с ней со стороны мерчантов. Это обеспечивает удобство в непосредственной работе, но это же может создавать и сложности, в частности, когда мерчантам необходимо подбирать оптимальные решения для своих нужд.Чтобы не теряться в вопросах работы с платформой, всегда можно использовать настоящую документацию\(и в том числе навигатор по её материалам, доступный на стартовой странице\), а также обращаться к курирующему менеджеру и специалистам технической поддержки Ecommpay. ## Ключевые понятия: проекты и платежи {#section_mrg_vjt_szb .section} Как бы ни строилась в различных случаях работа с платформой, на техническом уровне она начинается с регистрации в платформе конкретного мерчанта и проекта взаимодействия с его веб-сервисом. При этом проекту сразу же присваивается постоянный идентификатор и задаётся широкий набор изменяемых свойств,включая доступностьплатёжных методов и валют, а также различные параметры, влияющие на проведение платежей и порядок работы. И уже после этого \(и только тогда\) в рамках проекта конкретного мерчанта для него могут проводиться платежи— комплексные действия по обеспечению переводов денежных средств между мерчантом и его пользователями. Количество проектов для одного мерчанта может быть разным. Зачастую для работы вполне достаточно одного проекта, но в каких-то случаях их число может расти. Как правило, оптимальное количество определяется специалистами Ecommpay, исходя из специфики мерчанта и его задач. И, что важно, это число может пересматриваться в процессе сотрудничества. В свою очередь, платежи могут включать в себя различное число операций, связанных с движением денежных средств. Например, в рамках одного платежа может произойти оплата, а после — частичный или полный возврат средств пользователю. Или, другой пример, в рамках одного платежа по подписке может проводиться серия регулярных списаний на заданную сумму. И так далее.Состав допустимых типов платежей, операций и их статусов чётко регламентируется и описан далее в рамках этого раздела. Здесь же важно определить, что платежи проводятся в рамках проектов и могут включать в себя различное число операций. В целом такую логику — согласно которой для работы с мерчантом в платформе регистрируются проекты и в рамках этих проектов проводятся платежи, включающие в себя требуемое количество операций — можно считать базовой.Она применяется в отношении всех действий в платформе Ecommpay, начиная с тестовых подключений и проведения тестовых платежей и заканчивая распределением прав доступа к информации о конкретных платежах и операциях на уровне доступа к информации по конкретным проектам. ## Инструменты для работы: интерфейсы и компоненты {#section_ef5_v4b_snb .section} Для работы с платёжной платформой Ecommpay со стороны мерчанта и его веб-сервиса доступны специализированные интерфейсы, каждый из которых позволяет решать определённые задачи. К таким интерфейсам относятся: - [Payment Page](ru_PP_about.md) — платёжная форма Ecommpay, которая вызывается через программный интерфейс\(API\) и позволяет проводить оплатыи выполнять другие действияс применением различных платёжных методов. - [Gate](ru_Gate_Integration_About.md) — платёжный программный интерфейс\(API\), который обеспечивает максимальные возможности в работе с платежамивсех поддерживаемых типови методов и подразумевает при этом использование на стороне веб-сервиса собственных решений мерчанта в части пользовательского интерфейса\(UI\). - [Dashboard](ru_dbl_about.md) — веб-интерфейс для сотрудников мерчанта, позволяющий настраивать различные параметры работы по проектам,и в том числе интерфейс платёжной формы Payment Page, а также контролировать состояние всех проводимых платежей, управлять их проведением и инициировать различные платежи и операции. - [Data API](ru_dbl_api_protocol.md) — программный интерфейс \(API\), позволяющий получать информацию об операциях,опротестованиях и балансах по используемым проектам и выстраивать сводный контроль и анализ проведения платежей за рамками интерфейса Dashboard\(например, в сторонней аналитической системе\). Вместе с тем, для более удобной работы с платформой со стороны мерчантов в определённых ситуациях могут использоваться дополнительные компоненты— отчуждаемые от платформы программные продукты, которые могут применяться в веб-сервисах и обеспечивать решение определённых задач. К таким компонентам относятся: - [SDK для мобильных приложений](ru_sdk_overview.md) — наборы средств разработки \(SDK\) для подключения к платформе мобильных приложений, работающих с операционными системами iOS и Android, с использованием специальной версии платёжной формы Payment Page или собственного пользовательского интерфейса. - [Интеграционные модули для CMS](ru_CMS.md) — плагины\(в терминологии отдельных систем также „картриджи“\) для подключения к платформе веб-сервисов, созданных на базе ряда распространённых систем управления содержимым\(CMS\) и профильных платформ электронной коммерции. - [SDK для работы с подписью](ru_sdk_overview.md) — наборы средств разработки\(SDK\) на разных языках программирования, позволяющие подписывать отправляемые данные и проверять корректность получаемых данныхпри программном взаимодействии с платформой. Вместе все эти средства составляют множество инструментов для работы с платформой со стороны мерчанта, и в разных случаях можно строить работу с использованием различного числа инструментов.Так, в каких-то ситуациях для решения всех задач может быть достаточно одного интерфейса Dashboard, а в каких-то может быть актуально использовать SDK для мобильных приложений и для работы с подписью, Payment Page, Gate, Dashboard и Data API. Как правило, ключевыми факторами для выбора тех или иных инструментов являются целевые типы платежей и пользовательских сценариев, способы разработки веб-сервиса и интересующие способы организации работы с платформой. С учётом этих факторов построен, в частности, и навигатор по настоящей документации, доступный на её стартовой странице. И с учётом этих же факторов может выполняться подбор оптимальных решений с участием специалистов Ecommpay. ## Возможности и процедуры {#section_krp_kbn_tzb .section} Возможности платформы Ecommpay касаются множества аспектов, и, что значимо, в разной мере поддерживаются при работе с различными инструментами.Так, например, через Payment Page можно инициировать блокировки средств пользователей в рамках двухстадийных оплат, но для списаний или отмен блокировок этих средств необходимо использовать уже Gate или Dashboard \(либо настроить автоматические списания по истечении заданного времени\). Подобные нюансы касаются каждого инструмента, и можно сказать, что: - каждый инструмент платформы позволяет решать свой круг задач; - для решения любой релевантной задачи может подходить один или несколько инструментов; - для эффективной работы с платформой зачастую полезно комбинировать её возможности и инструменты согласно специфике решаемых задач. К этому можно также добавить, что технически за поддержкой любой возможности стоит выполнение определённых процедур, и при работе с разными инструментами эти процедуры в той или иной мере могут касаться веб-сервиса, конечных пользователей или специалистов мерчанта. Например, аутентификация пользователя с применением протокола 3‑D Secure, используемая для проведения оплат, при работе с платёжными интерфейсами Ecommpay не требует участия веб-сервиса \(только действий пользователя\), а при работе через Gate требует от веб-сервиса целого ряда действий \(по приёму и обработке данных и перенаправлениям пользователя\). Такие нюансы, связанные со спецификой различных инструментов и возможностей, тоже всегда полезно иметь в виду. Функционально возможности платформы можно разбить на несколько групп. Это: - Проведение платежейразных типов\(или выполнение основных платёжных процедур\) — группа возможностей, обеспечивающих базовые функции платформы. Эти возможности принципиально позволяют проводить оплатыразных типов\(в одну и две стадии, разово и с различными видами повторений\), а также выплаты и „условные“ платежи для проверки действительности платёжных инструментови использовать при этом различные платёжные методы. - Выполнение вспомогательных платёжных процедур— группа возможностей, обеспечивающих соблюдение требований, которые могут предъявляться при проведении платежей в отдельных случаях. Эти возможности позволяют выполнять такие процедуры, которые не обязательны для всех случаев, но обязательны для некоторых — в соответствии с требованиями платёжных систем, региональной спецификой и другими условиями.Как правило, это относится к необходимости дополнительного подтверждения подлинности пользователей, и примерами таких процедур можно считать аутентификацию 3‑D Secure и проверку Address Verification Service. - Расширение платёжных сценариев\(или использование дополнительных возможностей\) — группа возможностей, обеспечивающих подстройку под различные ситуации и потребности для улучшения платёжных сервисов. Эти возможности позволяют выполнять такие процедуры, которыеможно назвать полезными дополнениями: они не обязательны для проведения платежей, но способствуют тому, чтобы повышать вариативность платёжных сценариев, конверсию платёжных интерфейсов, проходимость платежей, уровень защиты от мошенничества и лояльность пользователей. - Обеспечение функций управления платёжными решениями и средствами— группа возможностей, покрывающих те потребности мерчантов, которые связаны с управлением платёжными решениями, но не касаются непосредственного проведения платежей. Эти возможности позволяют обеспечивать и облегчать такие процедуры, которые касаются контроля и анализа информации о платежах, работы с опротестованиями платежей, управления балансовыми средствами и прочих подобных процессов, необходимых в работе мерчантов. Вместе эти группы возможностей обеспечивают для мерчантов функциональную полноту и законченность платформы. **На уровень выше:**[Платформа](ru_platform_about.md) --- # Подключение {#ru_platform_registration} статьи об общем порядке подключения к платформе и о специализированных решениях для отдельных групп мерчантов Для подключения к платёжной платформе Ecommpay необходимо решить ряд организационных, юридических и технических вопросов. Чтобы эффективно организовывать эти процессы, со стороны Ecommpay используются и постоянно развиваются как общие, так и специализированные решения. - [Общий порядок подключения](ru_platform_registration_workflow.md)— индивидуализированный подход, в рамках которого специалисты Ecommpay активно взаимодействуют с представителями мерчанта для оперативного решения всех вопросов и подбора оптимальных решений. Используется для среднего и крупного бизнеса, удовлетворяющего общим требованиям Ecommpay к компаниям-клиентам. - [Ecommpay for Small Businesses](ru_platform_onboarding_for_small_businesses.md)— автоматизированная регистрация для малого бизнеса в Великобритании — частично автоматизированный подход, включающий в себя самостоятельную регистрацию мерчантов и последующее решение технических вопросов без выделения курирующего менеджера со стороны Ecommpay. Используется для малого бизнеса, базирующегося в Великобритании и удовлетворяющего профильным требованиям Ecommpay к компаниям-клиентам такого класса. - **[Общий порядок подключения](ru_platform_registration_workflow.md)** статья об общем порядке подключения к платформе, который применяется для среднего и крупного бизнеса, удовлетворяющего общим требованиям Ecommpay к компаниям-клиентам - **[Автоматизированная регистрация для малого бизнеса в Великобритании](ru_platform_onboarding_for_small_businesses.md)** статья о частном порядке подключения к платформе, который применяется для малого бизнеса, базирующегося в Великобритании и удовлетворяющего профильным требованиям Ecommpay к компаниям-клиентам такого класса **На уровень выше:**[Платформа](ru_platform_about.md) --- # Общий порядок подключения {#ru_platform_registration_workflow} статья об общем порядке подключения к платформе, который применяется для среднего и крупного бизнеса, удовлетворяющего общим требованиям Ecommpay к компаниям-клиентам В зависимости от того, какие инструменты планируется использовать для работы с платформой, состав и порядок выполнения подготовительных технических работ могутсущественно отличаться. В общем случае для этого необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если организация ещё не является клиентом Ecommpay и у неё нет идентификаторов проектов и секретных ключей для взаимодействия с платёжной платформой — отправить [заявку на подключение](https://ecommpay.com/apply-now/)и получить начальное одобрение этой заявки и контактные данные специалистов Ecommpay, курирующих подключение. 2. Если планируется проводить платежи с использованием карт платёжных систем Visa или Mastercard — предоставить курирующему менеджеру Ecommpay документы о соответствии [требованиям PCI DSS](ru_faq_integration.md#fig_fgk_rgs_4nb): - Для всех мерчантов — отчёт о результатах [ASV-сканирования](ru_glossary.md). Такие сканирования должны выполняться авторизованными поставщиками \(PCI SSC Approved Scanning Vendor, ASV\) ежеквартально, а также после каждого значительного изменения сетевой инфраструктуры.Мерчанты Ecommpay могут выбирать таких поставщиков самостоятельно и, если это актуально, могут задействовать поставщика, являющегося партнёром Ecommpay. Чтобы организовать сканирования через партнёра Ecommpay, можно обращаться к курирующему менеджеру. - Для мерчантов с количеством операций более 6 миллионов в год \(уровня 1\) — аттестат соответствия \(Attestation of Compliance, AOC\). - Для мерчантов с количеством операций до 6 миллионов в год \(уровней 2, 3 и 4\) — [опросный лист](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment) \(Self-Assessment Questionnaire, SAQ\). С вопросами о правилах заполнения опросных листов можно обращаться к курирующему менеджеру Ecommpay. 3. Если необходима техническая интеграция — согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования и запуска в работу.В рамках согласования порядка тестирования могут быть согласованы возможности проведения тестовых платежей с использованием платёжных карт, а также некоторых из альтернативных платёжных методов. 2. Выполнить подготовительные технические работы, самостоятельно или с использованием специализированных компонентов, предоставляемых Ecommpay, если это актуально; в том числе обеспечить подписывание данных и корректное реагирование на оповещения на стороне серверной части веб-сервиса. 3. Совместно со специалистами технической поддержки Ecommpay протестировать выполнение целевых действий и запустить решение по взаимодействию веб-сервиса с платёжной платформой в работу. После тестирования и мониторинга, когда подтверждается корректность выполнения целевых действий на рабочем трафике, специалисты технической поддержки переводят работу с веб-сервисом в режим штатной поддержки. Нюансы, актуальные для отдельных инструментов, как правило, представлены в разделах с информацией об этих инструментах. Кроме того, за уточнениями всегда можно обращаться к специалистам Ecommpay. **На уровень выше:**[Подключение](ru_platform_registration.md) --- # Автоматизированная регистрация для малого бизнеса в Великобритании {#ru_platform_onboarding_for_small_businesses} статья о частном порядке подключения к платформе, который применяется для малого бизнеса, базирующегося в Великобритании и удовлетворяющего профильным требованиям Ecommpay к компаниям-клиентам такого класса **На уровень выше:**[Подключение](ru_platform_registration.md) ## Введение {#ru_platform_onboarding_for_small_businesses_overview} Подключение к любой платёжной платформе требует решения большого числа организационных, юридических и технических вопросов. Чтобы облегчить этот процесс, в рамках платёжной платформы Ecommpay используются различные специализированные решения, в том числе решениеEcommpay for Small Businesses — для заключения договоров с представителями малого бизнеса, работающими на территории Великобритании и ранее не сотрудничавшими с Ecommpay в качестве мерчантов. Ecommpay for Small Businesses позволяет проходить все этапы по оформлению взаимоотношений, включая предоставление полного набора требуемых сведений, их проверку и подписание договора, в автоматизированном режиме через интерфейс Dashboard, без необходимости прямого взаимодействия со специалистами Ecommpay.Подключение через Ecommpay for Small Businesses доступно тем клиентам, бизнес которых не является достаточно крупным для типового обслуживания с вовлечением клиентских менеджеров и других специалистов, при этом такой способ позволяет малому бизнесу получить спектр ключевых платёжных методов и функциональных возможностей платёжной платформы Ecommpay для полноценной работы и развития своих платёжных сервисов. Для оформления взаимоотношений с Ecommpay через Ecommpay for Small Businesses организациям необходимо соответствовать следующим критериям. |Страна регистрации|Великобритания| |Вид деятельности|в рамках одобренного Ecommpay перечня отраслей с низким уровнем риска| |Количество сотрудников|не более 10\(по числу специалистов\)| |Годовой оборот|не более £ 1,5 млн| |Срок деятельности|не менее 12 месяцев с момента регистрации организации в реестре Companies House| - Advertising - Camera and Photographic Supply Stores - Children Clothes - Department Stores - Digital Entertainment - Electronic Stores - Family Clothes - Furniture and other made-to-order goods - Groceries - Gym memberships - Hobby, Toy, and Game Shops - Home Furnishings - Home Supply - Household Utilities - Job listings - Men Clothes - Online Education and Training - Pet Shops, Pet Foods and Supplies Stores - Product Subscriptions - Professional Digital Services - Reviews and Recommendations - Shipping, Delivery and Logistics - Space Hire \(Hall, Meeting Room, Office, etc\) - Sporting Goods - Sports and Riding Apparel Stores - Takeaways and Restaurants - Telecommunications - Warehouse Stores - Wholesalers - Women Clothes **Прим.:** Актуальный перечень доступен на основном сайте Ecommpay, в форме заполнения [заявки на подключение](https://ecommpay.com/payments-for-small-businesses/), и может отличаться от представленного здесь в ознакомительных целях. Для решения вопросов, которые могут возникать на любом из этапов регистрации Ecommpay for Small Businesses, можно обращаться к настоящей документации и к ИИ-ассистенту, встроенному в интерфейс Dashboard. В случаях, когда помощи этого ассистента оказывается недостаточно, можно дополнительно обращаться к специалистам Ecommpay по адресу [help@ecommpay.com](mailto:help@ecommpay.com), который выделен для решения вопросов, связанных с регистрацией Ecommpay for Small Businesses. ## Порядок подключения {#ru_platform_onboarding_for_small_businesses_workflow} При использовании регистрации Ecommpay for Small Businesses важно учитывать, что в рамках этого процесса автоматизировано решение организационных и юридических вопросов по оформлению взаимоотношений, в то время как решение технических вопросов, касающихся подключения веб-сервиса мерчанта к платёжной платформе Ecommpay, остаётся за мерчантом. Общий порядок действий со стороны мерчанта в рамкахтакого процесса можно представить следующим образом: 1. Подать заявку на подключение на сайте Ecommpay. Для этого следует убедиться, что организация соответствует предъявляемым требованиям, отправить [заявку](https://ecommpay.com/payments-for-small-businesses/) через основной сайт Ecommpay и получить приглашение для прохождения регистрации через интерфейс Dashboard \(подробнее [далее](ru_platform_onboarding_for_small_businesses.md)\). 2. Предоставить и подтвердить информацию об организациичерез интерфейс Dashboard. Для этого следует предоставить запрашиваемые сведения об организации, её ключевых лицах и банковском счёте для взаиморасчётов \([подробнее](ru_platform_onboarding_for_small_businesses.md)\), а также подтверждающие документы \([подробнее](ru_platform_onboarding_for_small_businesses.md)\). 3. Оформить взаимоотношения с Ecommpayчерез интерфейс Dashboard. Для этого следует ознакомиться с условиями представленного со стороны Ecommpay договора и подписать его через интерфейс Dashboard, подтвердив тем самым его юридическую силу \(подробнее [далее](ru_platform_onboarding_for_small_businesses.md)\). 4. Решить вопросы по технической интеграции с платформой. После подписания договора можно переходить к технической интеграции. Для клиентов, подключающихся через Ecommpay for Small Businesses, доступна ключевая функциональность платформы, и со стороны мерчанта можно настраивать и использовать актуальные возможности \(подробнее [далее](ru_platform_onboarding_for_small_businesses.md)\). ## Подача заявки {#ru_platform_onboarding_for_small_businesses_application} Заполнение и отправка заявки на подключение — первый этап в рамках регистрации Ecommpay for Small Businesses. На этом этапе важно учитывать, что решение по заявке принимается в автоматическом режиме и в случае отклонения заявки Ecommpay оставляет за собой право не пересматривать автоматически принятое решение. Для одобрения заявки важно соответствовать [предъявляемым требованиям](ru_platform_onboarding_for_small_businesses.md) и корректно указать всю необходимую информацию.Также можно иметь в виду, что при одобрении заявки указанные в ней сведения в дальнейшем могут быть уточнены и скорректированы в рамках работы с интерфейсом Dashboard. Чтобы подать заявку на подключение организации к платёжной платформе Ecommpay через Ecommpay for Small Businesses, следует: 1. Открыть форму для заполнения заявки, перейдя [по ссылке](https://ecommpay.com/payments-for-small-businesses/) и щёлкнув кнопку **Get started**. 2. Указать запрашиваемые сведения об организации. Для этого необходимо заполнить следующие поля: - **First name** — имя физического лица, заполняющего анкету от лица организации\(в соответствии с тем, как указано в документе, удостоверяющем личность\). - **Last name** — фамилия физического лица, заполняющего анкету от лица организации\(в соответствии с тем, как указано в документе, удостоверяющем личность\). - **Business email** — адрес электронной почты для связи с организацией и регистрации учётной записи Dashboard. - **Mobile number** — номер телефона для связи с организацией\(в международном формате\). - **Company registration number** — идентификационный номер организации в Регистрационной палате Великобритании\(в виде последовательности из восьми символов, в соответствии с тем, как указано в Сертификате о регистрации, Certificate of Incorporation from Companies House\). - **Company name** — наименование организации\(в соответствии с тем, как указано в Сертификате о регистрации\). - **Company website** — адрес официального сайта организации\(в виде URL, при этом адреса сторонних ресурсов не принимаются, даже если эти ресурсы являются партнёрскими\). - **Business segment** — вид деятельности организации в соответствии с перечнем допустимых видов от Ecommpay\(среди этих видов можно выбрать наиболее релевантный\). **Прим.:** Если хотя бы одно из этих полей не может быть заполнено \(в том числе вид деятельности, соотносящийся с одним из допустимых\), можно оставить [заявку на подключение](https://ecommpay.com/apply-now/) на общих основаниях. 3. Проверить корректность указанных сведений и отправить заявку с помощью кнопки **Register your interest** в левом нижнем углу формы. 4. Убедиться, что заявка отправлена. Об этом должно свидетельствовать перенаправление на страницу с подтверждающим сообщением \(`Thank you`\). 5. Получить информацию о результате рассмотрения заявки. Как правило, рассмотрение заявки выполняется автоматически и занимает не более минуты, однако при возникновении вопросов и необходимости подключения специалистов этот процесс может занимать до трёх рабочих дней. По итогам рассмотрения на указанный адрес электронной почты отправляется соответствующее письмо — с приглашением пройти регистрацию через интерфейс Dashboard или уведомлением об отклонении заявки. При возникновении вопросов, касающихся поданной заявки, можно обращаться к специалистам Ecommpay по адресу [help@ecommpay.com](mailto:help@ecommpay.com). ![](images/ecommpay/onboarding/onboarding_application.svg "Форма заявки на подключение") ## Предоставление информации {#ru_platform_onboarding_for_small_businesses_registering} ### Общий порядок {#section_js2_fjb_1jc .section} В рамках второго этапа регистрации Ecommpay for Small Businesses необходимо предоставить Ecommpay достаточный набор сведений для анализа возможностей сотрудничества и решения организационных вопросов. Эти сведения разбиты на три группы, которые касаются регистрируемой организации, её ключевых лиц и банковского счёта для взаиморасчётов с Ecommpay. По каждой из этих групп необходимо последовательно предоставить запрашиваемую информацию и получить подтверждение её соответствия предъявляемым требованиям. После этого, когда весь набор необходимых сведений предоставлен и предварительно проверен, необходимо подтвердить предоставленную информацию соответствующими документами\(такими, как сертификат о регистрации и налоговые уведомления, присылаемые Службой доходов и таможни Его Величества — HM Revenue and Customs, HMRC\). Для избегания разночтений при проверке подтверждающих документов важно обеспечить соответствие указываемых сведений официальным документам организации. ### Учёт сведений об организации {#ru_platform_onboarding_for_small_businesses_company} Первая группа сведений, запрашиваемых для регистрации, касается общей информации об организации. Часть этих сведений заполняется автоматически, на основе исходной заявки на подключение, при этом такие предварительно заполненные сведения доступны для редактирования. Также стоит учитывать, что для указанных сведений об организации не поддерживается промежуточное сохранение в качестве черновика — всю актуальную информацию необходимо предоставить в рамках одного сеанса работы с интерфейсом Dashboard. Официальные документы, которым должны соответствовать предоставленные сведения об организации, относятся к документам, подтверждающим [состав акционеров](ru_platform_onboarding_for_small_businesses.md#section_tp1_zxy_t3c) и [адрес организации](ru_platform_onboarding_for_small_businesses.md#section_kmw_lyy_t3c). Желательно сверяться с этими документами при указании информации в интерфейсе. Для учёта на стороне Ecommpay сведений об организации следует: 1. Открыть вкладку добавления информации об организации. Для этого необходимо открыть стартовую страницу интерфейса Dashboard и щёлкнуть кнопку **Add company info** на навигационной панели регистрации. 2. Указать сведения об организации, дополнив и при необходимости отредактировав сведения, перенесённые из исходной заявки на подключение. Для этого следует заполнить актуальные поля: - **Company legal name** — наименование организации\(в соответствии с тем, как указано в Сертификате о регистрации; заполняется автоматически на основе исходной заявки и доступно для редактирования\). - **Website URL** — адрес официального сайта организации\(в виде URL, при этом адреса сторонних ресурсов не принимаются, даже если эти ресурсы являются партнёрскими; заполняется автоматически на основе исходной заявки и доступен для редактирования\). - **Business industry segment** — вид деятельности организации в соответствии с перечнем допустимых видов от Ecommpay\(среди этих видов можно выбрать наиболее релевантный; заполняется автоматически на основе исходной заявки и доступен для редактирования\). - **Business phone number** — номер телефона для связи с организацией\(в международном формате; заполняется автоматически на основе исходной заявки и доступен для редактирования\). - **Registration Number** — идентификационный номер организации в Регистрационной палате Великобритании\(в виде последовательности из восьми символов, в соответствии с тем, как указано в Сертификате о регистрации, Certificate of Incorporation from Companies House; заполняется автоматически на основе исходной заявки и доступен для редактирования\). - **TAX ID \(if applicable\)** — налоговый идентификатор организации\(*Corporation Unique Taxpayer Reference*\) из 10 или 13 цифр в соответствии с корреспонденцией HMRC или сведениями из учётной записи Business Tax Account в HMRC. - **Number of employees in the company** — количество сотрудников, трудоустроенных в организации на дату заполнения формы\(с допустимыми значениями не более чем в 10 сотрудников\). - **Building number** — номер здания в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Street** — наименование улицы в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Unit / Floor / Office \(optional\)** — номер строения, этажа или офиса в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Country** — наименование страны в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; должно быть выбрано из списка\). - **City** — наименование города в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; должно быть выбрано из списка, доступного после выбора страны\). - **Postal code** — почтовый индекс в юридическом адресе организации\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом\). 3. Проверить корректность указанных сведений и отправить их на первичную проверку со стороны Ecommpay. Для этого можно сопоставить указанную информацию с официальными документами организации, после чего следует щёлкнуть кнопку **Continue** в правом нижнем углу вкладки, подтвердить действие в открывшемся модальном окне с помощью кнопки **Submit** и убедиться в перенаправлении к странице с уведомлением об отправке информации на рассмотрение. 4. Убедиться в получении информации о результате проверки на стороне Ecommpay. Как правило, такая проверка занимает около получаса. При одобрении дальнейшей регистрации становится доступной возможность перейти к предоставлению информации о ключевых лицах организации, а при отклонении — отображается информация об отказе в продолжении регистрации через интерфейс Dashboard. Также в отдельных случаях со стороны Ecommpay может быть инициирован перевод на базовый процесс подключения, с консультациями специалистов. ![](images/ecommpay/onboarding/onboarding_company_main.svg "Открытие вкладки") ![](images/ecommpay/onboarding/onboarding_company_fields.svg "Указание сведений") ![](images/ecommpay/onboarding/onboarding_company_success.svg "Уведомление о проверке информации") ![](images/ecommpay/onboarding/onboarding_company_decline.svg "Уведомление об отказе") ![](images/ecommpay/onboarding/onboarding_stakeholders_main.svg "Обновление панели регистрации") ### Учёт сведений о ключевых лицах {#ru_platform_onboarding_for_small_businesses_stakeholders} Вторая группа сведений, запрашиваемых для регистрации, касается информации о ключевых лицах организации, к которым относятся: - `Ultimate beneficial owner` — каждый из собственников с долей владения более 25 %. - `Director` — действующий директор. - `Signatory` — уполномоченное лицо с правом подписания договоров. - `Contact person` — контактное лицо, выполняющее регистрацию и доступное для коммуникации с организацией. В качестве таких ключевых лиц может выступать как один человек, так и группа людей — в соответствии со спецификой организации. При этом для контактного лица достаточно указать имя, фамилию и должность, в то время как для остальных требуется более широкий набор сведений, включая персональную информацию, сведения об источниках доходов и адреса проживания \(без необходимости повторения этих сведений, когда в качестве разных ключевых лиц выступает один человек\). Также стоит учитывать, что для указанных сведений о ключевых лицах поддерживаетсяпромежуточное сохранение в качестве черновика с помощью кнопки **Save a draft**\(с возможностью последующего возвращения к черновику через стартовую страницу интерфейса Dashboard\). Официальные документы, которым должны соответствовать предоставленные сведения о ключевых лицах организации, относятся к документам, подтверждающим [состав акционеров](ru_platform_onboarding_for_small_businesses.md#section_tp1_zxy_t3c), [личности представителей](ru_platform_onboarding_for_small_businesses.md#section_h41_cyy_t3c) и [адреса проживания](ru_platform_onboarding_for_small_businesses.md#section_mfc_fyy_t3c). Желательно сверяться с этими документами при указании информации в интерфейсе. Для учёта на стороне Ecommpay сведений о ключевых лицах организации следует: 1. Открыть вкладку добавления информации о ключевых лицах. Для этого необходимо открыть стартовую страницу интерфейса Dashboard и щёлкнуть кнопку **Add stakeholders** на навигационной панели регистрации. 2. Указать сведения обо всех ключевых лицах организации. При этом стоит учитывать, что для первого указываемого лица часть сведений заполняется автоматически на основе исходной заявки на подключениеи такие предварительно заполненные сведения можно скорректировать. Для последующих указываемых лиц предварительного заполнения информации не используется и все поля необходимо заполнять вручную. Для перехода к добавлению информации о каждом следующем лице необходимо использовать кнопку **Add person** в правом нижнем углу вкладки. Как правило, указание сведений о ключевых лицах начинается с контактного лица \(`Contact person`\), для которого достаточно указать имя, фамилию и должность. Для остальных лиц должна быть указана следующая информация: - **Role** — все роли, в которых выступает указанный человек \(из множества `Contact person`, `Director`, `Signatory` и `Ultimate beneficial owner`\). - **First name** — имя\(в соответствии с тем, как указано в документе, удостоверяющем личность\). - **Last name** — фамилия\(в соответствии с тем, как указано в документе, удостоверяющем личность\). - **Date of birth** — дата рождения\(в соответствии с тем, как указано в документе, удостоверяющем личность\). - **Mobile phone** — номер телефонадля связи \(в международном формате\). - **Email** — адрес электронной почтыдля связи. - **Share percentage** — доля акций организации\(в процентах, в соответствии с одним из подтверждающих документов\). - **Source of wealth** — источники благосостояния\(через указание подходящих вариантов\). - **Value of source of wealth** — уровень благосостояния\(через выбор подходящего диапазона с ориентировочными границами в долларах США\). - **Building number** — номер здания в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Street** — наименование улицы в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Unit / Floor / Office \(optional\)** — номер строения, этажа или квартиры в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; необязательное поле\). - **Country** — наименование страны в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; должно быть выбрано из списка\). - **City** — наименование города в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом; должно быть выбрано из списка, доступного после выбора страны\). - **Postal code** — почтовый индекс в адресе проживания\(в соответствии с налоговым уведомлением HMRC, договором аренды или иным подтверждающим документом\). 3. Проверить корректность указанных сведений и отправить их на первичную проверку со стороны Ecommpay. Для этого можно сопоставить указанную информацию с официальными документами организации и ключевых лиц, после чего следует щёлкнуть кнопку **Continue** в правом нижнем углу вкладки, подтвердить действие в открывшемся модальном окне с помощью кнопки **Submit** и убедиться в перенаправлении к странице с уведомлением об отправке информации на рассмотрение. 4. Убедиться в получении информации о результате проверки на стороне Ecommpay. Как правило, такая проверка занимает около получаса. При одобрении дальнейшей регистрации становится доступной возможность перейти к предоставлению информации о банковском счёте организации, а при отклонении — отображается информация об отказе в продолжении регистрации через интерфейс Dashboard. Также в отдельных случаях со стороны Ecommpay может быть инициирован перевод на базовый процесс подключения, с консультациями специалистов. ![](images/ecommpay/onboarding/onboarding_stakeholders_main.svg "Открытие вкладки") ![](images/ecommpay/onboarding/onboarding_stakeholders_contactperson.svg "Указаний сведений о контактном лице") ![](images/ecommpay/onboarding/onboarding_stakeholders_ubo.svg "Указаний сведений о собственнике") ![](images/ecommpay/onboarding/onboarding_stakeholders_success.svg "Уведомление о проверке информации") ![](images/ecommpay/onboarding/onboarding_company_decline.svg "Уведомление об отказе") ![](images/ecommpay/onboarding/onboarding_bankaccount_main.svg "Обновление панели регистрации") ### Учёт сведений о банковском счёте {#ru_platform_onboarding_for_small_businesses_bank_accounts} Третья группа сведений, запрашиваемых для регистрации, касается информации о банковском счёте организации для взаиморасчётов с Ecommpay. При этом, как правило, достаточно указать только SWIFT-код банка и номер счёта — наименование банка и страна регистрации определяются автоматически. Важно учитывать, что на этом этапе допускается указание только одного счёта, моно- или мультивалютного, и информация об этом счёте используется для проверки благонадёжности организации.Дополнительные счета можно добавлять в дальнейшем, после завершения регистрации. Также стоит иметь в виду, что для указанных сведений о счёте не поддерживается промежуточное сохранение в качестве черновика — всю актуальную информацию необходимо предоставить в рамках одного сеанса работы с интерфейсом Dashboard. Официальные документы, которым должны соответствовать предоставленные сведения о банковском счёте организации, относятся к документам, подтверждающим [оборот](ru_platform_onboarding_for_small_businesses.md#section_kf3_ryy_t3c).Желательно сверяться с этими документами при указании информации в интерфейсе. Для учёта на стороне Ecommpay сведений о банковском счёте организации следует: 1. Открыть вкладку добавления информации о счёте. Для этого необходимо открыть стартовую страницу интерфейса Dashboard и щёлкнуть кнопку **Connect bank account** на навигационной панели регистрации. 2. Указать сведения о банковском счёте. Для этого должны быть указаны следующие сведения: - **Is this a multicurrency account?** — индикатор поддержки на стороне банка мультивалютных операций для регистрируемого счёта\(`Yes`, `No`\). - **Account Number / IBAN** — номер счёта\(International Bank Account Number\). - **Account Currency** — валюта счёта\(указывается, если счёт моновалютный\). - **BIC/SWIFT** — международный идентификационный код банка, в котором открыт счёт \(БИК или SWIFT; при заполнении этого поля можно использовать варианты из выпадающего списка, которые становятся доступными при указании по крайней мере трёх символов\). - **Name of the financial institution** — наименование банка, в котором открыт счёт \(в соответствии с указанным кодом банка; без возможности редактирования\). - **Registration country of the financial institution** — наименование страны, в которой зарегистрирован банк\(в соответствии с указанным кодом банка; без возможности редактирования\). 3. Проверить корректность указанных сведений и отправить их для учёта на стороне Ecommpay. Для этого можно сопоставить указанную информацию с официальными документами организации, после чего следует щёлкнуть кнопку **Continue** в правом нижнем углу вкладки, подтвердить действие в открывшемся модальном окне с помощью кнопки **Submit** и убедиться в перенаправлении к странице для предоставления подтверждающих документов. ![](images/ecommpay/onboarding/onboarding_bankaccount_main.svg "Открытие вкладки") ![](images/ecommpay/onboarding/onboarding_bankaccount_fields.svg "Регистрация моновалютного счёта") ![](images/ecommpay/onboarding/onboarding_documents_shareholders.svg "Переход к подтверждению информации") ## Подтверждение информации {#ru_platform_onboarding_for_small_businesses_documents} ### Общий порядок {#section_gmy_mpv_s3c .section} После предоставления всех запрашиваемых сведений необходимо подтвердить их подлинность и актуальность соответствующими документами, состав которых описан далее в рамках этого раздела. **Прим.:** Непредоставление отдельных документов допускается только с указанием причин и может приводить к расширению числа запрашиваемых документов, дополнительным проверкам и увеличению общего времени регистрации. Общий порядок работ на этой стадии выглядит следующим образом: 1. Подготовить все актуальные документы для загрузки в электронном виде. Для этого следует проверить наличие документов по каждой из описанных в этом разделе категорий и подготовить для каждого актуального документа файл, соответствующий следующим базовым требованиям: - Тип документа — электронный оригинал или цифровая копия печатного оригинала\(в виде его сканированного изображения с обеспечением однозначной интерпретации всех текстовых символов\). - Язык документа — английский\(в качестве единственного или одного из параллельно используемых\). - Дата оригинального документа — в рамках допустимых сроков, указанных отдельно для каждой категории документов\(как правило, с давностью не более 12 месяцев\). - Формат файла — PDF, PNG или JPG.Другие форматы, в том числе форматы файловых архивов, не поддерживаются. - Размер файла — не более 25 МБ. 2. Открыть в интерфейсе Dashboard вкладку добавления документов. Для этого необходимо открыть стартовую страницу интерфейса Dashboard и щёлкнуть кнопку **Document upload** на навигационной панели регистрации. 3. Загрузить документы и указать актуальную информацию. Для этого следует последовательно прикрепить документы или заполнить сведения по каждой запрашиваемой категории — по составу акционеров, личностям и адресам проживания представителей организации, описанию деятельности организации, адресу её регистрации и финансовой отчётности. При этом для документов каждой категории следует проверить автоматически распознанную информацию и, если актуально, внести корректировки или дополнить сведения, после чего подтвердить корректность заполнения и перейти к следующей категории с помощью кнопки **Next**. В случаях, когда отсутствует возможность предоставить какой-либо документ,может быть допустимым пропустить его загрузку, щёлкнув кнопку **I don't have a document** и указавв открывшемся текстовом поле пояснение в свободной форме— об отсутствии, повреждении или иной причине. **Внимание:** Стоит учитывать, что при загрузке документов не предусмотрено возвращение к предыдущим страницам, даже в случаях со случайным пропуском форм и преждевременными переходами дальше без загрузки каких-либо документов. 4. Убедиться в отправке документов на рассмотрение на стороне Ecommpay. Об этом должно свидетельствовать перенаправление на страницу с подтверждающим сообщением \(`Thank you`\). 5. Убедиться в получении информации о результате рассмотрения документов на стороне Ecommpay. Как правило, такое рассмотрение занимает не более пяти минут. При одобрении дальнейшей регистрации становится доступной возможность перейти к подписанию договора, а при отклонении — отображается информация об отказе в продолжении регистрации через интерфейс Dashboard. Также в отдельных случаях со стороны Ecommpay может быть инициирован перевод на базовый процесс подключения, с консультациями специалистов. ![](images/ecommpay/onboarding/onboarding_documents_main.svg "Открытие вкладки") ![](images/ecommpay/onboarding/onboarding_documents_shareholders.svg "Загрузка информации об акционерах") ![](images/ecommpay/onboarding/onboarding_documents_businessnature.svg "Описание вида деятельности организации") ![](images/ecommpay/onboarding/onboarding_agreement_main.svg "Обновление панели регистрации") ### Подтверждение состава акционеров {#section_tp1_zxy_t3c .section} Для подтверждения информации об акционерах организации может использоваться любой из следующих документов, включающих в себя актуальный список всех акционеров с указанием их долей владениями акциями: - Выписка из Регистрационной палаты Великобритании \(Company Register Extract with shareholders\). - Учредительный договор \(Memorandum of Association with shareholders\). - Сертификат о полномочиях и должностных лицах \(Certificate of Incumbency\). - Свидетельство индивидуального предпринимателя \(Certificate of Sole Entrepreneurship\). ### Подтверждение представителей {#section_h41_cyy_t3c .section} Для подтверждения информации о каждом из ключевых лиц организации могут использоваться любые официальные документылюбой страны, включающие в себя основные идентификационные сведения \(имя, фамилию, дату рождения\), фотографию и срок действия документа. При этом для разных лиц могут использоваться документы разных типов, такие как: - Паспорт Великобритании или международный паспорт любой страны. - Внутреннее водительское удостоверение Великобритании \(UK Driving License\) или международное водительское удостоверение, выданное в любой стране \(International Driving License\). - Citizen Card или Biometric Residence Permit Великобритании либо Национальная идентификационная карта \(National ID Card\) любой европейской страны. ### Подтверждение адресов проживания {#section_mfc_fyy_t3c .section} Для подтверждения адреса проживания каждого из ключевых лиц, для которого на этапе предоставления информации была указана по крайней мере одна из ролей `Ultimate beneficial owner`, `Director` и `Signatory`, может использоваться любой официальный документ, включающий в себя имя, фамилию и адрес проживания этого человека, а также срок действия документа. При этом для разных лиц могут использоваться документы разных типов, такие как: - Налоговое уведомление HMRC \(не старше 3 месяцев и за исключением форм P45 и P60, которые не принимаются для подтверждения\). - Счёт на оплату налога на имущество от местного органа власти \(не старше 3 месяцев\). - Счёт на оплату коммунальных услуг \(не старше 3 месяцев\). - Банковская выписка по карте или по счёту за последние 6 или 12 месяцев \(не старше 3 месяцев\). - Договор аренды \(без ограничения по сроку давности\). ### Описание деятельности {#section_txt_hyy_t3c .section} Для подтверждения вида деятельности организации и соответствия этой деятельности низкому уровню риска принимаются ответы на ряд вопросов.Число таких вопросов может варьироваться, при этом к ним, как правило, относятся вопросы следующего характера: - Чем занимается организация, какие виды продуктов и услуг она предлагает клиентам и через какие каналы обеспечивает поставки? - Какие конкретные продукты и услуги предоставляет организация и кто является целевыми клиентами? - Как организация находит своих клиентов и какие методы использует для этого? - Через какие сайты организация предлагает свои услуги или продукты? Ответ на каждый вопрос должен представляться в форме простого текста. Форматирование текста и вставка иллюстраций в полях для предоставления ответов не поддерживаются.Также при указании разных сайтов адрес каждого из них следует начинать с новой строки. ### Подтверждение адреса регистрации {#section_kmw_lyy_t3c .section} Для подтверждения адреса регистрации организации может использоваться любой из следующих официальных документов, включающих в себя наименование и адрес организации, а также срок действия документа: - Налоговое уведомление HMRC \(не старше 3 месяцев и за исключением форм P45 и P60, которые не принимаются для подтверждения\). - Счёт на оплату налога на имущество от местного органа власти \(не старше 3 месяцев\). - Счёт на оплату коммунальных услуг \(не старше 3 месяцев\). - Банковская выписка по карте или по счёту за последние 6 или 12 месяцев \(не старше 3 месяцев\). - Договор аренды \(без ограничения по сроку давности\). ### Подтверждение оборота {#section_kf3_ryy_t3c .section} Для подтверждения информации об обороте организации могут использоваться актуальные документы с финансовой отчётностью или результатами аудиторских проверок. ## Подписание договора {#ru_platform_onboarding_for_small_businesses_agreement} В рамках заключительного этапа регистрации Ecommpay for Small Businesses необходимо оформить взаимоотношения с Ecommpay, ознакомившись с текстом договора и подписав его в интерфейсе Dashboard. Договор имеет юридическую силу и вступает в действие с момента подтверждения обеими сторонами. Чтобы подписать договор, следует: 1. Открыть вкладку подписания. Для этого необходимо открыть стартовую страницу интерфейса Dashboard и щёлкнуть кнопку **Agreement signing** на навигационной панели регистрации. 2. Ознакомиться с документами для подписания. Для этого следует изучить текст договора и политики безопасности Ecommpay, представленных для ознакомления и подписания в интерфейсе Dashboard. 3. Выбрать ключевое лицо с правом подписи и подтвердить подписание документа. Для этого необходимо выбрать представителя с ролью `Signatory` из выпадающего списка **Selected authorized signatory**, установить флажок согласия с приведёнными положениями, щёлкнуть кнопку **Continue** и подтвердить действие в открывшемся модальном окне. 4. Убедиться в подтверждении регистрации. Как правило, это занимает не более пяти минут. При подтверждении оформления взаимоотношений с Ecommpay в интерфейсе Dashboard отображается соответствующее уведомление — о завершении регистрации и переходе к технической настройке. В случаях со сбоями и ошибками на этом шаге можно обновить используемую страницу, очистить кеш используемого браузера и повторно открыть интерфейс Dashboard. При возникновении сложностей и вопросов можно обращаться к специалистам Ecommpay по адресу [help@ecommpay.com](mailto:help@ecommpay.com). ![](images/ecommpay/onboarding/onboarding_agreement_main.svg "Открытие вкладки") ![](images/ecommpay/onboarding/onboarding_agreement_signing.svg "Подписание договора") ![](images/ecommpay/onboarding/onboarding_agreement_success.svg "Уведомление о завершении регистрации") После подписания договора можно переходить к технической интеграции с платформой и к последующему запуску рабочего трафика. ## Техническая интеграция {#ru_platform_onboarding_for_small_businesses_integration} После подписания договора можно переходить к технической интеграции с платёжной платформой Ecommpay.Для мерчантов, подключающихся через Ecommpay for Small Businesses,при этом доступна ключевая функциональность платформыс различными вариантами приёма платежей. В рамках таких вариантов можно выбирать и настраивать: - Интерфейсы для проведения платежей, в качестве которых могут использоваться: - основная редакция платёжной формы Payment Page, которая может быть встроена в любой веб-сервис \([подробнее](ru_pp_quickstart.md)\); - плагины для веб-сервисов на базе CMS Magento \([подробнее](ru_CMS__magento.md)\) и Wordpress \([подробнее](ru_CMS__wordpress.md)\); - платёжные ссылки,которые можно формировать и отправлять пользователям через интерфейс Dashboard \([подробнее](ru_dbl_payments.md)\); - веб-приложение от Ecommpay для интеграции с платформой Xero \([подробнее](ru_xero_invoices.md)\). - Платёжные методы, среди которых доступны наиболее востребованные среди пользователей методы с глобальным покрытием: - [классические карточные платежи](ru_pm_card_payments.md); - [Apple Pay](pm_applepay.md); - [Google Pay](pm_googlepay.md). - Основные возможности, для которых автоматически поддерживаются все необходимые вспомогательные процедуры, такие как аутентификация 3‑D Secure или проверка адреса пользователя: - разовые оплаты в одну и две стадии\(выполняемые с учётом специфики используемых платёжных интерфейсов\); - возвраты средств по проведённым оплатам через интерфейс Dashboard \([подробнее](ru_dbl_payments.md)\). - Дополнительные возможности по работе с платёжной формой Payment Page, доступные по умолчанию, включая возможности настройки оформления \([подробнее](ru_PP__design_customisation.md)\) и управления языком при вызове формы \([подробнее](ru_PP_WigetLanguages.md)\). - Интерфейс для контроля проведения платежей [Dashboard](ru_dbl_about.md) и инструменты финансового учёта в платформе [Xero](ru_xero.md). Для решения вопросов, касающихся технической интеграции, можно обращаться к соответствующим разделам документации, к ИИ-ассистенту и к специалистам технической поддержки \(используя для первичных обращенийадрес [help@ecommpay.com](mailto:help@ecommpay.com)\), однако следует учитывать, что при регистрации Ecommpay for Small Businesses мерчантам не назначаются курирующие менеджеры со стороны Ecommpay и при отсылках по каким-либо вопросам к курирующему менеджеру следует обходиться доступными каналами коммуникации. --- # Проведение платежей {#ru_platform_payment_model} статьи о типах платежей, которые можно проводить через платформу, схемах их проведения и допустимых операциях и статусах Платёжная платформа Ecommpay позволяет проводить различные платежис использованием разных платёжных методов: с применением платёжных карти других платёжных инструментов. При этом все платежи, независимо от методов, разделяются на несколько базовых типов. - Разовая оплата, [в одну](ru_platform_sms_model.md) или [в две стадии](ru_platform_dms_model.md) — `purchase`. - Повторяемая оплата [со списаниями по запросу](ru_platform_recurring_model.md) или [с автоматическими списаниями](ru_platform_sheduled_recurring_model.md) — `recurring`. - [Оплата по платёжной ссылке](ru_platform_invoice_model.md), в одну или в две стадии — `invoice`. - [Выплата](ru_platform_payout_model.md) — `payout`. - [Проверка действительности платёжного инструмента](ru_platform_account_verification_model.md) — `account verification`. В рамках этого подраздела представленыстатьи, которые касаются общей модели проведения платежей, а также модели проведения отдельных типов платежей. - **[Модель проведения платежей](ru_platform_payment_model_overview.md)** статья с информацией об общей модели инициирования и проведения платежей через платформу - **[Разовая оплата в одну стадию](ru_platform_sms_model.md)** статья о порядке проведения разовых оплат с незамедлительным списанием средств \(в одну стадию\), с описанием схемы, допустимых операций и статусов - **[Разовая оплата в две стадии](ru_platform_dms_model.md)** статья о порядке проведения разовых оплат с предварительной блокировкой и последующим списанием средств \(в две стадии\), с описанием схемы, допустимых операций и статусов - **[Повторяемая оплата со списаниями по запросам](ru_platform_recurring_model.md)** статья о порядке проведения повторяемых оплат со списаниями средств по запросам мерчанта \(без фиксированного расписания\), с описанием схемы, допустимых операций и статусов - **[Повторяемая оплата с автоматическими списаниями](ru_platform_sheduled_recurring_model.md)** статья о порядке проведения повторяемых оплат с автоматическими списаниями средств \(по заданному расписанию\), с описанием схемы, допустимых операций и статусов - **[Оплата по платёжной ссылке](ru_platform_invoice_model.md)** статья о порядке проведения оплат по платёжным ссылкам, с описанием схемы, допустимых операций и статусов - **[Выплата](ru_platform_payout_model.md)** статья о порядке проведения выплат, с описанием схемы, допустимых операций и статусов - **[Проверка действительности платёжного инструмента](ru_platform_account_verification_model.md)** статья о порядке проверки действительности платёжных инструментов \(без фактического списания средств\), с описанием схемы, допустимых операций и статусов **На уровень выше:**[Платформа](ru_platform_about.md) --- # Модель проведения платежей {#ru_platform_payment_model_overview} статья с информацией об общей модели инициирования и проведения платежей через платформу Работа платёжной платформы строится на проведении *платежей*. Платежом в рамках платформы считается комплекс действий по выполнению заявки мерчанта на перевод денежных средств между ним и пользователем.Это может быть перевод средств от пользователя к мерчанту \(и тогда платёж относится к *оплате*\) либо от мерчанта к пользователю \(и тогда платёж относится к *выплате*\). Возвраты средств по проведённым оплатам рассматриваются в рамках оплат и не выделяются в отдельный тип платежей. Вместе с тем к платежам относится *проверка* действительности платёжного инструмента, в рамках которой может выполняться условный \(нулевой\) перевод денежных средствили реальная \(ненулевая\) блокировка средств с последующей отменой. Каждый платёж должен быть инициирован со стороны мерчанта. Это может быть сделано через один из программных интерфейсов платёжной платформы \(Gate API или Payment Page API\) с помощью *запроса*или через пользовательский интерфейс \(Dashboard\) с помощью соответствующего *действия*, равносильного запросу.. При получении корректного запроса в платформе создаётся объект `payment` и инициируется выполнение соответствующей *операции*, которая может быть единственной или первой из нескольких. ![](images/payment%20model/ru_gate_payment_model_1.svg) Как правило, каждая последующая операция инициируется отдельным запросом со стороны мерчанта, однако в некоторых случаях операции могут быть инициированы автоматически на стороне платёжной платформы. К таким случаям относится, например, автоматические списания средств в соответствии с переданными в платёжную платформу сведениями \(при проведении регулярных оплат\). Общая информация о проведении платежей через платёжную платформу Ecommpay представлена в разделе [Проведение платежей](ru_platform_payment_model.md), а техническая информация — в разделах с информацией об интерфейсах платформы. **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Разовая оплатав одну стадию {#ru_platform_sms_model} статья о порядке проведения разовых оплат с незамедлительным списанием средств \(в одну стадию\), с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Разовая оплата в одну стадию*, или *разовая одностадийная оплата*, — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один \(разовый\) перевод денежных средств от пользователя к мерчанту. Это базовый вариант для проведения оплат — с незамедлительным разовым списанием средств \(например, для расчёта за совершённую покупку\). ## Схема проведения {#section_ajd_brr_whb .section} Чтобы инициировать оплату в одну стадию, следуетотправить в платформу запрос категории `sale` либо открыть платёжную форму в режиме работы Purchase с указанием типа операции `sale`. Для выполнения такого запроса в платформе формируется операция `sale`, результатом выполнения которой является списание средств со счёта пользователя. При проведении оплаты в одну стадию может потребоваться выполнить следующие вспомогательные процедуры: - *Аутентификация пользователя с использованием протокола 3‑D Secure*.При работе через Gate для выполнения такой аутентификации со стороны веб-сервиса требуется принять соответствующее оповещение и выполнить необходимые действия, а при работе через Payment Page все необходимые для этого действия выполняются без участия веб-сервиса. - *Аутентификация пользователя со стороны платёжной системы по инициативе мерчанта*. При работе через Gate для выполнения такой аутентификации со стороны веб-сервиса требуется принять соответствующее оповещение и выполнить необходимые действия, а при работе через Payment Page все необходимые для этого действия выполняются без участия веб-сервиса. - *Дополнение информации о платеже* для какой-либо из сторон, участвующих в проведении платежа.При работе через Gate для дополнения информации со стороны веб-сервиса требуется принять соответствующее оповещение и отправить запрос с недостающей информацией, а при работе через Payment Page все необходимые для этого действия выполняются без участия веб-сервиса. Если для использованного платёжного метода поддерживается возможность получать информацию о зачислении средств получателю, то после выполнения операции `sale` в платформе формируется операция `payment confirmation`, результатом выполнения которой является получение такого подтверждения со стороны провайдера. Если для использованного платёжного метода поддерживается проведение возвратов, то после проведения разовой оплаты в одну стадию по этой оплате можно выполнить *возврат средств* пользователю. Это можно сделать с помощью [запроса](ru_Gate_Refund.md) через Gate либо соответствующего [действия](ru_dbl_payments.md) в карточке целевой оплаты интерфейса Dashboard. Для выполнения возврата после карточной оплаты в зависимости от того, когда, на какую сумму и для какого платёжного инструмента инициируется возврат, формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия [операционного дня](ru_glossary.md), вне зависимости от суммы оплаты для карт платёжной системы Mastercard и при условии возврата всей суммы оплаты для карт других платёжных систем; - `refund`, если возврат инициируется для карт любых платёжных систем после закрытия [операционного дня](ru_glossary.md) и вне зависимости от суммы, а также до закрытия операционного дня при условии возврата части суммы оплаты для карт всех платёжных систем, кроме Mastercard. Для выполнения возврата после оплаты с использованием альтернативного платёжного метода, как правило, формируется операция `refund`. Операция `reversal` может инициироваться в тех случаях, когда оплате после подтверждения со стороны платёжной системы или провайдера присвоен статус `success`, но зачислить средства получателю по каким-либо причинам невозможно. ![](images/payment%20model/ru_gate_payment_model_2.svg "Диаграмма состояний разовой одностадийной оплаты") Далее в рамках данного раздела представлена информация о возможных статусах разовой одностадийной оплаты и связанных с ней операций. Более подробную информацию о проведении разовой одностадийной оплатыс прямымиспользованием платёжных карт можно найти в разделах[Payment Page](ru_PP_about.md) и [Gate](ru_Gate_Integration_About.md), а об оплатес применением других платёжных инструментов — в разделе [Платёжные методы](ru_pm_about.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении разовой одностадийной оплаты могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting 3ds result`|Проведение платежа приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то платёж переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting merchant auth`|Проведение платежа приостановлено до завершения аутентификации пользователя в платёжной системе по инициативе мерчанта|*Промежуточное состояние*| |`awaiting redirect result`|Проведение платежа приостановлено до получения уведомления с результатом со стороны платёжной системы. В зависимости от результата на стороне платёжной системы платёж переводится в статус `success` или `decline`. В рамках проведения одного платежа может использоваться `awaiting redirect result` либо `awaiting customer action`, но не оба этих статуса |*Промежуточное состояние*| |`awaiting customer action`|Проведение платежа приостановлено до выполнения необходимых действий пользователем со стороны платёжной системы \(в соответствии со спецификой платёжного метода\). В зависимости от результата этих действий платёж переводится в статус `success` или статус `decline`. В рамках проведения одного платежа может использоваться `awaiting customer action` либо `awaiting redirect result`, но не оба этих статуса |*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`awaiting confirmation`|Проведение платежа приостановлено до получения со стороны платёжной системы или провайдера уведомления о зачислении средств получателю|*Промежуточное состояние*| |`awaiting customer`|Проведение платежа приостановлено до получения результата повторных попыток со стороны пользователя. При успешной повторной попытке платёж переводится в статус `success`, а при истечении числа безуспешных попыток — в статус `decline` \(подробнее — в разделе [Повторные попытки проведения платежей](ru_PP_Try_Again.md)\)|*Промежуточное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние. Дополнительно допускается проведение возврата*| |`partially reversed`|Сумма платежа частично возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние*| |`reversed`|Сумма платежа полностью возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние. Дополнительно допускается отмена возврата*| |`partially refunded`|Сумма платежа частично возвращена|*Конечное состояние. Дополнительно допускается отмена возврата*| |`refunded`|Сумма платежа полностью возвращена после закрытия операционного дня, в котором он был проведён. Осуществлён один полный возврат суммы платежа или несколько частичных, в совокупности составляющих исходную сумму|*Конечное состояние. Дополнительно допускается отмена возврата*| ## Статусы операции sale {#section_h3k_crr_whb .section} При выполнении операции `sale` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting 3ds result`|Выполнение операции приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то операция переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting merchant auth`|Выполнение операции приостановлено до завершения аутентификации пользователя в платёжной системе по инициативе мерчанта|*Промежуточное состояние*| |`awaiting redirect result`|Выполнение операции приостановлено до получения уведомления с результатом от платёжной системы. В зависимости от результата операция переводится в статус `success` или статус `decline`|*Промежуточное состояние*| |`awaiting customer action`|Выполнение операции приостановлено до выполнения необходимых действий пользователем со стороны платёжной системы \(в соответствии со спецификой платёжного метода\). В зависимости от результата этих действий операция переводится в статус `success` или статус `decline`|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции payment confirmation {#section_ddd .section} При выполнении операции `payment confirmation` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций reversal и refund {#section_zfx_crr_whb .section} При выполнении операций `reversal` и `refund` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Разовая оплата в две стадии {#ru_platform_dms_model} статья о порядке проведения разовых оплат с предварительной блокировкой и последующим списанием средств \(в две стадии\), с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Разовая оплата в две стадии*, или *разовая двухстадийная оплата*, — это тип платежа, в рамках которого для перевода денежных средств от пользователя к мерчанту сначала, на основании исходного запроса, осуществляется предварительная блокировка, а затем, на основании подтверждающего запроса или по истечении заданного периода, — списание. Этот вариант может быть актуален, когда необходимо гарантировать возможность последующего списания или отмены блокировки суммы в зависимости от ситуации \(например, при бронировании номера в отеле\). ## Схема проведения {#section_ajd_brr_whb .section} Чтобы инициировать *первую стадию* оплаты, следуетотправить в платформу запрос категории `auth` либо открыть платёжную форму в режиме работы `purchase` с указанием типа операции `auth`. Для выполнения такого запроса в платформе формируется операция `auth`, результатом выполнения которой является предварительная блокировка средств на счёте пользователя. При проведении *первой стадии* дополнительно могут требоваться и другие запросы: - Если необходима *аутентификация пользователя с использованием протокола 3‑D Secure*, то от платформы к веб-сервису отправляется оповещение с информацией для формирования запроса к эмитенту, после чего проведение платежа в платформе приостанавливается до получения информации о результате аутентификации.При работе через Gate для этого требуется отправить запрос с результатом аутентификации — `3ds_result`, — а при работе через Payment Page все действия выполняются без участия веб-сервиса мерчанта. - Если необходима *аутентификация пользователя со стороны платёжной системы по инициативе мерчанта*, то в платформу поступает уведомление от платёжной системы, после чего от платформы к веб-сервису отправляется оповещение с информацией о необходимости проведения аутентификации и проведение платежа в платформе приостанавливается. При работе через Gate для продолжения требуется отправить два запроса `merchant_auth` — `start` после получения согласия пользователя и `finish` после ввода пользователем проверочного кода, — а при работе через Payment Page все действия выполняются без участия веб-сервиса мерчанта. - Если необходимо *дополнение информации о платеже* для какой-либо из сторон, участвующих в проведении платежа \(например, предоставление в платёжную систему адреса держателя карты, не переданного в исходном запросе\), то от платформы к веб-сервису отправляется оповещение с названиями параметров для уточнения и проведение платежа в платформе приостанавливается до получения необходимой информации.При работе через Gate для этого требуется отправить запрос с такой информацией — `clarification`, — а при работе через Payment Page все действия выполняются без участия веб-сервиса. Сумму средств, заблокированную в результате выполнения этой стадии, можно изменить как до выполнения второй стадии, так и одновременно с её выполнением. Для увеличения суммы до инициирования второй стадии оплаты следует отправить запрос `incremental`, а для уменьшения — запрос `cancel`. *Вторая стадия* такой оплаты может быть инициирована по запросу со стороны веб-сервиса мерчанта, через действие в интерфейсе Dashboard или автоматически через заданный период на стороне платёжной платформы. Чтобы инициировать *вторую стадию* двухстадийной оплаты, следует отправить в платформу один из следующих запросов: - запрос `capture`, в процессе обработки которого формируется одноимённая операция и выполняется списание заблокированных средств; - запрос `cancel`, в процессе обработки которого формируется одноимённая операция и выполняется отмена блокировки средств. При этом в запросе `capture` можно указать сумму списания, отличную от суммы предварительно заблокированных средств. Подробную информацию об автоматическом инициировании второй стадии необходимо уточнять у курирующего менеджера. Если для использованного платёжного метода поддерживается проведение возвратов, то после выполнения второй стадии разовой двухстадийной оплаты по этой оплате можно выполнить *возврат средств* пользователю. Чтобы инициировать возврат, следует отправить в платформу запрос категории `refund` либо выбрать соответствующее действие в панели информации о платеже интерфейса Dashboard. Для выполнения возврата послекарточной оплаты в зависимости от того, когда, на какую сумму и для какого платёжного инструмента инициируется возврат, формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия [операционного дня](ru_glossary.md), вне зависимости от суммы оплаты для карт платёжной системы Mastercard и при условии возврата всей суммы оплаты для карт других платёжных систем; - `refund`, если возврат инициируется для карт любых платёжных систем после закрытия [операционного дня](ru_glossary.md) и вне зависимости от суммы, а также до закрытия операционного дня при условии возврата части суммы оплаты для карт всех платёжных систем, кроме Mastercard. ![](images/payment%20model/ru_gate_payment_model_3.svg) Далее в рамках данного раздела представлена информация о возможных статусах разовой двухстадийной оплаты и связанных с ней операций. Более подробную информацию о проведении разовой двухстадийной оплатыс прямым использованием платёжных карт можно найти вразделах [Payment Page](ru_PP_about.md)и [Gate](ru_Gate_Integration_About.md), а о проведении оплатс применением других платёжных инструментов — в разделе [Платёжные методы](ru_pm_about.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении разовой двухстадийной оплаты могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting 3ds result`|Проведение платежа приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то платёж переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting merchant auth`|Проведение платежа приостановлено до завершения аутентификации пользователя в платёжной системе по инициативе мерчанта|*Промежуточное состояние*| |`awaiting redirect result`|Проведение платежа приостановлено до получения уведомления с результатом со стороны платёжной системы. В зависимости от результата на стороне платёжной системы платёж переводится в статус `success` или `decline`|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`awaiting customer`|Проведение платежа приостановлено до получения результата повторных попыток со стороны пользователя. При успешной повторной попытке платёж переводится в статус `success`, а при истечении числа безуспешных попыток — в статус `decline` \(подробнее — в разделе [Повторные попытки проведения платежей](ru_PP_Try_Again.md)\)|*Промежуточное состояние*| |`awaiting capture`|Проведение платежа приостановлено до получения запроса на списание \(`capture`\) или на отмену предварительной блокировки средств \(`cancel`\)|*Промежуточное состояние*| |`canceled`|Предварительная блокировка средств, выполненная по запросу `auth`, отменена|*Конечное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние. Дополнительно допускается проведение возврата*| |`partially reversed`|Сумма платежа частично возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние*| |`reversed`|Сумма платежа полностью возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние. Дополнительно допускается отмена возврата*| |`partially refunded`|Сумма платежа частично возвращена|*Конечное состояние. Дополнительно допускается отмена возврата*| |`refunded`|Сумма платежа полностью возвращена после закрытия операционного дня, в котором он был проведён. Осуществлён один полный возврат суммы платежа или несколько частичных, в совокупности составляющих исходную сумму|*Конечное состояние. Дополнительно допускается отмена возврата*| ## Статусы операции auth {#section_h3k_crr_whb .section} При выполнении операции `auth` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting 3ds result`|Выполнение операции приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то операция переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting merchant auth`|Выполнение операции приостановлено до завершения аутентификации пользователя в платёжной системе по инициативе мерчанта|*Промежуточное состояние*| |`awaiting redirect result`|Выполнение операции приостановлено до получения уведомления с результатом от платёжной системы. В зависимости от результата операция переводится в статус `success` или статус `decline`|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции incremental {#section_kly_zw4_nnb .section} При выполнении операции `incremental` могут использоваться следующие статусы. |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций capture и cancel {#section_wxn_gsr_whb .section} При выполнении `capture` и `cancel` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций reversal и refund {#section_zfx_crr_whb .section} Статусы операций `reversal` и `refund` совпадают со статусами операций `capture` и `cancel`. **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Повторяемая оплата со списаниями по запросам {#ru_platform_recurring_model} статья о порядке проведения повторяемых оплат со списаниями средств по запросам мерчанта \(без фиксированного расписания\), с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Повторяемая оплата со списаниями по запросам* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один \(повторяемый\) перевод денежных средств от пользователя к мерчанту с использованием сохранённых платёжных данных и без подтверждения подлинности платёжного инструмента пользователя \(такого, как ввод кода проверки подлинности карты\). Этот вариант может быть актуален, когда в рамках обслуживания пользователя необходимо неоднократно проводить оплаты с использованием одного и того же платёжного инструмента без привязки к графику или сумме платежа \(например, при предоставлении услуг такси\). Для пользователя такие оплаты могут быть удобны тем, что с его стороны нет необходимости каждый раз вводить одни и те же платёжные данные и подтверждать подлинность платёжного инструмента. В платёжной платформе поддерживаются следующие категории повторяемых оплат со списаниями по запросам: - *Экспресс-оплаты*. Списания в рамках таких оплат инициируются пользователем и выполняются без привязки к расписанию или сумме платежа. Например, пользователь онлайн-кинотеатра может оплатить прокат одного или нескольких фильмов с использованием сохранённых данных карты. - *Автооплаты*. Списания в рамках таких оплат инициируются мерчантом и выполняются нерегулярно или на различные суммы. Например, когда остаток средств на счёте пользователя становится ниже заданного, выполняется списание средств с его карты для пополнения счёта. При использовании Gate можнорегистрировать и проводить любые повторяемые оплаты, а при использовании Payment Page доступна регистрация любых повторяемых оплат и проведение *экспресс-оплат* \(OneClick\)при использовании некоторых платёжных методов. ## Схема проведения {#section_ajd_brr_whb .section} До проведения повторяемой оплаты её требуется предварительно *зарегистрировать*, то есть провести первоначальный платёж — разовую оплату или проверку действительности платёжного инструмента — с сохранением в платформе платёжных данных пользователя и с указанием типа повторяемой оплаты.Набор параметров, которые требуется передать для последующего проведения повторяемой оплаты, может отличаться в зависимости от используемого платёжного метода. При использовании Gate для инициирования повторяемой оплаты следует отправить в платформуодин из следующих запросов: `recurring`или, в некоторых случаях, `sale`. Для выполнения таких запросов в платформе формируется операция `recurring`или `sale` соответственно, и результатом выполнения такой операции является списание средств пользователя без подтверждения подлинности платёжного инструмента. При использовании Payment Page для инициирования повторяемой оплаты в параметрах открытия платёжной формы следует указать режим работы `purchase` и дополнительные параметры, необходимые для проведения повторяемой оплаты с использованием конкретного платёжного метода, например идентификатор пользователя. После открытия платёжной формы пользователю необходимо выбрать для проведения оплаты тот платёжный инструмент, для которого зарегистрирована повторяемая оплата, и подтвердить своё согласие на проведение платежа. Подтверждать подлинность платёжного инструмента при этом не требуется. При получении согласия пользователя на проведение платежа в платёжную платформу направляется запрос, для выполнения которого в платформе формируется операция `sale`. Результатом выполнения такой операции является списание средств пользователя без подтверждения подлинности платёжного инструмента. Для проведения повторяемой оплаты со списаниями по запросам в редких случаях может требоваться отправка дополнительного запроса, если необходимо *дополнение информации о платеже* для какой-либо из сторон, участвующих в проведении платежа \(например, предоставление в платёжную систему адреса держателя карты, не переданного в исходном запросе\). При использовании Gate в таких случаях от платформы к веб-сервису отправляется оповещение с названиями параметров для уточнения и проведение платежа в платформе приостанавливается до получения от веб-сервиса запроса с необходимой информацией — `clarification`, — а при использовании Payment Page все действия выполняются без участия веб-сервиса мерчанта. Если для использованного платёжного метода поддерживается проведение возвратов, то после проведения повторяемой оплаты по этой оплате можно выполнить *возврат средств* пользователю. Чтобы инициировать возврат, следует отправить в платформу запрос категории `refund` либо выбрать соответствующее действие в панели информации о платеже интерфейса Dashboard. Для выполнения возврата после карточнойоплаты в зависимости от того, когда, на какую сумму и для какого платёжного инструмента инициируется возврат, формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия [операционного дня](ru_glossary.md), вне зависимости от суммы оплаты для карт платёжной системы Mastercard и при условии возврата всей суммы оплаты для карт других платёжных систем; - `refund`, если возврат инициируется для карт любых платёжных систем после закрытия [операционного дня](ru_glossary.md) и вне зависимости от суммы, а также до закрытия операционного дня при условии возврата части суммы оплаты для карт всех платёжных систем, кроме Mastercard. ![](images/payment%20model/ru_gate_payment_model_4.svg) Далее в рамках данного раздела представлена информация о возможных статусах повторяемой оплаты со списаниями по запросам и связанных с ней операций. Более подробную информацию о проведении повторяемых оплат можно найти в разделах [Payment Page](ru_PP_about.md) и [Gate](ru_Gate_Integration_About.md), а о проведении оплат с применением других платёжных инструментов — в разделе [Платёжные методы](ru_pm_about.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении повторяемой оплаты со списаниями по запросам могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние. Дополнительно допускается проведение возврата*| |`reversed`|Сумма платежа полностью возвращена до закрытия бизнес-дня, в котором он был проведён|*Конечное состояние. Дополнительно допускается отмена возврата*| |`partially refunded`|Сумма платежа частично возвращена|*Конечное состояние. Дополнительно допускается отмена возврата*| |`refunded`|Сумма платежа полностью возвращена после закрытия операционного дня, в котором он был проведён. Осуществлён один полный возврат суммы платежа или несколько частичных, в совокупности составляющих исходную сумму|*Конечное состояние. Дополнительно допускается отмена возврата*| ## Статусы операции recurring {#section_h3k_crr_whb .section} При выполнении операции `recurring` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций reversal и refund {#section_zfx_crr_whb .section} Статусы операций `reversal` и `refund` совпадают со статусами операции `recurring`. **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Повторяемая оплата с автоматическими списаниями {#ru_platform_sheduled_recurring_model} статья о порядке проведения повторяемых оплат с автоматическими списаниями средств \(по заданному расписанию\), с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Повторяемая оплата с автоматическими списаниями* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется серия переводов денежных средств от пользователя к мерчанту с использованием сохранённых платёжных данных и без подтверждения подлинности платёжного инструмента пользователя \(такого, как ввод кода проверки подлинности карты\). К таким оплатам относятся *регулярные оплаты*. Этот вариант может быть актуален, когда в рамках обслуживания пользователя необходимо проводить оплаты с использованием одного и того же платёжного инструмента с привязкой к графику и к сумме платежа \(например, при «подписке» на сервис с периодической оплатой\). При использовании повторяемых оплат с автоматическими списаниями у пользователя и мерчанта может быть уверенность в своевременном проведении серии оплат без участия с их стороны. ## Схема проведения {#section_ajd_brr_whb .section} До проведения повторяемой оплаты её требуется предварительно *зарегистрировать*, то есть провести первоначальный платёж — разовую оплату или проверку действительности платёжного инструмента — с сохранением в платформе платёжных данных пользователя и с указанием типа повторяемой оплаты.Набор параметров, которые требуется передать для последующего проведения повторяемой оплаты, может отличаться в зависимости от используемого платёжного метода. Зарегистрированную повторяемую оплату с автоматическими списаниями — при условии, что при её регистрации были переданы необходимые параметры — инициировать не нужно: все списания инициируются автоматически на стороне платёжной платформы. Для выполнения каждого списания используется отдельная операция `recurring`. При необходимости можно выполнить *обновление условий* проведения повторяемой оплаты или её *отмену*. Для обновления условий следует через Gate отправить в платёжную платформу запрос категории `update`, а для отмены — запрос категории `cancel`. Для выполнения этих запросов могут использоваться операции `recurring_update` и `recurring_cancel` соответственно. Для проведения повторяемой оплаты с автоматическими списаниями в редких случаях может требоваться отправка дополнительного запроса, если необходимо *дополнение информации о платеже* для какой-либо из сторон, участвующих в проведении платежа \(например, предоставление в платёжную систему адреса держателя карты, не переданного в исходном запросе\). При использовании Gate в таких случаях от платформы к веб-сервису отправляется оповещение с названиями параметров для уточнения и проведение платежа в платформе приостанавливается до получения от веб-сервиса запроса с необходимой информацией — `clarification`. Если для использованного платёжного метода поддерживается проведение возвратов, то после проведения первого списания можно выполнить *возврат средств* пользователю. Сумма возвращаемых средств не должна превышать сумму фактически проведённых списаний. Чтобы инициировать возврат, следует отправить в платформу запрос категории `refund` либо выбрать соответствующее действие в панели информации о платеже интерфейса Dashboard. Для выполнения такого запроса в платформе используется операция `refund`. ![](images/payment%20model/ru_gate_payment_model_5.svg) Далее в рамках данного раздела представлена информация о возможных статусах повторяемой оплаты с автоматическими списаниями и связанных с ней операций. Более подробную информацию о проведении повторяемых оплат можно найти в разделе [Gate](ru_Gate_Integration_About.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении повторяемой оплаты с автоматическими списаниями могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`processing`|Выполняется очередное списание в рамках платежа|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`sсheduled recurring processing`|Ожидаются дальнейшие списания средств пользователя в рамках платежа|*Промежуточное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён: все списания в рамках платежа выполнены|*Конечное состояние. Дополнительно допускается проведение возврата*| |`partially refunded`|Сумма платежа частично возвращена, при этом все списания в рамках платежа выполнены|*Конечное состояние. Дополнительно допускается отмена возврата*| |`refunded`|Сумма платежа полностью возвращена, при этом все списания в рамках платежа выполнены|*Конечное состояние. Дополнительно допускается отмена возврата*| ## Статусы операций recurring {#section_pf5_crw_tjb .section} При выполнении операции `recurring` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции recurring\_update и recurring\_cancel {#section_h3k_crr_whb .section} При выполнении операций `recurring_update` и `recurring_cancel` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции refund {#section_xk5_fns_g3b .section} Статусы операции `refund` совпадают со статусами операции `recurring`. **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Оплата по платёжной ссылке {#ru_platform_invoice_model} статья о порядке проведения оплат по платёжным ссылкам, с описанием схемы, допустимых операций и статусов ## Общая информация {#section_ltv_433_tkb .section} *Оплата по платёжной ссылке* — это тип платежа, в рамках которого на основании одного исходного запроса сначала создаётся и отправляется пользователю платёжная ссылка, а затем, при переходе по этой ссылке и подтверждении платежа, выполняется переводили серия переводов денежных средств от пользователя к мерчанту.Как правило, оплаты по ссылкам используются для разовых расчётов, с предварительной блокировкой средств или без таковой. Вместе с тем, когда это актуально, при проведении оплат по ссылкам можно регистрировать [повторяемые оплаты](ru_Gate__payments_on_saved_data.md), а в рамках работы с отдельными платёжными методами можно использовать платёжные ссылки только для получения согласия пользователей на регистрацию повторяемых оплат, без фактических списаний. Этот вариант может быть актуален, когда необходимо предоставлять пользователям возможность оплаты заказов без привязки к определённым месту и времени. Платёжные ссылки можно отправлять любым удобным способом: средствами Ecommpay на электронную почту пользователя или самостоятельно другими способами, например в социальных сетях. ## Схема проведения {#section_dy1_z33_tkb .section} Сформировать платёжную ссылку можно с помощью запроса `invoice/create` к Gate API или через интерфейс Dashboard. Для выполнения такого запроса формируется операция `invoice`, в результате которой платёжная ссылка: - формируется в платформе; - предоставляется инициатору; - отправляется пользователю, если это было задано. Сформированную ссылку можно получить на стороне мерчанта через программное оповещение и интерфейс Dashboard — с учётом того, через какой интерфейс было инициировано создание ссылки. В свою очередь, отправка ссылки пользователю автоматически выполняется через платформу, если указывается такая необходимость и целевой адрес электронной почты. В Gate API для этого служат параметры `send_email` и `email`, в интерфейсе Dashboard — флажок **Отправить e-mail покупателю** и поле **E-mail покупателя**.Если отправка ссылки пользователю средствами платформы Ecommpay не инициируется \(и подразумевается отправка средствами веб-сервиса\), операция `invoice` считается выполненной после предоставления ссылки инициатору. После формирования и отправки платёжной ссылки, но до того, как пользователь подтвердит проведение платежа, действие платёжной ссылки можно отменить. Для этого следует отправить в платёжную платформу запрос категории `invoice/cancel` или использовать переключатель **Деактивировать** в реестре платёжных ссылок интерфейса Dashboard. Пользователю после перехода по платёжной ссылке отображается платёжная форма Payment Page, в которой он указывает свои платёжные данные и подтверждает проведение оплаты. Далее, в зависимости от значения параметра `operation_type`, переданного в запросе, платёж проводится в соответствии с одним из следущих вариантов: - Проведение оплаты \([подробнее](ru_platform_sms_model.md)\), с регистрацией повторяемой оплаты или без таковой. Для проведения этого варианта оплаты в платёжной платформе формируется операция `sale`, результатом выполнения которой является списание средств со счёта пользователя. - Блокировка средств \([подробнее](ru_platform_dms_model.md)\), с регистрацией повторяемой оплаты или без таковой. Для выполнения блокировки в платёжной платформе формируется операция `auth`, результатом выполнения которой является предварительная блокировка средств пользователя. Списание заблокированных средств или отмена их блокировки могут быть инициированыодним из следующих способов: - со стороны веб-сервиса мерчанта по запросу, - со стороны сотрудников мерчанта через интерфейс Dashboard, - со стороны платёжной платформы автоматически через заданный период. - Регистрация повторяемой оплаты. В рамках этого варианта регистрация повторяемой оплаты выполняется без фактического списания или блокировки средств пользователя. Для этого в платёжной платформе формируется операция `contract registration`, результатом выполнения которой является зарегистрированная повторяемая оплата. В процессе проведения платежа могут выполняться одна или несколько [вспомогательных процедур](ru_gate_procedures.md), однако дополнительных действий со стороны веб-сервиса при этом не требуется — все действия выполняются на стороне Payment Page. После проведения платежа можно выполнить *возврат средств* пользователю, если для использованного платёжного методаи варианта проведения этого платежа поддерживается проведение возвратов. Чтобы инициировать возврат, следует отправить в платформу запрос категории `refund` либо выбрать соответствующее действие в панели информации о платеже интерфейса Dashboard. Для выполнения возвратапосле карточной оплаты в зависимости от того, когда, на какую сумму и для какого платёжного инструмента инициируется возврат, формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия [операционного дня](ru_glossary.md), вне зависимости от суммы оплаты для карт платёжной системы Mastercard и при условии возврата всей суммы оплаты для карт других платёжных систем; - `refund`, если возврат инициируется для карт любых платёжных систем после закрытия [операционного дня](ru_glossary.md) и вне зависимости от суммы, а также до закрытия операционного дня при условии возврата части суммы оплаты для карт всех платёжных систем, кроме Mastercard. ![](images/payment%20model/ru_gate_payment_model_invoice.svg "Диаграмма состояний оплаты по платёжной ссылке в две стадии") Далее в рамках данного раздела представлена информация о возможных статусах оплаты по платёжной ссылке и связанных с ней операций. Более подробную информацию о проведении оплаты по платёжной ссылке можно найтив разделах [Gate](ru_Gate_Integration_About.md) и [Dashboard](ru_dbl_about.md). ## Статусы платежа {#section_qbs_z33_tkb .section} При проведении оплаты по платёжной ссылке могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`awaiting payment`|Проведение платежа инициировано, ожидается отправка платёжной ссылки|*Промежуточное состояние*| |`expired`|Платёж не проведён из-за истечения срока действия платёжной ссылки|*Конечное состояние*| |`invoice canceled`|Проведение платёжа отменено по инициативе мерчанта|*Конечное состояние*| |`invoice sent`|Проведение платежа инициировано, платёжная ссылка отправлена|*Промежуточное состояние*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting 3ds result`|Проведение платежа приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то платёж переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting redirect result`|Проведение платежа приостановлено до получения со стороны платёжной системы уведомленияс информацией о результате или о выполнении пользователем необходимых действий. В зависимости от результата на стороне платёжной системы платёж переводится в статус `awaiting finalization`,`success` или `decline`|*Промежуточное состояние*| |`awaiting finalization`|Проведение платежа приостановлено до получения со стороны платёжной системы уведомления с информацией о результате. В этом случае со стороны пользователя не требуется никаких дополнительных действий, и в зависимости от результата на стороне платёжной системы платёж переводится в статус `success` или `decline`|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`awaiting customer`|Проведение платежа приостановлено до получения результата повторных попыток со стороны пользователя. При успешной повторной попытке платёж переводится в статус `success`, а при истечении числа безуспешных попыток — в статус `decline` \(подробнее — в разделе [Повторные попытки проведения платежей](ru_PP_Try_Again.md)\)|*Промежуточное состояние*| |`awaiting capture`|Проведение платежа приостановлено до получения запроса на списание \(`capture`\) или на отмену предварительной блокировки средств \(`cancel`\)|*Промежуточное состояние*| |`canceled`|Предварительная блокировка средств, выполненная по запросу `auth`, отменена|*Конечное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние. Дополнительно допускается проведение возврата*| |`partially reversed`|Сумма платежа частично возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние*| |`reversed`|Сумма платежа полностью возвращена до закрытия операционного дня, в котором он был проведён|*Конечное состояние. Дополнительно допускается отмена возврата*| |`partially refunded`|Сумма платежа частично возвращена|*Конечное состояние. Дополнительно допускается отмена возврата*| |`refunded`|Сумма платежа полностью возвращена после закрытия операционного дня, в котором он был проведён. Осуществлён один полный возврат суммы платежа или несколько частичных, в совокупности составляющих исходную сумму|*Конечное состояние. Дополнительно допускается отмена возврата*| ## Статусы операции invoice {#section_vhh_1j3_tkb .section} При выполнении операции `invoice` могут использоваться следующие статусы. |`awaiting payment`|Платёжная ссылка сформирована и предоставлена инициатору. Если исходно инициирована отправка платёжной ссылки пользователю средствами платформы Ecommpay, то ожидается отправка электронного письма со ссылкой. Если отправка платёжной ссылки пользователю средствами платформы Ecommpay не инициирована \(и подразумевается отправка средствами веб-сервиса\), операция считается выполненной |*Промежуточное состояниепри отправке ссылки через платёжную платформу.* *Конечное состояние при отправке ссылки через веб-сервис мерчанта* | |`expired`|Операция выполнена, срок действия платёжной ссылки истёк|*Конечное состояние*| |`invoice canceled`|Операция отменена по инициативе мерчанта|*Конечное состояние*| |`invoice sent`|Операция выполнена, платёжная ссылка отправлена|*Конечное состояние*| ## Статусыопераций sale и auth {#section_oxc_cw3_tkb .section} При выполненииодной из операций, `sale` или `auth`, могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting 3ds result`|Выполнение операции приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то операция переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting redirect result`|Выполнение операции приостановлено до получения уведомления с результатом от платёжной системы. В зависимости от результата операция переводится в статус `success` или `decline`|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций capture и cancel {#section_gnf_fw3_tkb .section} При выполнении `capture` и `cancel` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции contract registration {#section_jcp_w5f_32c .section} |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`awaiting redirect result`|Выполнение операции приостановлено до получения уведомления от платёжной системы. В зависимости от результата операция переводится в статус `success` или `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операций reversal и refund {#section_mvr_hw3_tkb .section} Статусы операций `reversal` и `refund` совпадают со статусами операций `capture` и `cancel`. **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Выплата {#ru_platform_payout_model} статья о порядке проведения выплат, с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Выплата* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один перевод денежных средств от мерчанта к пользователю. В рамках платёжной платформы поддерживается один вариант для работы с выплатами через запросы \(разовые единичные выплаты\), но дополнительно обеспечивается возможность проведения массовых выплат через Dashboard \(с автоматическим формированием требуемого количества платежей; подробнее — в разделе [Контроль и проведение платежей](ru_dbl_payments.md)\). ## Схема проведения {#section_ajd_brr_whb .section} Чтобы инициировать выплату, следует отправить в платформу запрос категории `payout`, открыть платёжную форму в режиме работы Payout либо выбрать соответствующее действие в разделе **Выплаты** интерфейса Dashboard. Для выполнения такого запроса в платформе формируется операция `payout`, результатом выполнения которой является перечисление средств на счёт пользователя. Для проведения выплаты может требоваться отправка дополнительного запроса, если необходимо *уточнение информации* для какой-либо из сторон, участвующих в проведении платежа \(например, предоставление в платёжную систему адреса держателя карты, не переданного в исходном запросе\). В этом случае от платформы к веб-сервису отправляется оповещение с названиями параметров для уточнения и проведение платежа в платформе приостанавливается до получения от веб-сервиса запроса с необходимой информацией — `clarification`.В настоящее время эта процедура не используется для работы альтернативными платёжными методами. Если выплате после подтверждения со стороны платёжной системы или провайдера присвоен статус `success`, но зачислить средства пользователю по каким-либо причинам невозможно, то после получения уведомления об этом в платёжной платформе инициируется отмена выплаты. Это выполняется вручную специалистами технической поддержки Ecommpay или, при использовании некоторых платёжных методов, автоматически. Для выполнения такой отмены формируется операция `payout reversal`. ![](images/payment%20model/ru_gate_payment_model_14.svg "Диаграмма состояний выплаты через Payment Page") ![](images/payment%20model/ru_gate_payment_model_12.svg "Диаграмма состояний выплаты через Gate") Далее в рамках данного раздела представлена информация о возможных статусах выплаты и связанных с ней операций. Более подробную информацию о проведении выплатна счета, ассоциированные с платёжными картами, можно найти в разделах [Payment Page](ru_PP_about.md),[Gate](ru_Gate_Integration_About.md) и [Dashboard](ru_dbl_about.md), а о проведении выплат на альтернативные платёжные инструменты — в разделе [Платёжные методы](ru_pm_about.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении выплаты могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`awaiting payout completion`|Проведение платежа инициировано, ожидается подтверждение выплаты пользователем|*Промежуточное состояние*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние*| |`reversed`|Платёж отменён|*Конечное состояние*| ## Статусы операции payout {#section_h3k_crr_whb .section} При выполнении операции `payout` могут использоваться следующие статусы. |`awaiting payout completion`|Выполнение операции инициировано, ожидается подтверждение выплаты пользователем|*Промежуточное состояние*| |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| ## Статусы операции payout reversal {#section_czg_klb_wxb .section} При выполнении операции `payout reversal` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Проверка действительности платёжного инструмента {#ru_platform_account_verification_model} статья о порядке проверки действительности платёжных инструментов \(без фактического списания средств\), с описанием схемы, допустимых операций и статусов ## Общая информация {#section_zvh_1rr_whb .section} *Проверка действительности платёжного инструмента* — это тип платежа, в рамках которого для проверки возможности использования платёжного инструмента на основании одного исходного запроса осуществляется один условный \(нулевой\) перевод денежных средств от пользователя к мерчантуили одна реальная \(ненулевая\) блокировка средств пользователя с последующей отменой. При этом сумма блокировки может согласовываться с мерчантом, а срок отмены блокировки может составлять до 45 дней. Платежи этого типа могут быть актуальны, например, для регистрации повторяемых оплат. **Прим.:** Информацию о возможности проведения проверки действительности платёжного инструмента необходимо уточнять у курирующего менеджера Ecommpay. ## Схема проведения {#section_ajd_brr_whb .section} Чтобы инициировать проверку действительности платёжного инструмента, следуетотправить в платформу запрос `account verification` либо открыть платёжную форму в режиме работы `card_verify`. Для выполнения такого запроса в платформе формируется операция `account verification`. При проведении проверки платёжного инструмента дополнительно могут требоваться и другие запросы: - Если необходима *аутентификация пользователя с использованием протокола 3‑D Secure*, то от платформы к веб-сервису отправляется оповещение с информацией для формирования запроса к эмитенту, после чего проведение платежа в платформе приостанавливается до получения информации о результате аутентификации.При работе через Gate для этого требуется отправить запрос с результатом аутентификации — `3ds_result`, — а при работе через Payment Page все действия выполняются без участия веб-сервиса мерчанта. - Если необходимо *дополнение информации о платеже* для какой-либо из сторон, участвующих в проведении платежа \(например, предоставление в платёжную систему адреса держателя карты, не переданного в исходном запросе\), то от платформы к веб-сервису отправляется оповещение с названиями параметров для уточнения и проведение платежа в платформе приостанавливается до получения необходимой информации.При работе через Gate для этого требуется отправить запрос с такой информацией — `clarification`, — а при работе через Payment Page все действия выполняются без участия веб-сервиса. ![](images/payment%20model/ru_gate_payment_model_7.svg) Далее в рамках данного раздела представлена информация о возможных статусах проверки действительности платёжного инструмента и связанных с ней операций. Более подробную информацию о проведении проверки действительности платёжного инструмента можно найти вразделах [Payment Page](ru_PP_about.md)и [Gate](ru_Gate_Integration_About.md). ## Статусы платежа {#section_n4r_brr_whb .section} При проведении проверки действительности платёжного инструмента могут использоваться следующие статусы. |`error`|Проведение платежа не инициировано из-за ошибки, возникшей при проверке принятого запроса|*Конечное состояние. Допускается повторная отправка запроса с тем же идентификатором платежа и повторная попытка проведения этого платежа*| |`processing`|Платёж проводится|*Промежуточное состояние*| |`awaiting 3ds result`|Проведение платежа приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то платёж переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting clarification`|Проведение платежа приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, платёж переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Платёж отклонён|*Конечное состояние*| |`success`|Платёж проведён|*Конечное состояние*| ## Статусы операции account verification {#section_h3k_crr_whb .section} При выполнении операции `account verification` могут использоваться следующие статусы. |`processing`|Операция выполняется|*Промежуточное состояние*| |`awaiting 3ds result`|Выполнение операции приостановлено до получения информации о результате аутентификации 3‑D Secure. Если такая информация не получена в течение установленного времени, то операция переводится в статус `decline`. Как правило, время ожидания такой информации составляет 30 минут, но может варьироваться в зависимости от используемого провайдера. Для получения более подробной информации о времени ожидания следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com)|*Промежуточное состояние*| |`awaiting clarification`|Выполнение операции приостановлено до получения требуемой дополнительной информации. Если такая информация не получена в течение 30 минут, операция переводится в статус `decline`|*Промежуточное состояние*| |`decline`|Операция отклонена|*Конечное состояние*| |`success`|Операция выполнена|*Конечное состояние*| **На уровень выше:**[Проведение платежей](ru_platform_payment_model.md) --- # Работа с подписью к данным {#ru_platform_signature} статья о порядке создания и проверки подписи, используемой в программных запросах, ответах и оповещениях для обеспечения защищённого обмена данными при взаимодействии с платёжной платформой **На уровень выше:**[Платформа](ru_platform_about.md) ## Общая информация {#ru_platform_signature_overview} Для обеспечения защищённого обмена данными при работе с платёжной платформой Ecommpay используется криптографический протокол TLS \(Transport Layer Security; протокол защиты транспортного уровня\) версии не ниже 1.2, а для подтверждения авторства и целостности передаваемых данных дополнительно применяется цифровая подпись. Цифровая подпись формируется и проверяется по заданным алгоритмам с использованием одинакового секретного ключа, доступного на двух сторонах: мерчанта и Ecommpay. Независимо от интерфейса, используемого при работе с платформой, подпись обязательна к включению в состав всех программных запросов, отправляемых от веб-сервиса к платёжной платформе, а также всех оповещений и ряда ответов, отправляемых от платёжной платформы к веб-сервису. Поэтому перед отправкой любого запроса в платформу необходимо сформировать подпись и включить её в состав этого запроса, а при получении ответов и оповещений от платформы следует проверять целостность данных путём сличения расчётных подписей с полученными.Для этого можно использовать как собственные программные решения, так и SDK от Ecommpay \([подробнее](ru_sdk_overview.md)\). Алгоритмы подписывания данных и проверки их целостности, а также примеры выполнения этих алгоритмов и интерактивные формы для самостоятельной проверки корректной работы с подписью к разным данным при использовании программных интерфейсов Ecommpay, представлены далее. ## Подписывание данных {#ru_platform_signature_generation} ### Описание алгоритма {#section_imf_5kd_x4b .section} *В качестве входных данных* для подписывания выступают: 1. *Данные*, которые требуется подписать. Как правило, это заполненное тело запроса, все параметры запроса за исключением подписи или JavaScript-объект configObj с параметрами без включения параметра `signature`. 2. *Ключ*, используемый для подписывания. **Прим.:** Для работы с Data API должны использоваться ключи, получаемые через интерфейс Dashboard в связке с токенами. \(Подробнее в разделе [Порядок доступа к данным](ru_dbl_api_interaction.md).\) Для отладки и тестирования могут использоваться произвольные ключи, а для рабочих запросов в платформу — только актуальный секретный ключ. *В качестве выходных данных* подписывания в зависимости от реализации алгоритма могут выступать либо *подпись*, либо *подписанные данные* — как правило, это итоговый объект или итоговое тело запроса в формате JSON с параметром `signature`, включённым в его состав. Далее в описании, примерах и формах для тестирования представлен наиболее показательный вариант реализации алгоритма, актуальный при работе с интерфейсами Payment Page API, Gate API и Data API. *В состав алгоритма* в этом случае *включаются следующие шаги*: 1. *Проверка входных данных* на соблюдение заданных требований: 1. Структура данных для подписывания должна соответствовать формату JSON. При работе с Payment Page также можно использовать JavaScript-объекты. 2. В составе данных для подписывания не должен присутствовать параметр `signature` \(даже с пустым значением\). 3. Должен быть задан ключ. 2. *Приведение структуры проверяемых данных к требуемой глубине вложенности.* В зависимости от интерфейса платёжной платформы, к которому должен отправляться запрос, на этом шаге могут выполняться разные действия: - При работе через Payment Page отдельные параметры, представленные вложенными объектами, кодируются в строки с применением алгоритма Base64 или преобразования URL-encoding — в соответствии с требованиями, представленными в статье [Спецификация Payment Page API](ru_PP_Parameters.md). - При работе через Gate API ограничений по вложенности не применяется и действий по преобразованию или исключению данных не требуется. - При работе через Data API значения всех параметров, расположенных на четвёртом и более глубоких уровнях вложенности, заменяются пустыми строками. 3. *Преобразование данных в строку UTF-8 с сортировкой параметров в естественном порядке*. В рамках этого шага выполняются следующие действия: 1. Логические \(булевы\) значения кодируются следующим образом: `false` заменяется на `0`, а `true` — на `1`. Но это относится только к булевым значениям — в строковых параметрах, даже если они содержат значения `false` или `true`, замены на `0` или `1` не используются\(например, в параметре `recurring: "{type: \"U\",register: true}"` замена `true` на `1` не требуется\). 2. Каждый параметр преобразуется в строку, содержащую полный путь к параметру, название параметра и его значение: ``` <родительский_узел_1>:...:<родительский_узел_N>:<название_параметра>:<значение_параметра> ``` где *родительские узлы* — это названия объектов и \(или\) массивов, в состав которых включена пара «название параметра — значение параметра». Родительские узлы располагаются в порядке их вложения, начиная с самого верхнего уровня. В качестве разделителя при этом используется двоеточие \(:\), между парами «название параметра — значение параметра» удаляются запятые, а у строковых значений параметров удаляются обрамляющие кавычки. 3. Параметры с нулевыми, а также пустыми значениями остаются в строке, например запись `"payment_description":""` представляется в виде `payment_description:`. Замены пустых значений на пробелы или `null` не применяются. 4. Элементы массивов записываются отдельными строками, с указанием номера каждого элемента, начиная с нуля. Например, массив `["alpha", "beta", "gamma"]` представляется в виде трёх строк: `0:alpha`, `1:beta` и `2:gamma`. 5. Пустые массивы полностью игнорируются и не включаются в набор строк для создания подписи. 6. Кодировка всех строк приводится к формату UTF-8. 7. Полученные строки упорядочиваются в естественном порядке и объединяются в одну строку с использованием в качестве разделителя точки с запятой \(;\). 4. *Получение двоичного кода HMAC с использованием ключа и функции SHA-512.* На этом шаге для полученной строки с параметрами вычисляется HMAC \(Hash-based Message Authentication Code; код аутентификации сообщений с использованием хеш-функции\) с использованием функции хеширования SHA‑512 \(Secure Hash Algorithm; безопасный алгоритм хеширования\) и применяемого ключа. И этот HMAC представляется в виде необработанных двоичных данных. 5. *Кодирование двоичного кода HMAC с применением алгоритма Base64*. На этом шаге полученный двоичный код HMAC кодируется с использованием алгоритма Base64. Получаемая при этом строка является подписью к исходным данным. 6. *Добавление подписи к данным*. На этом шаге к исходным данным для подписывания добавляется параметр `signature` с полученной подписью в качестве его значения. ### Пример для запроса на оплату через Payment Page {#section_osk_5kd_x4b .section} Допустим, что надо подписать запрос на открытие Payment Page при следующих условиях: - Используемый ключ — `secret` - Предварительная версия объекта configObj, в котором еще нет значения параметра с подписью, выглядит так: ``` {#codeblock_azp_jjb_f1c} { "project_id": 12345, "payment_id": "X03936", "payment_amount": 2035, "payment_currency": "USD", "payment_description": "Guyliner purchase", "customer_first_name": "Jack", "customer_id": "user007", "customer_last_name": "Sparrow", "customer_phone": "02081234567", "close_on_missclick": true, **"signature": "<подпись, которую нужно создать\>" ** } ``` Задача заключается в том, чтобы вычислить подпись, то есть определить значение параметра `signature`. Для этого необходимо: 1. Убедиться, что в теле запроса нет параметра `signature`, даже с пустым значением. Если такой параметр есть, его нужно удалить: ``` {#codeblock_ljm_2x3_1fc} { "project_id": 12345, "payment_id": "X03936", "payment_amount": 2035, "payment_currency": "USD", "payment_description": "Guyliner purchase", "customer_first_name": "Jack", "customer_id": "user007", "customer_last_name": "Sparrow", "customer_phone": "02081234567", "close_on_missclick": true, **"signature": "<*подпись, которую нужно создать*\>" ** } ``` 2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ``` {#codeblock_e5n_d1b_f1c} project_id:12345 payment_id:X03936 payment_amount:2035 payment_currency:USD payment_description:Guyliner purchase customer_first_name:Jack customer_id:user007 customer_last_name:Sparrow customer_phone:02081234567 close_on_missclick:1 ``` 3. Отсортировать полученные строки в естественном порядке: ``` {#codeblock_zkw_d1b_f1c} close_on_missclick:1 customer_first_name:Jack customer_id:user007 customer_last_name:Sparrow customer_phone:02081234567 payment_amount:2035 payment_currency:USD payment_description:Guyliner purchase payment_id:X03936 project_id:12345 ``` 4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` {#codeblock_wng_21b_f1c} close_on_missclick:1;customer_first_name:Jack;customer_id:user007;customer_last_name:Sparrow;customer_phone:02081234567;payment_amount:2035;payment_currency:USD;payment_description:Guyliner purchase;payment_id:X03936;project_id:12345 ``` 5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` {#codeblock_uq4_21b_f1c} SyA3cx/dmFrwjRcpbnwEK9zaklWKR9buIfTctQob/EHUTutFLpI0zWpSDFEWEwbZt/04i83395RCdEhtUMw83A== ``` 6. Добавить полученную подпись в объект configObj: ``` {#codeblock_cmw_21b_f1c} { "project_id": 12345, "payment_id": "X03936", "payment_amount": 2035, "payment_currency": "USD", "payment_description": "Guyliner purchase", "customer_first_name": "Jack", "customer_id": "user007", "customer_last_name": "Sparrow", "customer_phone": "02081234567", "close_on_missclick": true, **"signature": "SyA3cx/dmFrwjRcpbnwEK9zaklWKR9buIfTctQob/EHUTutFLpI0zWpSDFEWEwbZt/04i83395RCdEhtUMw83A==" ** } ``` ### Форма тестирования для Payment Page {#section_sjm_2x3_1fc .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов на открытие Payment Page. **Прим.:** Для корректной работы с параметрами реальных запросов следует учитывать требования к кодированию вложенных объектов, представленные в статье [Спецификация Payment Page API](ru_PP_Parameters.md) и в статьях с описанием возможностей платёжной формы. При указании вложенных объектов, не соответствующих таким требованиям, подпись в форме тестирования рассчитывается в соответствии с алгоритмом, но не может использоваться для реальных запросов, поскольку оказывается сформированной на некорректных входных данных. ### Пример для запроса на оплату через Gate {#section_jqp_1ld_x4b .section} Допустим, что надо подписать запрос в Gate при следующих условиях: - Используемый ключ — `secret` - Предварительная версия тела запроса, в котором еще нет значения параметра с подписью, выглядит так: ``` {#codeblock_rzk_gx3_1fc .language-python} { "general": { "project_id": 3254, "payment_id": "id_38202316", **"signature": "<*подпись, которую нужно создать*\>"** }, "customer": { "id": "585741", "email": "johndoe@mycompany.com", "first_name": "John", "last_name": "Doe", "address": "Downing str., 23", "identify": { "doc_number": "54122312544" }, "ip_address": "111.222.333.444" }, "payment": { "amount": 10800, "currency": "USD", "description": "Computer keyboards" }, "receipt_data": { "positions": [ { "quantity": "10", "amount": "108", "description": "Computer keyboard" } ] }, "return_url": { "success": "https://paymentpage.mycompany.com/complete-redirect?id=success", "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline" } } ``` Задача заключается в том, чтобы вычислить подпись, то есть рассчитать значение параметра `signature` и добавить его в запрос. Для этого необходимо: 1. Убедиться, что в теле запроса нет параметра `signature`, даже с пустым значением. Если такой параметр есть, его нужно удалить. ``` {#codeblock_tzk_gx3_1fc .language-python} { "general": { "project_id": 3254, "payment_id": "id_38202316", **"signature": "<*подпись, которую нужно создать*\>"** }, "customer": { "id": "585741", "email": "johndoe@mycompany.com", "first_name": "John", "last_name": "Doe", "address": "Downing str., 23", "identify": { "doc_number": "54122312544" }, "ip_address": "111.222.333.444" }, "payment": { "amount": 10800, "currency": "USD", "description": "Computer keyboards" }, "receipt_data": { "positions": [ { "quantity": "10", "amount": "108", "description": "Computer keyboard" } ] }, "return_url": { "success": "https://paymentpage.mycompany.com/complete-redirect?id=success", "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline" } } ``` 2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ``` {#codeblock_vzk_gx3_1fc .language-json} general:project_id:3254 general:payment_id:id_38202316 customer:id:585741 customer:email:johndoe@mycompany.com customer:first_name:John customer:last_name:Doe customer:address:Downing str., 23 customer:identify:doc_number:54122312544 customer:ip_address:111.222.333.444 payment:amount:10800 payment:currency:USD payment:description:Computer keyboards receipt_data:positions:0:quantity:10 receipt_data:positions:0:amount:108 receipt_data:positions:0:description:Computer keyboard return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline ``` 3. Отсортировать полученные строки в естественном порядке: ``` {#codeblock_xzk_gx3_1fc .language-lua} customer:address:Downing str., 23 customer:email:johndoe@mycompany.com customer:first_name:John customer:id:585741 customer:identify:doc_number:54122312544 customer:ip_address:111.222.333.444 customer:last_name:Doe general:payment_id:id_38202316 general:project_id:3254 payment:amount:10800 payment:currency:USD payment:description:Computer keyboards receipt_data:positions:0:amount:108 receipt_data:positions:0:description:Computer keyboard receipt_data:positions:0:quantity:10 return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success ``` 4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` {#codeblock_zzk_gx3_1fc} customer:address:Downing str., 23;customer:email:johndoe@mycompany.com;customer:first_name:John;customer:id:585741;customer:identify:doc_number:54122312544;customer:ip_address:111.222.333.444;customer:last_name:Doe;general:payment_id:id_38202316;general:project_id:3254;payment:amount:10800;payment:currency:USD;payment:description:Computer keyboards;receipt_data:positions:0:amount:108;receipt_data:positions:0:description:Computer keyboard;receipt_data:positions:0:quantity:10;return_url:decline:https://paymentpage.mycompany.com/complete-redirect?id=decline;return_url:success:https://paymentpage.mycompany.com/complete-redirect?id=success ``` 5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` {#codeblock_b1l_gx3_1fc} VLLZzVNGevQNhr1b4TEhbC4qqHD17Kyn/M6FPNN93ttyk/amJgD/R6dayTKVvW6/QCRdq4hOf8R2w/xbUa8f2w== ``` 6. Добавить полученную подпись в тело запроса: ``` {#codeblock_d1l_gx3_1fc} { "general": { "project_id": 3254, "payment_id": "id_38202316", ** "signature": "VLLZzVNGevQNhr1b4TEhbC4qqHD17Kyn/M6FPNN93ttyk/amJgD/R6dayTKVvW6/QCRdq4hOf8R2w/xbUa8f2w=="** }, "customer": { "id": "585741", "email": "johndoe@mycompany.com", "first_name": "John", "last_name": "Doe", "address": "Downing str., 23", "identify": { "doc_number": "54122312544" }, "ip_address": "111.222.333.444" }, "payment": { "amount": 10800, "currency": "USD", "description": "Computer keyboards" }, "receipt_data": { "positions": [ { "quantity": "10", "amount": "108", "description": "Computer keyboard" } ] }, "return_url": { "success": "https://paymentpage.mycompany.com/complete-redirect?id=success", "decline": "https://paymentpage.mycompany.com/complete-redirect?id=decline" } } ``` ### Форма тестирования для Gate API {#section_f1l_gx3_1fc .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов к Gate API. ### Пример для запроса на получение данных через Data API {#section_omc_dld_x4b .section} Допустим, что надо подписать запрос в Dashboard при следующих условиях: - Используемый ключ — `secret` - Предварительная версия тела запроса, в котором еще нет значения параметра с подписью, выглядит так: ``` { "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl", "interval": { "from": "2020-01-01 14:53:55", "to": "2020-01-30 13:53:59" }, "project_id": [ 183 ], "limit": 3, "offset": 0, "tz": "Asia/Singapore", **"signature": "<*подпись, которую нужно создать*\>"** } ``` Задача заключается в том, чтобы вычислить подпись, то есть рассчитать значение параметра `signature` и добавить его в запрос. Для этого необходимо: 1. Убедиться, что в теле запроса нет параметра `signature`, даже с пустым значением. Если такой параметр есть, его нужно удалить. ``` { "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl", "interval": { "from": "2020-01-01 14:53:55", "to": "2020-01-30 13:53:59" }, "project_id": [ 183 ], "limit": 3, "offset": 0, "tz": "Asia/Singapore", **"signature": "<*подпись, которую нужно создать*\>"** } ``` 2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ``` token:WKiarERJ5pcceNerpM9R5TNnyPTQMl interval:from:2020-01-01 14:53:55 interval:to:2020-01-30 13:53:59 project_id:0:183 limit:3 offset:0 tz:Asia/Singapore ``` 3. Отсортировать полученные строки в естественном порядке: ``` interval:from:2020-01-01 14:53:55 interval:to:2020-01-30 13:53:59 limit:3 offset:0 project_id:0:183 token:WKiarERJ5pcceNerpM9R5TNnyPTQMl tz:Asia/Singapore ``` 4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` interval:from:2020-01-01 14:53:55;interval:to:2020-01-30 13:53:59;limit:3;offset:0;project_id:0:183;token:WKiarERJ5pcceNerpM9R5TNnyPTQMl;tz:Asia/Singapore ``` 5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` Ini3aKje6aZskajTuRS761YOzVqierlVRafZdxIz48wmVnL7yxgy9vDsp7T2/LGPGHJ/DHoKOgP7VqObJALrUA== ``` 6. Добавить полученную подпись в тело запроса: ``` { "token": "WKiarERJ5pcceNerpM9R5TNnyPTQMl", "interval": { "from": "2020-01-01 14:53:55", "to": "2020-01-30 13:53:59" }, "project_id": [ 183 ], "limit": 3, "offset": 0, "tz": "Asia/Singapore", **"signature": "Ini3aKje6aZskajTuRS761YOzVqierlVRafZdxIz48wmVnL7yxgy9vDsp7T2/LGPGHJ/DHoKOgP7VqObJALrUA=="** } ``` ### Форма тестирования для Data API {#section_tnw_qdf_52c .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписью при отправке запросов к Data API. **Прим.:** При работе с запросами, отправляемыми к платформе через Data API, и ответами на такие запросы необходимо учитывать, что расчётная подпись составляется с ограничением на 3 уровня вложенности и данные на более глубоких уровнях вложенности не принимаются в расчёт. ## Проверка данных {#ru_platform_signature_verification} ### Описание алгоритма {#section_skf_smd_x4b .section} *В качестве входных данных* для проверки целостности выступают: 1. *Подписанные данные*, которые требуется проверить. Как правило, это тело оповещения или ответа в формате JSON с параметром `signature` в его составе. 2. *Ключ*, используемый для проверки. Это должен быть ровно тот ключ, который был использован для подписывания проверяемых данных. *В качестве выходных данных* при проверке целостности в зависимости от реализации алгоритма могут выступать *расчётная подпись* и информация о её совпадении с проверяемой подписью, то есть *информация о целостности проверяемых данных*. Далее в описании, примерах и формах для тестирования представлен часто используемый и наиболее показательный вариант реализации алгоритма: с телом проверяемого сообщения \(оповещения или ответа\) в формате JSON на входе и с заключением о целостности этого сообщения на выходе. *В состав алгоритма* в этом случае *включаются следующие шаги*: 1. *Проверка входных данных на соблюдение заданных требований*: 1. Структура проверяемых данных должна соответствовать формату JSON. 2. В составе проверяемых данных должен присутствовать параметр `signature` с подписью. 3. Должен быть задан проверочный ключ. 2. *Извлечение подписи из проверяемых данных.* На этом шаге из проверяемых данных исключается параметр `signature`, а его значение фиксируется для последующего сличения с расчётной подписью. 3. При работе с ответами, получаемыми от платформы через Data API, на этом шаге значения всех параметров, расположенных на четвёртом и более глубоких уровнях вложенности, заменяются пустыми строками \(например, в ответе с информацией о выполнении операций за заданный период для объекта `"sum_initial": {"amount": 2000, "currency": "EUR"}` необходимо исключить значение и учитывать при расчёте подписи запись вида `"sum_initial": ""`\). При работе с ответами и оповещениями, получаемыми через другие интерфейсы платформы, ограничений по вложенности не применяется и действий по исключению данных не требуется. 4. *Формирование расчётной подписи для проверяемых данных:* 1. *Преобразование данных в строку UTF-8 с сортировкой параметров в естественном порядке.* В рамках этого шага выполняются следующие действия: 1. Логические \(булевы\) значения кодируются следующим образом: `false` заменяется на `0`, а `true` — на `1`. Но это относится только к булевым значениям — в строковых параметрах, даже если они содержат значения `false` или `true`, замены на `0` или `1` не используются\(например, в параметре `recurring: "{type: \"U\",register: true}"` замена `true` на `1` не требуется\). 2. Каждый параметр преобразуется в строку, содержащую полный путь к параметру, название параметра и его значение: `<родительский_узел_1>:...:<родительский_узел_N>:<название_параметра>:<значение_параметра>`, где *родительские узлы* — это названия объектов и \(или\) массивов, в состав которых включена пара «название параметра — значение параметра». Родительские узлы располагаются в порядке их вложения, начиная с самого верхнего уровня. В качестве разделителя при этом используется двоеточие \(:\), между парами «название параметра — значение параметра» удаляются запятые, а у строковых значений параметров удаляются обрамляющие кавычки. 3. Параметры с нулевыми, а также пустыми значениями остаются в строке, например запись `"payment_description":""` представляется в виде `payment_description:`. Замены пустых значений на пробелы или `null` не применяются. 4. Элементы массивов записываются отдельными строками, с указанием номера каждого элемента, начиная с нуля. Например, массив `["alpha", "beta", "gamma"]` представляется в виде трёх строк: `0:alpha`, `1:beta` и `2:gamma`. 5. Пустые массивы полностью игнорируются и не включаются в набор строк для создания подписи. 6. Кодировка всех строк приводится к формату UTF-8. 7. Полученные строки упорядочиваются в естественном порядке и объединяются в одну строку с использованием в качестве разделителя точки с запятой \(;\). 2. *Получение двоичного кода HMAC с использованием ключа и функции SHA‑512.* На этом шаге для полученной строки с параметрами вычисляется HMAC \(Hash-based Message Authentication Code; код аутентификации сообщений с использованием хеш-функции\) с использованием функции хеширования SHA‑512 \(Secure Hash Algorithm; безопасный алгоритм хеширования\) и применяемого ключа. И этот HMAC представляется в виде необработанных двоичных данных. 3. *Кодирование двоичного кода HMAC с применением алгоритма Base64*. На этом шаге полученный двоичный код HMAC кодируется с использованием алгоритма Base64. Получаемая при этом строка является подписью к исходным данным. 5. *Сопоставление подписей.* На этом шаге расчётная подпись сопоставляется с проверяемой. Если подписи совпадают, данные признаются целостными и достоверными. При несовпадении подписей данные не могут считаться достоверными и не должны использоваться в качестве рабочих. ### Пример для оповещения {#section_tk2_fnd_x4b .section} Допустим, что надо проверить подпись оповещения при следующих условиях: - Используемый ключ — `secret` - Тело полученного оповещения выглядит так: ``` {#codeblock_nyj_zlp_31c .language-json} { "customer": { "id": "782572" }, "account": { "number": "424242******4242", "token": "c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359", "type": "visa", "card_holder": "TEST TEST", "expiry_month": "01", "expiry_year": "2025" }, "project_id": 28051, "payment": { "id": "5242723", "type": "purchase", "status": "success", "date": "2023-03-10T12:26:17+0000", "method": "card", "sum": { "amount": 5200, "currency": "EUR" }, "description": "" }, "operation": { "sum_initial": { "amount": 5200, "currency": "EUR" }, "sum_converted": { "amount": 5200, "currency": "EUR" }, "code": "0", "message": "Success", "provider": { "id": 6, "payment_id": "16784511766816", "auth_code": "563253", "endpoint_id": 6, "date": "2023-03-10T10:26:17+0000" }, "id": 5028800010128225, "type": "sale", "status": "success", "date": "2023-03-10T12:26:17+0000", "created_date": "2023-03-10T12:26:15+0000", "request_id": "1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801" }, "signature": "IszjSnH+UqFp88DF0giI/jUTDHOnfPxc83j2VD/jN4loB9wbHwiO5+KvHfdFE4nBPHhhxD6TXbOkGnRINFTTmg==" } ``` Для проверки подписи необходимо: 1. Удалить из тела оповещения параметр `signature` вместе с его значением: ``` {#codeblock_vpc_1mp_31c .language-json} { "customer": { "id": "782572" }, "account": { "number": "424242******4242", "token": "c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359", "type": "visa", "card_holder": "TEST TEST", "expiry_month": "01", "expiry_year": "2025" }, "project_id": 28051, "payment": { "id": "5242723", "type": "purchase", "status": "success", "date": "2023-03-10T12:26:17+0000", "method": "card", "sum": { "amount": 5200, "currency": "EUR" }, "description": "" }, "operation": { "sum_initial": { "amount": 5200, "currency": "EUR" }, "sum_converted": { "amount": 5200, "currency": "EUR" }, "code": "0", "message": "Success", "provider": { "id": 6, "payment_id": "16784511766816", "auth_code": "563253", "endpoint_id": 6, "date": "2023-03-10T10:26:17+0000" }, "id": 5028800010128225, "type": "sale", "status": "success", "date": "2023-03-10T12:26:17+0000", "created_date": "2023-03-10T12:26:15+0000", "request_id": "1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801" }, **"signature": "IszjSnH+UqFp88DF0giI/jUTDHOnfPxc83j2VD/jN4loB9wbHwiO5+KvHfdFE4nBPHhhxD6TXbOkGnRINFTTmg=="** } ``` 2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ``` {#codeblock_lwv_1mp_31c .language-json} customer:id:782572 account:number:424242******4242 account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359 account:type:visa account:card_holder:TEST TEST account:expiry_month:01 account:expiry_year:2025 project_id:28051 payment:id:5242723 payment:type:purchase payment:status:success payment:date:2023-03-10T12:26:17+0000 payment:method:card payment:sum:amount:5200 payment:sum:currency:EUR payment:description: operation:sum_initial:amount:5200 operation:sum_initial:currency:EUR operation:sum_converted:amount:5200 operation:sum_converted:currency:EUR operation:code:0 operation:message:Success operation:provider:id:6 operation:provider:payment_id:16784511766816 operation:provider:auth_code:563253 operation:provider:endpoint_id:6 operation:provider:date:2023-03-10T10:26:17+0000 operation:id:5028800010128225 operation:type:sale operation:status:success operation:date:2023-03-10T12:26:17+0000 operation:created_date:2023-03-10T12:26:15+0000 operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801 ``` 3. Отсортировать полученные строки в естественном порядке: ``` {#codeblock_pmt_lkp_31c .language-json} account:card_holder:TEST TEST account:expiry_month:01 account:expiry_year:2025 account:number:424242******4242 account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359 account:type:visa customer:id:782572 operation:code:0 operation:created_date:2023-03-10T12:26:15+0000 operation:date:2023-03-10T12:26:17+0000 operation:id:5028800010128225 operation:message:Success operation:provider:auth_code:563253 operation:provider:date:2023-03-10T10:26:17+0000 operation:provider:endpoint_id:6 operation:provider:id:6 operation:provider:payment_id:16784511766816 operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801 operation:status:success operation:sum_converted:amount:5200 operation:sum_converted:currency:EUR operation:sum_initial:amount:5200 operation:sum_initial:currency:EUR operation:type:sale payment:date:2023-03-10T12:26:17+0000 payment:description: payment:id:5242723 payment:method:card payment:status:success payment:sum:amount:5200 payment:sum:currency:EUR payment:type:purchase project_id:28051 ``` 4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` {#codeblock_fjv_bmp_31c} account:card_holder:TEST TEST;account:expiry_month:01;account:expiry_year:2025;account:number:424242******4242;account:token:c8175453f68ec7c8fb3f052b8d786c661261efebcb91155327a6c7b8f8e66359;account:type:visa;customer:id:782572;operation:code:0;operation:created_date:2023-03-10T12:26:15+0000;operation:date:2023-03-10T12:26:17+0000;operation:id:5028800010128225;operation:message:Success;operation:provider:auth_code:563253;operation:provider:date:2023-03-10T10:26:17+0000;operation:provider:endpoint_id:6;operation:provider:id:6;operation:provider:payment_id:16784511766816;operation:request_id:1f6d3ac37444142f5bd27e7491faa360633fd5a2-fc98e73d475fa4cd6ee02fc6340c964f0267b3d8-05028801;operation:status:success;operation:sum_converted:amount:5200;operation:sum_converted:currency:EUR;operation:sum_initial:amount:5200;operation:sum_initial:currency:EUR;operation:type:sale;payment:date:2023-03-10T12:26:17+0000;payment:description:;payment:id:5242723;payment:method:card;payment:status:success;payment:sum:amount:5200;payment:sum:currency:EUR;payment:type:purchase;project_id:28051 ``` 5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` {#codeblock_nzc_cmp_31c} Y0qjN9dDnPTdddkVvXKS1pGp2z8ZpIl60P1CocND3YRxuBNx05ZMnhUaGFt90fPzgwsI/UpLw0q2RR/XTiDQBg== ``` 6. Сравнить полученную подпись с проверяемой. В данном случае подписи не совпадают, а это значит, что такое оповещение недостоверно или ошибочно и должно быть отброшено. ### Форма тестирования для оповещений {#section_dzg_lx3_1fc .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными. ### Пример для ответа через Gate API {#section_ag3_ghs_y4b .section} Допустим, что надо проверить подпись ответа при следующих условиях: - Используемый ключ — `secret` - Тело полученного ответа выглядит так: ```language-json { "project_id": 200, "payment": { "id": "abc12345", "type": "purchase", "status": "success", "date": "2025-04-23T10:54:37+0000", "method": "card", "sum": { "amount": 45000, "currency": "EUR" }, "description": "" }, "account": { "number": "425000******0000", "token": "13n121******4991", "type": "visa", "card_holder": "****************", "expiry_month": "**", "expiry_year": "****" }, "customer": { "id": "customer_007" }, "operations": [ { "id": 9529253065607, "type": "auth", "status": "success", "date": "2025-04-23T10:54:27+0000", "created_date": "2025-04-23T10:53:48+0000", "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd", "sum_initial": { "amount": 45000, "currency": "EUR" }, "sum_converted": { "amount": 45000, "currency": "EUR" }, "code": "0", "message": "Success", "eci": "05", "provider": { "id": 3651, "payment_id": "00000000123456", "auth_code": "070707", "endpoint_id": 0000, "date": "2025-04-23T10:54:26+0000" } } ], "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ==" } ``` Для проверки подписи необходимо: 1. Удалить из тела ответа параметр `signature` вместе с его значением: ```language-json { "project_id": 200, "payment": { "id": "abc12345", "type": "purchase", "status": "success", "date": "2025-04-23T10:54:37+0000", "method": "card", "sum": { "amount": 45000, "currency": "EUR" }, "description": "" }, "account": { "number": "425000******0000", "token": "13n121******4991", "type": "visa", "card_holder": "****************", "expiry_month": "**", "expiry_year": "****" }, "customer": { "id": "customer_007" }, "operations": [ { "id": 9529253065607, "type": "auth", "status": "success", "date": "2025-04-23T10:54:27+0000", "created_date": "2025-04-23T10:53:48+0000", "request_id": "a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd", "sum_initial": { "amount": 45000, "currency": "EUR" }, "sum_converted": { "amount": 45000, "currency": "EUR" }, "code": "0", "message": "Success", "eci": "05", "provider": { "id": 3651, "payment_id": "00000000123456", "auth_code": "070707", "endpoint_id": 0000, "date": "2025-04-23T10:54:26+0000" } } ], **"signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="** } ``` 2. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ```language-json project_id:200 payment:id:abc12345 payment:type:purchase payment:status:success payment:date:2025-04-23T10:54:37+0000 payment:method:card payment:sum:amount:45000 payment:sum:currency:EUR payment:description: account:number:425000******0000 account:token:13n121******4991 account:type:visa account:card_holder:**************** account:expiry_month:** account:expiry_year:**** customer:id:customer_007 operations:0:id:9529253065607 operations:0:type:auth operations:0:status:success operations:0:date:2025-04-23T10:54:27+0000 operations:0:created_date:2025-04-23T10:53:48+0000 operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd operations:0:sum_initial:amount:45000 operations:0:sum_initial:currency:EUR operations:0:sum_converted:amount:45000 operations:0:sum_converted:currency:EUR operations:0:code:0 operations:0:message:Success operations:0:eci:05 operations:0:provider:id:3651 operations:0:provider:payment_id:00000000123456 operations:0:provider:auth_code:070707 operations:0:provider:endpoint_id:0 operations:0:provider:date:2025-04-23T10:54:26+0000 ``` 3. Отсортировать полученные строки в естественном порядке: ```language-json account:card_holder:**************** account:expiry_month:** account:expiry_year:**** account:number:425000******0000 account:token:13n121******4991 account:type:visa customer:id:customer_007 operations:0:code:0 operations:0:created_date:2025-04-23T10:53:48+0000 operations:0:date:2025-04-23T10:54:27+0000 operations:0:eci:05 operations:0:id:9529253065607 operations:0:message:Success operations:0:provider:auth_code:070707 operations:0:provider:date:2025-04-23T10:54:26+0000 operations:0:provider:endpoint_id:0 operations:0:provider:id:3651 operations:0:provider:payment_id:00000000123456 operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd operations:0:status:success operations:0:sum_converted:amount:45000 operations:0:sum_converted:currency:EUR operations:0:sum_initial:amount:45000 operations:0:sum_initial:currency:EUR operations:0:type:auth payment:date:2025-04-23T10:54:37+0000 payment:description: payment:id:abc12345 payment:method:card payment:status:success payment:sum:amount:45000 payment:sum:currency:EUR payment:type:purchase project_id:200 ``` 4. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` account:card_holder:****************;account:expiry_month:**;account:expiry_year:****;account:number:425000******0000;account:token:13n121******4991;account:type:visa;customer:id:customer_007;operations:0:code:0;operations:0:created_date:2025-04-23T10:53:48+0000;operations:0:date:2025-04-23T10:54:27+0000;operations:0:eci:05;operations:0:id:9529253065607;operations:0:message:Success;operations:0:provider:auth_code:070707;operations:0:provider:date:2025-04-23T10:54:26+0000;operations:0:provider:endpoint_id:0;operations:0:provider:id:3651;operations:0:provider:payment_id:00000000123456;operations:0:request_id:a7B9kLmQwP2X8rTg-uV3n6Zc1RbEyHd;operations:0:status:success;operations:0:sum_converted:amount:45000;operations:0:sum_converted:currency:EUR;operations:0:sum_initial:amount:45000;operations:0:sum_initial:currency:EUR;operations:0:type:auth;payment:date:2025-04-23T10:54:37+0000;payment:description:;payment:id:abc12345;payment:method:card;payment:status:success;payment:sum:amount:45000;payment:sum:currency:EUR;payment:type:purchase;project_id:200 ``` 5. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` qUVvwChGUOSWRXwKQI6ZIkKvvWJsvx2luS8cYvN+M7iRiBAKkGE+WwfgAztgGU+vZNMr2bd4Lnn0J0KkhwYS1A== ``` 6. Сравнить полученную подпись с проверяемой. В данном случае подписи не совпадают, а это значит, что такой ответ недостоверен или ошибочен и должен быть отброшен. ### Форма тестирования для ответов через Gate API {#section_dml_53y_y2c .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными. ### Пример для ответа через Data API {#section_tnl_nx3_1fc .section} Допустим, что надо проверить подпись ответа при следующих условиях: - Используемый ключ — `secret` - Тело полученного ответа выглядит так: ``` {#codeblock_wnl_nx3_1fc .language-json} { "operations": [ { "project_id": "183", "operation_id": "9048253065548", "payment_id": "EP834a-40521580376090593", "operation_type": "cancel", "operation_status": "success", "account_number": "431422******0056", "customer_ip": "192.0.0.255", "payment_method_name": "visa", "payment_method_type": "visa", "payment_description": null, "operation_created_at": "2020-01-30T12:29:03+03:00", "operation_completed_at": "2020-01-30T12:29:04+03:00", "provider_date": null, "shipment_date": "", "mid": "3416123", "sum_initial": { "amount": 2000, "currency": "EUR" }, "sum_converted": { "amount": 2000, "currency": "EUR" }, "provider_name": "Dashboard Provider Card", "fee_currency": null, "fee_amount": 0, "arn": null, "rrn": null } ], "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ==" } ``` Для проверки подписи необходимо: 1. Удалить из тела ответа параметр `signature` вместе с его значением: ``` {#codeblock_znl_nx3_1fc .language-json} { "operations": [ { "project_id": "183", "operation_id": "9048253065548", "payment_id": "EP834a-40521580376090593", "operation_type": "cancel", "operation_status": "success", "account_number": "431422******0056", "customer_ip": "192.0.0.255", "payment_method_name": "visa", "payment_method_type": "visa", "payment_description": null, "operation_created_at": "2020-01-30T12:29:03+03:00", "operation_completed_at": "2020-01-30T12:29:04+03:00", "provider_date": null, "shipment_date": "", "mid": "3416123", "sum_initial": { "amount": 2000, "currency": "EUR" }, "sum_converted": { "amount": 2000, "currency": "EUR" }, "provider_name": "Dashboard Provider Card", "fee_currency": null, "fee_amount": 0, "arn": null, "rrn": null } ], ** "signature": "EksxDdDygDQ30JKsfK6QSvubpNRSj3wtLI5FzWDJuNY0nEhLXt65Y77dtKMJRcd39NegA7YK1eojA2EB1hIbnQ=="** } ``` 2. Заменить пустой строкой данные на четвёртом уровне вложенности: ``` {#codeblock_g4b_fhq_1fc .language-json} { "operations": [ { "project_id": "183", "operation_id": "9048253065548", "payment_id": "EP834a-40521580376090593", "operation_type": "cancel", "operation_status": "success", "account_number": "431422******0056", "customer_ip": "192.0.0.255", "payment_method_name": "visa", "payment_method_type": "visa", "payment_description": null, "operation_created_at": "2020-01-30T12:29:03+03:00", "operation_completed_at": "2020-01-30T12:29:04+03:00", "provider_date": null, "shipment_date": "", "mid": "3416123", **"sum\_initial": \{ "amount": 2000, "currency": "EUR" \},** **"sum\_initial":"",** **"sum\_converted": \{ "amount": 2000, "currency": "EUR" \},** **"sum\_converted":"",** "provider_name": "Dashboard Provider Card", "fee_currency": null, "fee_amount": 0, "arn": null, "rrn": null } ] } ``` 3. Преобразовать оставшиеся параметры в строки UTF-8 согласно правилам алгоритма: ``` {#codeblock_b4l_nx3_1fc .language-json} operations:0:project_id:183 operations:0:operation_id:9048253065548 operations:0:payment_id:EP834a-40521580376090593 operations:0:operation_type:cancel operations:0:operation_status:success operations:0:account_number:431422******0056 operations:0:customer_ip:192.0.0.255 operations:0:payment_method_name:visa operations:0:payment_method_type:visa operations:0:payment_description: operations:0:operation_created_at:2020-01-30T12:29:03+03:00 operations:0:operation_completed_at:2020-01-30T12:29:04+03:00 operations:0:provider_date: operations:0:shipment_date: operations:0:mid:3416123 operations:0:sum_initial: operations:0:sum_converted: operations:0:provider_name:Dashboard Provider Card operations:0:fee_currency: operations:0:fee_amount:0 operations:0:arn: operations:0:rrn: ``` 4. Отсортировать полученные строки в естественном порядке: ``` {#codeblock_d4l_nx3_1fc .language-json} operations:0:account_number:431422******0056 operations:0:arn: operations:0:customer_ip:192.0.0.255 operations:0:fee_amount:0 operations:0:fee_currency: operations:0:mid:3416123 operations:0:operation_completed_at:2020-01-30T12:29:04+03:00 operations:0:operation_created_at:2020-01-30T12:29:03+03:00 operations:0:operation_id:9048253065548 operations:0:operation_status:success operations:0:operation_type:cancel operations:0:payment_description: operations:0:payment_id:EP834a-40521580376090593 operations:0:payment_method_name:visa operations:0:payment_method_type:visa operations:0:project_id:183 operations:0:provider_date: operations:0:provider_name:Dashboard Provider Card operations:0:rrn: operations:0:shipment_date: operations:0:sum_converted: operations:0:sum_initial: ``` 5. Объединить отсортированные строки в одну строку с использованием в качестве разделителя точки с запятой: ``` {#codeblock_f4l_nx3_1fc} operations:0:account_number:431422******0056;operations:0:arn:;operations:0:customer_ip:192.0.0.255;operations:0:fee_amount:0;operations:0:fee_currency:;operations:0:mid:3416123;operations:0:operation_completed_at:2020-01-30T12:29:04+03:00;operations:0:operation_created_at:2020-01-30T12:29:03+03:00;operations:0:operation_id:9048253065548;operations:0:operation_status:success;operations:0:operation_type:cancel;operations:0:payment_description:;operations:0:payment_id:EP834a-40521580376090593;operations:0:payment_method_name:visa;operations:0:payment_method_type:visa;operations:0:project_id:183;operations:0:provider_date:;operations:0:provider_name:Dashboard Provider Card;operations:0:rrn:;operations:0:shipment_date:;operations:0:sum_converted:;operations:0:sum_initial: ``` 6. Вычислить HMAC полученной строки с использованием функции хеширования SHA-512 и используемого ключа, после чего кодировать двоичный код HMAC с применением алгоритма Base64: ``` {#codeblock_h4l_nx3_1fc} F58IW7JCqHsUthlmgQ/i1plf6lRPfdSVTGMXeEfhUMpdmwDMHKlO/rbtTy+V8cmQtvPNBjvuyQnl/rWxT7gPGg== ``` 7. Сравнить полученную подпись с проверяемой. В данном случае подписи не совпадают, а это значит, что такой ответ недостоверен или ошибочен и должен быть отброшен. ### Форма тестирования для ответов через Data API {#section_fnv_4x3_1fc .section} Далее представлена интерактивная форма для самостоятельной проверки корректной работы с подписанными данными. **Прим.:** При работе с запросами, отправляемыми к платформе через Data API, и ответами на такие запросы необходимо учитывать, что расчётная подпись составляется с ограничением на 3 уровня вложенности и данные на более глубоких уровнях вложенности не принимаются в расчёт. --- # Работа с информацией о платежах {#ru_platform_payment_information} статьи о том, как можно получать информацию о платежах, проводимых через платформу, чтобы организовывать необходимые процессы контроля, реагирования и анализа Чтобы организовывать необходимые со стороны мерчанта процессы контроля, реагирования и анализа при работе с платёжной платформой, следует настроить получение и обработку информации о платежах. В этом разделе собраны основные материалы, которые могут быть полезны для такой настройки: - [Обзор](ru_platform_payment_information_overview.md) — краткий обзор основных способов получения информации о платежах и операциях, с описанием их ключевых различий и особенностей. - [Работа с оповещениями](ru_platform_callbacks.md) — статья о работе с программными оповещениями, позволяющими максимально оперативно получать значимую информацию о проведении каждого платежа. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md) — статья о статусах и служебных кодах, которые используются в платформе, чтобы фиксировать состояние операций и причины их отклонения. Кроме того, для работы с информацией о платежах могут быть полезны: - статья о работе с запросами Gate API, которые позволяют получать актуальную информацию об отдельных платежах — [Получение информации о состоянии платежа](ru_Gate_payment_status_request.md); - материалы о работе с интерфейсами, обеспечивающими разные способы контроля информации о платежах — [Dashboard](ru_dbl_about.md), [Использование Data API](ru_dbl_api_protocol.md). - **[Обзор](ru_platform_payment_information_overview.md)** статья с кратким обзором и сопоставлением основных способов получения информации о платежах и операциях при работе с платформой - **[Работа с оповещениями](ru_platform_callbacks.md)** статья о работе с программными оповещениями, позволяющими максимально оперативно получать значимую информацию о проведении каждого платежа, с описанием типов оповещений и используемых в них структур данных - **[Работа с информацией об операциях](ru_platform_payment_info_codes.md)** статья о статусах и служебных кодах, которые используются в платформе, чтобы фиксировать состояние операций и причины их отклонения **На уровень выше:**[Платформа](ru_platform_about.md) --- # Обзор {#ru_platform_payment_information_overview} статья с кратким обзором и сопоставлением основных способов получения информации о платежах и операциях при работе с платформой При проведении платежей со стороны мерчанта важно контролировать ситуацию и своевременно получать различные сведения: о статусах отдельных платежей и операций, о сводных результатах платежей по разным срезам, об итоговых финансовых результатах и так далее. Для работы с такими задачами и обеспечения мерчантов всей необходимой информацией в платформе предусмотрен широкий круг возможностей. К основным из этих возможностей можно отнести следующие: - *Получение оповещений*. Если необходимо автоматически получать актуальную информацию об отдельных платежах, можно использовать программные оповещения \([подробнее](ru_platform_callbacks.md)\). Они отправляются от платформы к веб-сервису в заданных случаях, включают в себя настраиваемый набор параметров и заверяются цифровой подписью.При этом отправка оповещений может выполняться непосредственно при регистрации в платформе изменений, связанных с платежами \(без каких-либо задержек\), либо с заданной задержкой. При проведении платежей через Gate работа с оповещениями, которые предписывают выполнение определённых действий на стороне веб-сервиса, является обязательной. В остальных случаях от получения оповещений, как правило, можно отказываться, но желательно, напротив, использовать их как наиболее оперативный способ получения информации о каждом проводимом платеже. - *Использование Gate API*. Если необходимо получать актуальную информацию об отдельных платежах в то время, которое обуславливается спецификой работы веб-сервиса, а не платформы\(например, при наступлении определённых событий в веб-сервисе или через заданное время после инициирования каждого платежа\), можно использовать специализированные запросы к Gate API \([подробнее](ru_Gate_payment_status_request.md)\). Они обрабатываются по синхронной схеме и подразумевают ответы с настраиваемым набором параметров и цифровой подписью.При этом, как и в случае с оповещениями, в ответах на такие запросы используется оперативная информация, без задержек в её обновлении. - *Использование Data API*. Если необходимо получать в программном виде информацию о результатах проведения платежей за определённые периоды, можно использовать Data API \([подробнее](ru_dbl_api_protocol.md)\).Это может быть актуальным, например, при работе с собственной или сторонней аналитической системой вместо интерфейса Dashboard или в дополнение к нему. Data API позволяет получать информацию об операциях\(в том числе отдельно о мошеннических\), об опротестованиях операций и о балансах; при этом, поскольку при работе через Data API используется информация из долговременного хранилища, её обновление может выполняться с задержкой вплоть до нескольких минут. - *Использование интерфейса Dashboard*. Если необходимо получать информацию о результатах проведения платежей через пользовательский интерфейс, можно использовать Dashboard \([подробнее](ru_dbl_about.md)\). Он позволяет комплексно работать с информацией о платежах и операциях в самых разных срезах и использовать при этом различные реестры, карточки и отчёты.И, кроме того, через Dashboard можно не только получать различные сведения, но и выполнять множество действий по управлению платежами, „белыми“ и „чёрными“ списками платёжных атрибутов, опротестованиями, балансами и многим другим. Вместе с тем, стоит учитывать, что, как и в случае с Data API, при работе через Dashboard используется информация из долговременного хранилища, и её обновление может выполняться с задержкой вплоть до нескольких минут. Помимо этого, при работе с отдельными инструментами\(в частности, с SDK для мобильных приложений\) могут быть доступны дополнительные способы получения информации о проведении платежей. Они описываются в статьях о работе с этими инструментами и могут использоваться наряду с указанными здесь основными способами. В целом же можно отметить, что максимально оперативную информацию можно получать через оповещения и запросы Gate API, максимально полную — через Dashboard и Data API, а максимально удобную — через комбинирование доступных возможностей с учётом специфики веб-сервиса. С вопросами по этой теме всегда можно обращаться к материалам настоящей документации и к специалистам технической поддержки Ecommpay. **На уровень выше:**[Работа с информацией о платежах](ru_platform_payment_information.md) --- # Работа с оповещениями {#ru_platform_callbacks .concept} статья о работе с программными оповещениями, позволяющими максимально оперативно получать значимую информацию о проведении каждого платежа, с описанием типов оповещений и используемых в них структур данных **На уровень выше:**[Работа с информацией о платежах](ru_platform_payment_information.md) ## Обзор {#ru_callbacks_overview} ### Введение {#section_agk_xs2_ytb .section} *Оповещение* — это техническое сообщение, отправляемое от платёжной платформы Ecommpay к веб-сервису мерчанта и содержащее информацию об определённом событии в платёжной платформе, как правило связанном с проведением платежаили хранением платёжных данных пользователя. Оповещения позволяют своевременно получать информацию о различных событиях, при этом состав и условия отправки оповещений можно гибко конфигурировать, определяя что именно, в каких случаях, в каком виде и куда отправлять. В этой статье представлена информация об оповещениях, а также о порядке и особенностях работы с ними. ### Виды оповещений {#section_uk5_ys2_ytb .section} Оповещения можно условно разделить на *предписывающие*, требующие каких-либо действий со стороны веб-сервиса, и *уведомительные*, содержащие информацию к сведению. Предписывающие оповещения направляются в случаях, когда требуется отправить какие-либо сведения в платёжную платформу, предоставить определённую информацию пользователю, перенаправить его к сторонним сервисам или выполнить иные действия. Такие оповещения всегда содержат только промежуточную информацию о платежах и от их получения нельзя отказаться, поскольку своевременное реагирование на эти оповещения необходимо для корректного проведения платежей. Уведомительные оповещения направляются в случаях, когда можно принять и использовать определённую информацию, например об изменении статуса платежаили о формировании токена карты. Такие оповещения могут содержать промежуточную или итоговую информацию о платежах и от их получения можно отказываться \(выборочно или полностью\). **Прим.:** Отказ от получения уведомительных оповещений никак не влияет на возможность получения информации о платежах другими способами, в том числе с помощью запросов черезGate API \([подробнее](ru_Gate_payment_status_request.md)\) и Data API \([подробнее](ru_dbl_using_api.md)\), а также с помощью интерфейса Dashboard. Вместе с тем, оповещения являются наиболее оперативным и надёжным способом получения информации \(с подтверждением её доставки\), и отказываться от их получения следует только в обоснованных случаях, когда это соответствует специфике работы веб-сервиса. ### Типовые случаи применения {#section_hq2_zs2_ytb .section} К типовым случаям применения оповещений можно отнести следующие. - *Изменение статуса платежа.* Это могут быть оповещения как с промежуточной, так и с итоговой информацией о проведении платежа. ```language-json { "project_id": 42, "customer": { "id": "17008" }, "payment": { "id": "6789101", "type": "purchase", "status": "awaiting capture", // промежуточный статус платежа "date": "2022-01-11T13:00:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "USD" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "SONYA KOVALEVSKY", "expiry_month": "05", "expiry_year": "2025" }, "operation": { "id": 77000002, "type": "auth", "status": "success", "date": "2022-01-11T13:00:40+0000", "created_date": "2022-01-11T13:00:37+0000", "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9", "sum_initial": { "amount": 200000, "currency": "USD" }, "sum_converted": { "amount": 200000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "224750650", "date": "2022-01-11T13:00:39+0000", "result_code": "000", "result_message": "Approved", "auth_code": "505050", "endpoint_id": 120 }, "code": "0", "message": "Success", "description": "SUCCESS", "eci": "00" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` ```language-json { "project_id": 42, "payment": { "id": "6789102", "type": "purchase", "status": "success", // итоговый статус платежа "date": "2022-01-11T15:54:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "EUR" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "SONYA KOVALEVSKY", "expiry_month": "05", "expiry_year": "2025" }, "customer": { "id": "17008" }, "operation": { "id": 7178000006597, "type": "capture", "status": "success", "date": "2022-01-11T15:54:40+0000", "created_date": "2022-01-11T15:54:39+0000", "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0", "sum_initial": { "amount": 200000, "currency": "EUR" }, "sum_converted": { "amount": 200000, "currency": "EUR" }, "provider": { "id": 120, "payment_id": "227307324", "date": "2022-01-11T15:54:40+0000", "auth_code": "919372", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` - *Необходимость действий на стороне веб-сервиса.* Как правило, это оповещения с информацией для перенаправления пользователей, для отображения им определённой информации и для указания дополнительных данных, необходимых для проведения платежа. ```language-json "redirect_data":{ "method": "GET", "body": [], "encrypted": [], "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC" } ``` ```language-json "display_data": [ { "type": "qr_data", "title": "QR code", "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG" }, { "type": "add_info", "title": "QR Code Timeout", "data": "600" } ] ``` - *Формирование или удаление токена платёжной карты.* Это оповещения с информацией о событиях, связанных с токенами платёжных карт \(таких, как формирование и удаление токенов\). ```language-json { "general":{ "project_id":42, "customer_id":17008, "signature":"gmTHcy4ISuWEiV8+AupOYkl9S5eLZ", "request": { "id": "3c7f53fdbb5b8c96f9707457d75f", "action": "tokenize", "status": "success" }, "token":"f365bb1729f9b72fd9c0970e35c91d18070d15654", "token_created_at":"2022-01-28 13:30:57", "token_status":"active" } ``` ## Подключение и настройка {#ru_callbacks_configuration} ### Конфигурирование для проектов {#section_x1l_rt1_stb .section} В общем случае отправка оповещений для рабочих проектов мерчанта настраивается при интеграции веб-сервиса с платёжной платформой Ecommpay. Вместе с тем, для изменения правил отправки оповещений всегда можно использовать возможности интерфейса Dashboard \([подробнее](ru_dbl_projects.md)\), а также указывать специальные параметры в запросах на проведение платежей \(подробнее [далее](ru_platform_callbacks.md#section_ut2_hjq_x5b)\) и при необходимости обращаться к специалистам технической поддержки Ecommpay. Со стороны мерчанта для оповещений можно настраивать следующие свойства: - Обязательность отправки. Оповещения могут отправляться как для всех событий, так и только для событий, соответствующих заданным условиям: по типам событий, платёжным методам, а также типам и статусам платежей и операций.Так, например, оповещения могут не отправляться для проведённых выплат на платёжные карты и отправляться для отклонённых. Это позволяет оперативно получать только необходимую информацию. - Адреса доставки. Оповещения по разным событиям могут отправляться на разные адреса веб-сервиса, с учётом типа события, платёжного метода, типа и статуса платежа и операции. Например, оповещения с итоговой информацией о проведении платежей могут отправляться на один адрес, а об отклонении платежей — на другой. - Время задержки отправки. При необходимости оповещения могут отправляться с задержкой до 600 секунд включительно, например для удобства их обработки на стороне веб-сервиса. - Состав параметров. Для удобства обработки на стороне веб-сервиса состав информации, передаваемой в оповещениях, можно варьировать: добавлять и удалять параметры, а также заменять их названия и определять обязательность включения параметров с пустыми значениями. При этом нельзя менять структуру оповещений и исключать обязательные параметры. Стоит учитывать, что отдельные параметры могут быть обязательными для всех или только для определённых типов оповещений. Обязательные параметры передаются в оповещениях в любом случае, а необязательные — только в тех случаях, когда была получена соответствующая информация либо когда настроена отправка таких параметров даже с пустыми значениями. Таким образом, оповещения об одинаковых событиях в разных случаях могут выглядеть по-разному. ```language-json { "account": { "number": "431422******0056", "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654", "type": "visa", "card_holder": "SONYA KOVALEVSKY", "expiry_month": "05", "expiry_year": "2025" }, "customer": { "id": "17008", "phone": "79012345678" }, "payment": { "date": "2022-11-11T13:02:42+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 40000, "currency": "EUR" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2022-11-11T13:02:42+0000", "created_date": "2022-11-11T13:01:45+0000", "request_id": "c6eed1eb14c6290088cbc0be4667c", "sum_initial": { "amount": 40000, "currency": "EUR" }, "sum_converted": { "amount": 40000, "currency": "EUR" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2022-11-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` ```language-json { "account": { "number": "431422******0056", "token": "f365bb1729f9b72fd9c0970e35c91d18070d15654", "type": "visa", "card_holder": "SONYA KOVALEVSKY", "id": 45678, "expiry_month": "05", "expiry_year": "2025" }, "customer": { // объект с расширенной информацией о пользователе "id": "17008", "email": "sonya.kovalevsky@example.com" "phone": "79012345678", "first_name": "Sonya", "last_name": "Kovalevsky" }, "payment": { "date": "2022-11-11T13:02:42+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 40000, "currency": "EUR" }, "type": "purchase", "description": "" }, "project_id": 91663, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2022-11-11T13:02:42+0000", "created_date": "2022-11-11T13:01:45+0000", "request_id": "c6eed1e088cbc0be4667c", "sum_initial": { "amount": 40000, "currency": "EUR" }, "sum_converted": { "amount": 40000, "currency": "EUR" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2022-11-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogVftZ1ZZ5D/aZAeb0VMdeR+CqGrYyilUwSm...==" } ``` ### Управление отправкой для отдельных платежей {#section_ut2_hjq_x5b .section} При проведении платежей через Gate можно задавать адреса доставки оповещений, их обязательность и время задержки при отправке. Для этого в запросах на проведение платежей могут использоваться следующие параметры: - `merchant_callback_url` \(в объекте `general`\) — адрес доставки оповещений по этому запросу; - `force_disable` \(в объекте `callback`\) — указатель запрета отправки оповещений \(со значениями `true` для запрета отправки оповещений с информацией о данном платеже и `false` для разрешения их отправки\); - `delay` \(в объекте `callback`\) — задержка отправки оповещений, в секундах \(от 0 до 600; например, `42`\). Информацию о возможности использования этих параметров при запросах к конкретным конечным точкам можно найти в спецификации [Gate API](https://api-developers.ecommpay.com/). ```language-json { "general":{ "project_id":42, "payment_id":"456789", "merchant_callback_url":"https://example.com", "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "customer": { "id": "customer1", "ip_address": "66.249.64.45", "first_name": "John", "last_name": "Doe" }, "payment":{ "amount":40000, "currency":"EUR" }, "callback":{ "delay":42 // время задержки, равное 42 секундам }, "card":{ "pan":"4314220000000056", "year":2025, "month":5, "card_holder":"SONYA KOVALEVSKY", "cvv":"123" } } ``` ## Использование {#ru_callbacks_usage} ### Порядок работы {#section_kbg_v1q_stb .section} Технически оповещение представляет собой HTTP-POST-сообщение, отправляемое на предоставленный мерчантом URL. Порядок реагирования на каждое поступающее оповещение со стороны веб-сервиса сводится к следующим шагам: 1. Принять и проверить оповещение. Принимать оповещения следует только с IP-адресов платёжной платформы, предоставленных специалистами технической поддержки Ecommpay. При этом не следует ограничивать время ожидания оповещений, поскольку разные события могут наступать в различное время, а для отправки дополнительно может использоваться задержка. Чтобы подтверждать достоверность отправителя и целостность данных, необходимо проверять подпись, включаемую в состав каждого оповещения. Подробнее о такой проверке — в разделе [Работа с подписью к данным](ru_platform_signature.md). 2. Подтвердить получение оповещения. Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа `200 ОК`, в остальных случаях — с кодами ответов, соответствующими ошибкам, например `HTTP 400 Bad Request`, если не удалось преобразовать строку параметров в массив, или `HTTP 500 Internal Server Error`, если оповещение поступило на некорректный URL веб-сервиса. Если от веб-сервиса не поступило сообщение с кодом ответа `200 ОК`, независимо от характера ошибки оповещение отправляется повторно. 3. Выполнить необходимые действия. При получении предписывающих оповещений необходимо выполнять действия согласно этим оповещениям, при получении уведомительных — согласно специфике работы веб-сервиса, например с уведомлениями пользователей. ### Повторные отправления {#section_m1m_f2p_w5b .section} Если в платёжной платформе получена информация об ошибке при приёме оповещения или получение оповещения не подтверждено, такое оповещение отправляется повторно. При этом сведения в повторно отправляемых оповещениях могут меняться при изменении соответствующей информации в платёжной платформе: например, при изменении статуса платежа в последующие за этим оповещения включается информация уже о новом статусе. В общем случае отправка повторных оповещений выполняется в следующем порядке: 1. 6 попыток с нарастающим интервалом, от 10 до 60 секундс увеличением на 10 секунд для каждой попытки. 2. 58 попыток с нарастающим интервалом, от 84 секунд до 2,5 часовс увеличением по формуле `70 + 10 × 1,12n − 4` \(в секундах\), где *n* — порядковый номер попытки. 3. 56 попыток каждые 4 часадо достижения в общей сложности 120 попыток, после чего отправка оповещений по этому событию прекращается. Этот порядок может незначительно меняться с учётом загруженности серверов и каналов связи, но в целом автоматические попытки доставить оповещение укладываются в 11 суток. Для изменения этого порядка можно обращаться к специалистам технической поддержки Ecommpay. Кроме того, помимо автоматической повторной отправки оповещений в необходимых случаях можно инициировать разовые повторные отправки с помощью интерфейса Dashboard. ### Устранение неисправностей {#section_cnz_f2k_45b .section} Оповещения могут не приходить на требуемые адреса по различным причинам. Со стороны мерчанта такие ситуации и способы реагирования на них можно разбить на несколько групп. - *Не приходят оповещения ни по одному из событий.* Это может быть связано с отсутствием в платёжной платформе целевых запросов и событий, с проблемами в каналах связи и недействительностью заданных URL веб-сервиса, а также с отключением отправки оповещений по проекту. В таких ситуациях рекомендуется: 1. Убедиться, что со стороны веб-сервиса отправлялись корректные запросы\(без запрета отправки оповещений\) и они были приняты со стороны платформы. При необходимости отправить тестовый запрос, например на формирование токена платёжной карты. 2. Если запросы принимаются в платформе, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки Ecommpay. 3. Если по итогам предыдущих действий проблему не удалось решить — обратиться к специалистам технической поддержки Ecommpay. - *Не приходят оповещения по событиям отдельных типов.* Это может быть связано с отсутствием событий таких типов, с недействительностью URL веб-сервиса или с отключением отправки оповещений для событий этих типов. В таких ситуациях рекомендуется: 1. Убедиться в наличии событий тех типов, по которым не приходят оповещения, используя карточки платежей в интерфейсе Dashboard. 2. Если такие события выполнялись, но оповещения по-прежнему не приходят — проверить работоспособность URL для приёма оповещений по событиям соответствующих типов. При обнаружении проблем восстановить работоспособность адресов или изменить их на корректные: самостоятельно, через интерфейс Dashboard, или с помощью специалистов технической поддержки Ecommpay. 3. Если проблему не удалось решить — обратиться к специалистам технической поддержки Ecommpay. - *Не приходит оповещение по конкретной операции.* Это может быть связано с тем, что в объекте `callback` запроса на выполнение операции был передан параметр `force_disable` со значением `true`. В такой ситуации уточнять состояние операции можно через Gate, используя запросы на получение соответствующей информации \([подробнее](ru_Gate_payment_status_request.md)\), и[Dashboard](ru_dbl_payments.md). ## Передаваемые параметры {#ru_callbacks_parameters} ### Параметры оповещений о платежах и операциях {#section_jsq_s1g_ptb .section} Состав и названия параметров, передаваемых в оповещенияx о платежах и операциях, могут быть базовыми или индивидуально настроенными для отдельных проектов. К базовым относятся следующие параметры. |Параметр|Описание|tree| |--------|--------|----| |account object, optional |Объект, содержащий информацию о платёжных данных пользователя\(например, данных платёжной карты, счёта или электронного кошелька\)|10| |card\_holder string, optional |Имя держателя платёжной карты. Пример: `SONYA KOVALEVSKY` |10-10 10| |expiry\_month string, optional |Порядковый номер месяца срока действия платёжной карты. Пример: `05` |10-20 10| |expiry\_year string, optional |Год срока действия платёжной карты. Пример: `2025` |10-30 10| |id integer, optional |Идентификатор сохранённых платёжных данных, используемый в платёжной платформе\([подробнее](ru_gate_saved_data.md)\). Пример: `56789` |10-40 10| |number string, required |Маскированный номер или иной идентификатор платёжного инструмента пользователя \(например, платёжной карты, счёта или электронного кошелька\). Пример: `431422******0056` |10-50 10| |token string, optional |Токен платёжной карты, если он был сформирован при выполнении запроса \([подробнее](ru_Gate_Token.md)\) |10-60 10| |type string, optional |Указатель бренда платёжной карты, с использованием которой был проведён платёж: `amex`,`mastercard`, `maestro`, `visa`и другие |10-70 10| |acs object, optional |Объект, содержащий информацию о результате аутентификации пользователя с применением протокола 3‑D Secure|20| |acs\_url string, required |Адрес страницы, на которую перенаправлялся пользователь для его аутентификации с применением протокола 3‑D Secure \(ACS-страницы\) |20-10 20| |md string, required |Данные о мерчанте, полученные от международной платёжной системы при аутентификации пользователя с применением протокола 3‑D Secure \(Merchant Data\) |20-20 20| |pa\_req string, required |Сообщение PAReq \(Payer Authentication Request\), полученное при аутентификации пользователя с применением протокола 3‑D Secure|20-30 20| |avs\_data object, optional |Объект, содержащий информацию о результате проверки Address Verification Service \(AVS, [подробнее](ru_Gate_avs.md)\)|30| |avs\_post\_code string, optional |Почтовый индекс пользователя, переданный для выполнения проверки AVS. Пример: `LT-071171` |30-10 30| |avs\_street\_address string, optional |Адрес пользователя, переданный для выполнения проверки AVS. Пример: `Вильнюс, улица Дукшту, 30` |30-20 30| |avs\_result string, optional |Код результата проверки AVS \([подробнее](ru_Gate_avs.md)\). Пример: `F` |40| |bank object, optional |Объект, содержащий информацию об эмитенте платёжной карты, использованной при проведении платежа|50| |name string, optional |Название эмитента в платёжной платформе. Пример: `CITIBANK` |50-10 50| |customer object, optional |Объект, содержащий информацию о пользователе|70| |billing object, optional |Объект, содержащий информацию о платёжном адресе пользователя, полученном в платёжной платформе при проведении платежа|70-10 70| |address string, optional |Название улицы расчётного адреса пользователя. Пример: `Дукшту` |70-10-10 70-10| |city string, optional |Название города платёжного адреса пользователя. Пример: `Вильнюс` |70-10-20 70-10| |country string, optional |Код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2. Пример: `LT` |70-10-30 70-10| |postal string, optional |Индекс платёжного адреса пользователя. Пример: `LT-071171` |70-10-40 70-10| |region string, optional |Название региона \(района, области, края или республики\) платёжного адреса пользователя. Пример: `Вильнюсский уезд` |70-10-50 70-10| |city string, optional |Название города пользователя.Пример: `Вильнюс` |70-20 70| |country string, optional |Код страны пользователя в формате ISO 3166-1 alpha-2. Пример: `LT` |70-30 70| |day\_of\_birth string, optional |Дата рождения пользователя в формате ДД-ММ-ГГГГ. Пример: `17-04-1989` |70-40 70| |first\_name string, optional |Имя пользователя. Пример: `Софья` |70-50 70| |id string, optional |Идентификатор пользователя в рамках проекта мерчанта. Пример: `17008` |70-60 70| |ip\_address string, required |IP-адрес пользователя, актуальный для данной операции. Пример: `192.0.2.32` |70-70 70| |last\_name string, optional |Фамилия пользователя.Пример: `Ковалевская` |70-80 70| |middle\_name string, optional |Отчество или среднее имя пользователя.Пример: `Васильевна` |70-90 70| |phone string, optional |Номер телефона пользователя, содержащий от 4 до 24 цифр. Пример: `44997654321` |70-100 70| |decision string, optional |Строка, содержащая информацию об оценке допустимости проведения платежа на стороне платёжной платформы|80| |decision\_message array, optional |Массив записей, содержащий информацию об оценке допустимости проведения платежа на стороне платёжной платформы. Пример: `reject.message("RCS reject. Amount less than allowed")` |90| |display\_data object, optional |Объект, содержащий информацию, необходимую для отображения пользователю. Как правило, в этом объекте передаются сведения, полученные от провайдера или платёжной системы. Специфика для разных платёжных методов обычно указывается в статьях с описанием этих методов. Пример: `Approve the payment request sent to your phone` |100| |errors array, optional |Массив с сообщениями об ошибках, полученных при выполнении запроса|110| |ErrorItem object, required |Объект, содержащий информацию об ошибке при выполнении запроса|110-10 110| |code integer, optional |Код ошибки. Пример: `3287` |110-10-10 110-10| |description string, optional |Сведения о причине ошибки. Пример: `EMPTY_REFUND_CURRENCY` |110-10-10 110-10| |field string, optional |Название параметра, при указании которого была допущена ошибка \(если такой параметр определён\)|110-10-20 110-10| |message string, optional |Пояснение к коду ошибки. Пример: `The property currency is required` |110-10-30 110-10| |interface\_type object, optional |Объект, содержащий информацию о способе инициирования платежа|120| |id integer, optional |Индикатор интерфейса, через который поступил исходный запрос:- `1` — запрос поступил через Gate - `5` — запрос поступил через Dashboard - `6` — запрос поступил через Payment Page, открытой в модальном окне - `7` — запрос поступил через Payment Page, открытой в объекте iframe HTML-страницы |120-10 120| |user string, optional |Сведения об учётной записи пользователя Dashboard, отправившего исходный запрос. Пример: `janedoe@cosmoshop.com` |120-20 120| |operation object, optional |Объект, содержащий информацию об операциях, относящихся к платежу|130| |code string, optional |Код состояния операции \([подробнее](ru_platform_payment_info_codes.md)\). Пример: `0` |130-10 130| |created\_date string, optional |Дата и время создания операции. Пример: `2022-10-08T18:52:19+0000` |130-20 130| |date string, optional |Дата и время последнего обновления статуса операции в платёжной платформе. Пример: `2022-10-08T18:52:54+0000` |130-30 130| |eci string, optional |Индикатор результата аутентификации пользователя с применением протокола 3‑D Secure \([подробнее](ru_ECI_codes.md)\). Пример: `07` |130-40 130| |id integer, optional |Идентификатор операции в платёжной платформе. Пример: `17007255` |130-50 130| |message string, optional |Пояснительное описание к коду состояния операции \([подробнее](ru_platform_payment_info_codes.md)\). Пример: `Success` |130-60 130| |provider object, optional |Объект, содержащий информацию о результате выполнения платежа, полученную от провайдераилиплатёжной системы|130-70 130| |auth\_code string, optional |Код авторизации, полученный от провайдераилиплатёжной системы. Пример: `331040` |130-70-10 130-70| |date string, optional |Дата и время завершения обработки платежа на стороне провайдераилиплатёжной системы. Пример: `2022-10-08T18:52:53+0000` |130-70-20 130-70| |endpoint\_id string \(integer\), optional |CRC32-идентификатор провайдераилиплатёжной системы. Пример: `2` |130-70-30 130-70| |id integer, optional |Идентификатор провайдераилиплатёжной системы в платёжной платформе. Пример: `2` |130-70-40 130-70| |payment\_id string, optional |Идентификатор платежа на стороне провайдераилиплатёжной системы. Пример: `603458` |130-70-50 130-70| |recurring\_retry object, optional |Объект, содержащий информацию о повторных попытках списаний в рамках регулярных оплат \([подробнее](ru_Gate__cof_gate_side.md)\)|130-80 130| |next\_retry\_date string, optional |Дата и время следующей попытки списания. Пример: `2022-10-08T18:52:19+0000` |130-80-10 130-80| |next\_retry\_exists boolean, optional |Индикатор наличия следующей запланированной попытки списания: - `true` — повторная попытка запланирована, - `false` — повторная попытка не запланирована. Этот параметр обязателен, если передан объект `recurring_retry`. |130-80-20 130-80| |retry\_count integer, optional |Номер повторной попытки \(число от 1 до 7\), если такая попытка была выполнена. Пример: `3` |130-80-30 130-80| |trigger\_operation\_id integer, optional |Идентификатор очередного списания, для которого была выполнена повторная попытка. Пример: `17007255` |130-80-40 130-80| |request\_id string, required |Идентификатор последнего запроса, относящегося к данной операции, в платёжной платформе |130-90 130| |status string, required |Статус операции \(в соответствии [c моделью проведения платежей](ru_platform_payment_model.md)\). Пример: `success` |130-100 130| |sum\_converted object, optional |Объект, содержащий информацию о сумме и валюте операции после конвертации\([подробнее о конвертации](ru_Gate_Conversion.md)\)|130-110 130| |amount integer, optional |Сумма операции. В дробных единицах валюты, если они применимы, или в целых единицах. Пример: `8726` |130-110-10 130-110| |currency string, optional |Код валюты операции в формате ISO 4217 alpha-3. Пример: `EUR` |130-110-20 130-110| |sum\_initial object, optional |Объект, содержащий информацию о сумме и валюте операции, переданных в запросе|130-120 130| |amount integer, required |Исходная сумма операции в дробных единицах валюты. Пример: `9055` |130-120-10 130-120| |currency string, required |Код исходной валюты операции в формате ISO 4217 alpha-3. Пример: `USD` |130-120-20 130-120| |type string, required |Тип операции \(в соответствии [с моделью проведения платежей](ru_platform_payment_model.md)\). Пример: `sale` |130-130 130| |payment object, required |Объект, содержащий основные сведения о платеже|140| |cascading\_with\_redirect boolean, optional |Индикатор необходимости получить подтверждение пользователя на дополнительную попытку проведения оплаты в случае получения отказа при выполнении аутентификации 3‑D Secure \([подробнее](ru_gate_cascading.md)\):- `true` — подтверждение требуется - `false` — подтверждение не требуется |140-10 140| |date string, optional |Дата и время последнего обновления статуса платежа в платёжной платформе. Пример: `2022-10-08T18:52:54+0000` |140-20 140| |description string, optional |Описание платежа, переданное в исходном запросе. Пример: `Радиоуправляемая модель летающей тарелки Nano Size с доставкой` |140-30 140| |id string, required |Идентификатор платежа, переданный в исходном запросе. Пример: `18641868` |140-40 140| |is\_new\_attempts\_available boolean, optional |Индикатор возможности выполнить повторную попытку оплаты \([подробнее](ru_PP_Try_Again.md)\): - `true` — повторная попытка доступна - `false` — повторная попытка недоступна |140-50 140 е| |method string, optional |Код платёжного метода \([подробнее](ru_pm_codes.md)\). Пример: `card` |140-60 140| |merchant\_refund\_id string, optional |Идентификатор, полученный при инициировании возврата со стороны веб-сервиса. Пример: `refund_143` |140-61 140| |OperationFee object, optional |Объект, содержащий информацию о сумме комиссии|140-70 140| |amount string, optional |Сумма комиссии в дробных единицах валюты, если эта сумма включена в общую сумму операции|140-70-10 140-70| |currency string, optional |Код валюты, в которой начислена комиссия, в формате ISO 4217 alpha-3|140-70-20 140-70| |sum\_with\_surcharge string, optional |Общая сумма операции и надбавленной комиссии в дробных единицах валюты|140-70-30 140-70| |surcharge\_amount string, optional |Сумма комиссии, надбавленной к сумме платежа, в дробных единицах валюты \(применяется для микрофинансовых организаций, МФО\)|140-70-40 140-70| |surcharge\_currency string, optional |Код валюты, в которой начислена сумма комиссии, надбавленная к сумме платежа, в формате ISO 4217 alpha-3|140-70-50 140-70| |region string, optional |Код региона выполнения операции \([подробнее](ru_region_codes.md)\). Пример: `eea` |140-80 140| |status string, required |Cтатус платежа \(в соответствии [с моделью проведения платежей](ru_platform_payment_model.md)\). Пример: `partially refunded` |140-90 140| |sum object, optional |Объект, содержащий информацию о сумме и валюте платежа|140-100 140| |amount integer, required |Сумма платежа с учётом всех выполненных операций, в дробных единицах валюты. Пример: `8855` |140-100-10 140-100| |currency string, required |Код валюты платежа, переданный в исходном запросе, в формате ISO 4217 alpha-3. Пример: `USD` |140-100-20 140-100| |timeout\_attempts string, optional |Время, в течение которого возможно выполнение повторных попыток оплаты \([подробнее](ru_PP_Try_Again.md)\), в секундах. Пример: `360` |140-110 140| |type string, required |Тип платежа \(в соответствии [с моделью проведения платежей](ru_platform_payment_model.md)\). Пример: `purchase` |140-120 140| |scheme\_id string, optional |Идентификатор операции, в рамках которой была зарегистрирована повторяемая оплата, на стороне международной платёжной системы \(Mastercard или Visa\). Может передаваться при регистрации повторяемой оплаты для карты, выпущенной в Европейской экономической зоне. Пример: `MCS38A0790706` |210| |project\_id integer, required |Идентификатор проекта мерчанта в платёжной платформе. Пример: `42` |150| |provider\_extra\_fields object, optional |Объект, содержащий информацию, поступившую от провайдераилиплатёжной системы|160| |recurring object, optional |Объект, содержащий информацию о повторяемой оплате \([подробнее](ru_Gate__payments_on_saved_data.md)\)|170| |currency string, optional |Код валюты повторяемой оплаты в формате ISO 4217 alpha-3. Пример: `USD` |170-10 170| |id integer, optional |Идентификатор записи о серии списаний, присвоенный на стороне платёжной платформы \([подробнее](ru_PP_Try_Again.md)\) в платёжной платформе. Пример: `1001648` |170-20 170| |register\_payment\_id string, optional |Идентификатор записи о серии списаний \([подробнее](ru_PP_Try_Again.md)\) в веб-сервисе мерчанта. Пример: `18641865` |170-30 170| |status string, optional |Статус записи о серии списаний \([подробнее](ru_PP_Try_Again.md)\):- `active` — запись о серии списаний действительна - `canceled` — запись о серии списаний недействительна \(например, если повторяемая оплата отменена по запросу мерчанта\) |170-40 170| |type string, optional |Тип повторяемой оплаты \([подробнее](ru_PP_Try_Again.md)\):- `C` — экспресс-оплата \(OneClick\) - `U` — автооплата - `R` — регулярная оплата |170-50 170| |valid\_thru string, optional |Дата, до наступления которой возможно выполнение списаний \([подробнее](ru_PP_Try_Again.md)\). Пример: `2023-05-20T00:00:00+0000` |170-60 170| |redirect\_data object, optional |Объект, содержащий данные для перенаправления пользователя|180| |body object, optional |Данные для перенаправления пользователя|180-10 180| |method string, optional |Требуемый HTTP-метод отправки запроса на перенаправление: `POST` или `GET`|180-20 180| |url string, optional |URL, на который требуется направить пользователя|180-30 180| |signature string, required |Подпись оповещения \([подробнее](ru_platform_signature.md)\)|190| ### Параметры оповещений о токенах {#section_mhj_cvg_5tb .section} Состав и названия параметров, передаваемых в оповещенияx о действиях с токенами, таких как формирование или удаление токенов, могут быть базовыми или индивидуально настроенными для отдельных проектов. К базовым относятся следующие параметры. |Параметр|Описание| | |--------|--------|--| |general object, required |Объект с основными идентификационными сведениями из исходного запроса на формирование токена|1| |project\_id string, required |Идентификатор проекта мерчанта в платёжной платформе. Пример: `42` |1-11| |customer\_id string, optional |Идентификатор пользователя в проекте мерчанта. Пример: `17008` |1-21| |signature string, required |Подпись оповещения|1-31| |request object, required |Объект со сведениями об исходном запросе|2| |id integer, required |Идентификатор исходного запроса |2-12| |action string, optional |Тип исходного запроса:- `tokenize` — запрос на формирование токена; - `token_revoke` — запрос на удаление токена; Этот параметр может отсутствовать в случае, если токен деактивирован по истечению его срока действия и отправка оповещения инициирована автоматически в связи с этим событием |2-22| |status string, required |Статус запроса:- `success` — запрос выполнен - `error` — запрос не выполнен из-за возникновения ошибок, сведения о которых указаны в массиве `errors` |2-32| |errors array, optional |Массив с информацией об ошибках, возникших при выполнении запроса.Этот массив не передаётся в случаях, когда запрос выполнен без ошибок |2-42| |ErrorItem object, required |Объект с информацией об ошибке, возникшей при выполнении запроса|2-4-12-4| |code string, optional |Код ошибки, возникшей при выполнении запроса. Пример: `3021` |2-4-1-12-4-1| |message string, optional |Поясняющее описание к коду ошибки. Пример: `Card expired` |2-4-1-22-4-1| |field string, optional |Название параметра исходного запроса, в котором допущена ошибка, если этот параметр определён|2-4-1-32-4-1| |token string, optional |Токен платёжной карты |3| |token\_created\_at string, optional |Дата и время формирования токена карты. Пример: `2022-07-22T03:31:24+0000` |4| |token\_status string, optional |Статус токена:- `active` — токен действителен и может использоваться при проведении платежей; - `expiry` — токен недействителен, так как срок его действия истёк; - `revoke` — токен недействителен, так как был удалён по запросу со стороны веб-сервиса мерчанта |5| ## Дополнительные материалы {#ru_callbacks_links} При работе с оповещениями могут быть полезны: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— раздел с общей информацией о взаимодействии с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— раздел с информацией о работе с подписью к данным. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— раздел с информацией о кодах ошибок, используемых в платёжной платформе. - [Контроль и проведение платежей](ru_dbl_payments.md)— раздел с информацией о проведении и контроле проведения платежей и операций через Dashboard. - [Использование токенов](ru_Gate_Token.md)— раздел с информацией о работе с токенами карт. - [Спецификация Gate API](https://api-developers.ecommpay.com/)— спецификация интерфейса Gate API. --- # Работа с информацией об операциях {#ru_platform_payment_info_codes} статья о статусах и служебных кодах, которые используются в платформе, чтобы фиксировать состояние операций и причины их отклонения О состоянии каждой операции, созданной в платёжной платформе Ecommpay в рамках платежа, свидетельствует её статус. Этот статус передается в промежуточных и итоговых оповещениях о проведении платежа и в ответах на запрос [Получение информации о состоянии платежа](ru_Gate_payment_status_request.md)в параметре operation.status, а также отображается в интерфейсе Dashboard. В дополнение к статусам в платёжной платформе используются служебные коды и сообщения, которые уточняют информацию о выполнении или возможных причинах отклонения операций, в том числе со стороны внешних платёжных систем. Для удобства представления информации все используемые коды ответов и ошибок, а также соответствующие им сообщения унифицированы и передаются в веб-сервис мерчанта аналогично статусу в параметрах operation.code и operation.message. Также эти коды и сообщения можно увидеть в интерфейсе Dashboard в карточке платежа. ``` "operation": { "id": 65658000001111, "type": "sale", "status": "success", // статус операции "date": "2024-08-30T13:58:12+0000", "created_date": "2024-08-30T13:58:06+0000", "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3", "sum_initial": { "amount": 10000, "currency": "EUR" }, "sum_converted": { "amount": 10000, "currency": "EUR" }, "code": "0", // код, уточняющий статус "message": "Success" // пояснение к коду } ``` Если при обработке запроса на выполнение операции возникает ошибка, то в синхронном ответе от платёжной платформы указывается статус запроса `error`. Так как операция в данном случае не создаётся, то информация об ошибке передаётся в параметрах code и message. Подробная информация и примеры синхронных ответов об ошибках представлены в разделе [Формат ответа](ru_gate_interaction_organisation.md). При работе с ошибками, со стороны мерчанта могут потребоваться определённые действия в соответствии с полученными статусом и кодом ошибки. Возможные статусы операции и запроса и предусмотренные для них дальнейшие действия со стороны мерчанта приведены в таблице ниже. |Статусы|Примечание|Рекомендуемые действия| |-------|----------|----------------------| |`success`|Операция выполнена. Дальнейших действий не предусмотрено|Действий не требуется| |- `awaiting 3ds result` - `awaiting redirect result` - `awaiting clarification` - `awaiting customer action` - `awaiting merchant auth` - `processing` |Операция выполняется|Необходимо подождать| |`decline`|Операция отклонена из-за отказа пользователя, превышения количества запросов, обрыва связи или нехватки денежных средств у пользователя в данный момент времени|Можно попробовать еще раз или Можно повторить запрос позже| |Операция отклонена по причине некорректных данных в запросе. Устранить ошибку можно самостоятельно, скорректировав запрос, или обратиться за помощью в службу технической поддержки|Следует скорректировать запрос| |Операция отклонена по технической причине. Для устранения необходимо связаться со службой технической поддержки|Следует связаться со службой технической поддержки| |Операция отклонена после ее проверки риск-системой или по иным причинам, которые невозможно устранить. Комментарии по отказу можно узнать у службы технической поддержки|Действий не требуется| |`error`|Выполнение операции не инициировано из-за ошибки, возникшей при проверке принятого запроса|Следует скорректировать запрос| Возможные коды ответов, соответствующие им сообщения, а также рекомендуемые мерчанту дальнейшие действия, если они предусмотрены, приведены в таблицах ниже. ## Общие коды {#section_lyq_rcs_xzb .section} |Код|Сообщение|Описание|Действие| |---|---------|--------|--------| |0|Success|Операция успешно завершена|Действий не требуется| |100|General decline|Выполнение операции отклонено из-за получения общей ошибки от платёжной платформы|Следует связаться со службой технической поддержки| |104|Declined by 3DS check|Выполнение операции отклонено по причине неудачной попытки аутентификации пользователя|Можно попробовать еще раз| |108|Customer has not returned from ACS|Выполнение операции отклонено. Пользователь не вернулся с ACS страницы|Можно попробовать еще раз| |109|Declined by AVS check|Выполнение операции отклонено. Пользователь ввел некорректный адрес выставления счетов|Следует скорректировать запрос| |301|Cancelled|Выполнение операции отменено участником|Можно попробовать еще раз| |303|Access denied|Невозможно выполнить запрос, так как недостаточно прав|Следует связаться со службой технической поддержки| |309|The amount received during conversion exceeds the limit|Выполнение операции отклонено, так как сумма платежа превышает лимит, установленный платёжным провайдером|Следует скорректировать запрос| |310|This operation is not allowed by project settings|Выполнение операции отклонено. Данный тип операции недоступен для проекта|Следует связаться со службой технической поддержки| |314|Provider is not available now to perform the operation|Выполнение операции отклонено, так как платежный провайдер недоступен в данный момент|Можно повторить запрос позже| |318|Use of token\_data is disabled for the project|Выполнение операции отклонено, так как возможность применения сетевых токенов не подключена для проекта|Следует связаться со службой технической поддержки| |319|There is not enough data to create an operation|Выполнение операции отклонено, так как в запросе не указаны данные, обязательные для формирования операции|Следует скорректировать запрос| |402|RCS reject. Declined by Risk System|Выполнение операции отклонено из-за подозрения на мошенничество|Действий не требуется| |501|Internal error|Возникла внутренняя ошибка|Следует связаться со службой технической поддержки| |502|Validation error|Предоставленные данные не проходят валидацию|Следует связаться со службой технической поддержки| |504|Insufficient funds on the balance|Недостаточно средств на счёте|Следует связаться со службой технической поддержки| |601|Try again|Возникла ошибка|Можно попробовать еще раз| |602|Network error|Возникла ошибка соединения с одним из сторонних сервисов|Можно попробовать еще раз| |603|Auto decline|Выполнение операции было автоматически отклонено|Можно попробовать еще раз| |604|Payout Session Terminated. UUID Expired|Выполнение операции отклонено в связи с истечением срока действия идентификатора `uuid`|Можно повторить запрос с указанием действующего идентификатора `uuid`| |702|Malformed request|Запрос был отклонен по причине некорректного формата|Следует скорректировать запрос| |903|Exceeded allowed amount for refund|По данной карте общая сумма возвратов превышает сумму инитных оплат|Следует связаться со службой технической поддержки| |904|Exceeded allowed amount for payout|По данной карте превышен лимит по сумме для выплат|Следует связаться со службой технической поддержки| |2003|Invalid JSON string|В запросе передан некорректный JSON|Следует скорректировать запрос| |2004|Required field not provided|В запросе не передан обязательный параметр|Следует скорректировать запрос| |2014|Addendum data disallowed with recurring registration|Длинная запись запрещена при регистрации повторяемой оплаты|Следует скорректировать запрос| |2061|Avs Data Not Found|Выполнение операции отклонено. Необходимо указать данные для проверки AVS \(Address verification service\)|Попробуйте изменить запрос перед повторной отправкой| |2123|Account verification is not allowed|Проверка аккаунта запрещена|Следует связаться со службой технической поддержки| |2124|Invalid Customer ID|В запросе передано некорректное значение customer\_id|Следует скорректировать запрос| |2147|Lock Error|Выполнение операции отклонено из-за истечения времени ожидания|Можно повторить запрос позже| |2154|Customer ID is required for project|В запросе не передан обязательный для проекта параметр customer\_id|Следует скорректировать запрос| |2261|Country not found|В запросе не передан параметр country|Следует скорректировать запрос| |2426|Invalid Email|В запросе передано некорректное значение email|Следует скорректировать запрос| |2442|Project ID not found|В запросе не передан параметр project\_id|Следует скорректировать запрос| |2466|Declined By Pares Settings|Введен некорректный код проверки 3‑D Secure или произошла ошибка во время ввода|Можно повторить запрос позже| |2467|3DS SDK request is not supported|Указанный в запросе тип интерфейса App-based для аутентификации 3‑D Secure не может использоваться в рамках инициированного платежа|Можно сформировать повторный запрос, указав допустимое значение параметра `device_channel` и новый идентификатор платежа, или связаться со службой технической поддержки| |2468|3DS 3RI request is not supported|Указанный в запросе тип интерфейса 3DS Requestor Initiated для аутентификации 3‑D Secure не может использоваться в рамках инициированного платежа|Можно сформировать повторный запрос, указав допустимое значение параметра `device_channel` и новый идентификатор платежа, или связаться со службой технической поддержки| |2541|Unknown Payment Method|В запросе передан неизвестный payment\_method|Следует скорректировать запрос| |2606|Withdrawal without initial payment is not allowed|Выплата без инитной оплаты невозможна|Следует скорректировать запрос| |2609|Invalid day of birth|В запросе передано некорректное значение day\_of\_birth|Следует скорректировать запрос| |2610|Invalid Country|В запросе передано некорректное значение country|Следует скорректировать запрос| |2611|Invalid City|В запросе передано некорректное значение city|Следует скорректировать запрос| |2641|Invalid Bank Code or Currency|В запросе передано некорректное значение bank\_code или currency|Следует скорректировать запрос| |2642|Operation amount is greater than limit|Сумма операции больше установленного лимита|Следует скорректировать запрос| |2701|Rules Failed Code|Выполнение операции отклонено по бизнес-правилам|Следует связаться со службой технической поддержки| |2801|Bank ID not found|В запросе не передан параметр bank\_id|Следует скорректировать запрос| |2945|Invalid operation type for try again request|В запросе try again передан некорректный тип операции|Следует скорректировать запрос| |2949|Invalid amount for try again request|В запросе try again передано некорректное значение суммы|Следует скорректировать запрос| |3001|Invalid day of birth from UK merchant|В запросе от Мерчанта из Великобритании передано некорректное значение даты рождения пользователя|Следует скорректировать запрос| |3002|Invalid Post Code from UK merchant|В запросе от Мерчанта из Великобритании передано некорректное значение почтового индекса|Следует скорректировать запрос| |3003|Invalid Surname from UK merchant|В запросе от Мерчанта из Великобритании передано некорректное значение имени пользователя|Следует скорректировать запрос| |3004|Invalid Street Address from UK merchant|В запросе от Мерчанта из Великобритании передано некорректное значение адреса пользователя|Следует скорректировать запрос| |3020|Period of card validity is required for the project|Дата срока действия карты обязательна, но не была передана в запросе|Следует скорректировать запрос| |3021|Card expired|Срок действия карты истек|Следует скорректировать запрос| |3022|Customer is not presented in saved card request|В запросе на оплату по сохраненной карте не передано значение customer|Следует скорректировать запрос| |3023|Provided currency disabled for Project ID|В запросе передано значение валюты недопустимое для данного project\_id|Следует связаться со службой технической поддержки| |3024|Invalid Payment ID|В запросе передано некорректное значение payment\_id|Следует скорректировать запрос| |3025|Insufficent funds on card|Выполнение операции отклонено из-за недостатка средств на счете карты|Можно попробовать еще раз| |3026|Internal Decline|Выполнение операции через данную платежную систему недоступно|Следует связаться со службой технической поддержки| |3027|Invalid token provided|В запросе передано некорректное значение token|Следует скорректировать запрос| |3028|Insufficient funds on merchant balance|Недостаточно средств на счете для выплаты|Следует связаться с курирующим менеджером Ecommpay| |3029|Operation with expired card is not allowed for this provider|Выполнение операции по карте с истекшим сроком действия не разрешено для данного провайдера|Следует связаться со службой технической поддержки| |3041|Payment ID already exists|Значение payment\_id уже существует в системе|Следует скорректировать запрос| |3060|Current payment or operation status does not allow this action|Текущий статус платежа или операции не позволяет совершить желаемое действие|Следует связаться со службой технической поддержки| |3061|Transaction not found|Платеж не найден в системе|Можно попробовать еще раз или свяжитесь со службой технической поддержки| |3062|Payment details not received|Не удалось получить информацию о платеже в данный момент|Можно повторить запрос позже| |3081|State Machine Flow Break|При обработке платежа возникла ошибка|Следует связаться со службой технической поддержки| |3101|Card not found|Пользователю в запросе не принадлежат данные карты из переданного токена|Следует скорректировать запрос| |3102|Invalid payment constraint|Операция по карте не прошла проверку бизнес-правил системы|Следует связаться со службой технической поддержки| |3103|Payout was declined due to constraint for card type|Выплата отклонена по причине налагаемых эмитентом ограничений, связанных с типом карты|Следует связаться со службой технической поддержки| |3104|Payment Constraint Invalid Payout Amount|Превышен максимальный лимит по выплате|Следует скорректировать запрос| |3105|Card country is forbidden|Выполнение операции с использованием карты, выпущенной в указанной стране, запрещено|Следует скорректировать запрос| |3106|Payment Constraint Invalid Monthly Payout|Исчерпан месячный лимит на сумму выплат|Можно повторить запрос позже| |3107|Payout Constraint, card without successful purchase|Выплата отклонена в связи с тем, что не удалось идентифицировать оплату, в рамках которой была указана данная карта получателя средств|Следует связаться со службой технической поддержки| |3108|Payment Constraint Invalid Weekly Payout|Исчерпан недельный лимит на сумму выплат|Можно повторить запрос позже| |3109|Payment Constraint Invalid 24 Hour Payout|Исчерпан суточный лимит на сумму выплат|Можно повторить запрос позже| |3110|Payment Constraint Monthly payout operations number exceeded|Исчерпан месячный лимит на количество выплат|Можно повторить запрос позже| |3111|Payment Constraint Weekly payout operations number exceeded|Исчерпан недельный лимит на количество выплат|Можно повторить запрос позже| |3112|Payment Constraint 24 hour payout operations number exceeded|Исчерпан суточный лимит на количество выплат|Можно повторить запрос позже| |3117|Operation is prohibited because residual payment amount is less than one minor in USD|Выполнение операции отклонено, так как разница между актуальной суммой платежа и суммой операции меньше требуемой \(0,01 USD\)|Следует скорректировать запрос: указать меньшую сумму или полную сумму платежа| |3118|Operation amount will be less than one minor unit after conversion by IPS|Выполнение операции отклонено, так как сумма операции не должна быть меньше одной дробной единицы после конвертации, осуществлённой на стороне МПС|Следует скорректировать запрос| |3119|Request currency does not match channel currency|Валюта, указанная в запросе, не совпадает со значением валюты, в которой настроен платёжный канал мерчанта|Следует скорректировать запрос| |3120|The payment amount should not exceed 25 USD for the MCC|Выполнение операции отклонено, так как сумма платежа для этого MCC не должна превышать `25 USD` или эквивалентную сумму|Следует скорректировать запрос| |3121|Invalid currency|В запросе передано некорректное значение currency|Следует скорректировать запрос| |3123|Invalid API Key|В запросе передано некорректное значение API Key|Следует скорректировать запрос| |3124|Invalid certificate|При обработке запроса возникла ошибка|Следует связаться со службой технической поддержки| |3125|Incremental authorization requests are forbidden for the MCC|Запрос на увеличение суммы платежа в две стадии запрещён для этого MCC|Следует скорректировать запрос| |3141|CVV is required|CVV является обязательным параметром в данном запросе|Следует скорректировать запрос| |3161|Invalid Holder|В запросе передано некорректное значение card\_holder|Следует скорректировать запрос| |3162|Cardholder is required|В запросе не передан параметр card\_holder|Следует скорректировать запрос| |3181|Recurring registration ID not found|Идентификатор регистрации повторяемой оплаты recurring\_id, переданный в запросе, не найден|Следует скорректировать запрос| |3182|Duplicate recurring scheduled payment id|Идентификатор платежа для повторяемой оплаты продублирован|Следует скорректировать запрос| |3183|Recurring registration ID is invalidated due to card expiry date|По зарегистрированному повторяемому платежу истек срок действия карты|Действий не требуется| |3184|Recurring registration ID is cancelled|Повторяемая оплата по переданному идентификатору recurring\_id была отменена|Следует связаться со службой технической поддержки| |3186|Trigger operation ID is not found|Идентификатор списания в рамках повторяемой оплаты, для которого необходимо отменить выполнение повторных попыток, не найден|Следует скорректировать запрос| |3190|Remittance payment method mismatched|Платёжный метод, указанный в запросе, не совпадает с платёжным методом, указанным в карточке партнёра|Следует скорректировать запрос| |3191|Need clarification|Запрос нуждается в уточнении параметров|Следует скорректировать запрос| |3192|Remittance currency mismatched|Валюта, указанная в запросе, не совпадает с валютой, указанной в карточке партнёра|Следует скорректировать запрос| |3193|Remittance is not allowed for this project|Функциональность B2B-выплат недоступна для данного проекта|Следует связаться со службой технической поддержки| |3194|Recipient ID is not found|Переданное значение Recipient ID не найдено|Следует скорректировать запрос| |3195|Recipient ID is forbidden|Проведение B2B-выплаты на счёт получателя с данным Recipient ID запрещено|Следует скорректировать запрос| |3196|Remittance is not supported by payment system|Тип платежа `remittance` не поддерживается платёжной системой|Следует связаться со службой технической поддержки| |3197|Remittance is not allowed for this payment method|Тип платежа `remittance` запрещён для данного платёжного метода|Следует связаться со службой технической поддержки| |3198|Auto decline due to long verification|Операция отклонена, поскольку превышено время проверки её допустимости со стороны AML-специалистов Ecommpay|Следует связаться со службой технической поддержки и повторить запрос позже| |3199|Operation was declined by AML checks|Операция отклонена по результатам проверки её допустимости со стороны AML-специалистов Ecommpay|Следует связаться с курирующим менеджером| |3201|Expected error|Выполнение операции отклонено из-за ошибки при маршрутизации платежа|Следует связаться со службой технической поддержки| |3221|Card token not found|В запросе не передано значение token|Следует скорректировать запрос| |3230|The operation with such merchant\_refund\_id already exists|Выполнение операции отклонено, так как идентификатор возврата мерчанта уже зарегистрирован в платёжной платформе|Следует скорректировать запрос| |3241|Customer not found|В запросе значение customer не соответствует token|Следует скорректировать запрос| |3242|Account must be defined|Должен быть передан объект `account`|Следует скорректировать запрос| |3243|Account must not be defined|Объект `account` не должен быть передан|Следует скорректировать запрос| |3244|Bank id must be defined|Должен быть передан параметр `bank_id`|Следует скорректировать запрос| |3261|Invalid signature|В запросе передано некорректное значение signature|Следует скорректировать запрос| |3262|Empty signature|Значение параметра signature в запросе пустое|Следует скорректировать запрос| |3281|Converted amount is less than one minor unit|Сконвертированная сумма меньше дробной единицы валюты|Следует связаться со службой технической поддержки| |3283|Refund amount more than init amount|Значение суммы в запросе на возврат больше суммы в первоначальной оплате|Следует скорректировать запрос| |3284|Refund currency mismatched or empty|Значение валюты в запросе на возврат не совпадает с валютой в первоначальной оплате или пустое|Следует скорректировать запрос| |3285|Cannot make refund because of timeout block for repeat refund|Выполнение операции отклонено из-за ограничений по частоте запросов на refund|Можно повторить запрос позже| |3286|The property amount is required|Отсутствует параметр amount в запросе. При передаче параметра currency необходимо передавать параметр amount|Следует скорректировать запрос| |3287|The property currency is required|Отсутствует параметр currency в запросе. При передаче параметра amount необходимо передавать параметр currency|Следует скорректировать запрос| |3288|Refund prohibited on disputed transaction|Выполнение возврата запрещено по платежус опротестованием|Следует связаться со службой технической поддержки| |3289|The operation amount is less than fix fee of tariff|Выполнение операции отклонено, так как сумма меньше суммы комиссии по тарифу|Следует скорректировать запрос| |3291|Incorrect merchant account settings for operation|Выполнение операции отклонено так как мерчант-аккаунт закрыт на все операции, кроме одного типа.|Следует скорректировать запрос| |3292|Online gambling payouts are not available for this MCC|Выплаты по азартным онлайн-играм недоступны для этого MCC|Следует связаться со службой технической поддержки| |3293|Payout method not filled in merchant account|Для мерчант-аккаунта не заполнен платёжный метод|Следует связаться со службой технической поддержки| |3297|The provider's daily limit for the merchant account for the total amount of transactions has been exceeded|Исчерпан суточный лимит на сумму операций, установленный провайдером для мерчант-аккаунта|Можно повторить запрос позже| |3298|The provider's daily limit on the total amount of transactions has been exceeded|Исчерпан суточный лимит на сумму операций, установленный провайдером|Можно повторить запрос позже| |3299|Sorry, the merchant status does not allow you to create an operation|Невозможно создать новую операцию для этого мерчанта|Следует связаться со службой технической поддержки| |3301|Recurring registration is expired|Срок действия повторяемой оплаты с таким идентификатором истёк|Следует скорректировать запрос| |3305|Payment Constraint 30-days Payout operations number exceeded for MCC 7995, 9406 Domestic|Исчерпан лимит на количество операций на выплаты за 30 дней по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3306|Payment Constraint 30-days Payout operations number exceeded for MCC 7995, 9406 Cross-border|Исчерпан лимит на количество операций на трансграничные выплаты за 30 дней по MCC 7995, 9406|Можно повторить запрос позже| |3307|Payment Constraint 30-days Payout operations number exceeded for Money transfer Domestic|Исчерпан лимит на количество выплат для денежных переводов внутри страны за 30 дней|Можно повторить запрос позже| |3308|Payment Constraint 30-days Payout operations number exceeded for Money transfer Cross-border|Исчерпан лимит на количество трансграничных выплат для денежных переводов за 30 дней|Можно повторить запрос позже| |3309|Payment Constraint 30-days Payout operations number exceeded for Funds disbursement Domestic|Исчерпан лимит на количество выплат по программе Funds disbursement внутри страны за 30 дней|Можно повторить запрос позже| |3310|Payment Constraint 30-days Payout operations number exceeded for Funds disbursement Cross-border|Исчерпан лимит на количество трансграничных выплат по программе Funds disbursement за 30 дней|Можно повторить запрос позже| |3311|Payment Constraint Invalid Weekly Payout for MCC 7995, 9406 Domestic|Исчерпан недельный лимит на сумму выплат по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3312|Payment Constraint Invalid Weekly Payout for MCC 7995, 9406 Cross-border|Исчерпан недельный лимит на сумму трансграничных выплат по MCC 7995, 9406|Можно повторить запрос позже| |3313|Payment Constraint Invalid Weekly Payout for Money transfer Domestic|Исчерпан недельный лимит на сумму выплат для денежных переводов внутри страны, составляющий `100 000 USD`|Можно повторить запрос позже| |3314|Payment Constraint Invalid Weekly Payout for Money transfer Cross-border|Исчерпан недельный лимит на сумму трансграничных выплат для денежных переводов, составляющий `100 000 USD`|Можно повторить запрос позже| |3315|Payment Constraint Invalid Weekly Payout for Funds disbursement Domestic|Исчерпан недельный лимит на сумму выплат по программе Funds disbursement внутри страны, составляющий `600 000 USD`|Можно повторить запрос позже| |3316|Payment Constraint Invalid Weekly Payout for Funds disbursement Cross-border|Исчерпан недельный лимит на сумму трансграничных выплат по программе Funds disbursement, составляющий `250 000 USD`|Можно повторить запрос позже| |3317|Payment Constraint Invalid 24 Hour Payout for MCC 7995, 9406 Domestic|Исчерпан суточный лимит на сумму выплат по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3318|Payment Constraint Invalid 24 Hour Payout for MCC 7995, 9406 Cross-border|Исчерпан суточный лимит на сумму трансграничных выплат по MCC 7995, 9406|Можно повторить запрос позже| |3319|Payment Constraint Invalid 24 Hour Payout for Money transfer Domestic|Исчерпан суточный лимит на сумму выплат для денежных переводов внутри страны, составляющий `50 000 USD`|Можно повторить запрос позже| |3320|Payment Constraint Invalid 24 Hour Payout for Money transfer Cross-border|Исчерпан суточный лимит на сумму трансграничных выплат для денежных переводов, составляющий `50 000 USD`|Можно повторить запрос позже| |3321|Payment Constraint Invalid 24 Hour Payout for Funds disbursement Domestic|Исчерпан суточный лимит на сумму выплат по программе Funds disbursement внутри страны, составляющий `250 000 USD`|Можно повторить запрос позже| |3322|Payment Constraint Invalid 24 Hour Payout for Funds disbursement Cross-border|Исчерпан суточный лимит на сумму трансграничных выплат по программе Funds disbursement, составляющий `100 000 USD`|Можно повторить запрос позже| |3323|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406 Domestic|Исчерпан лимит на сумму выплат за 30 дней по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3324|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406 Cross-border|Исчерпан лимит на сумму трансграничных выплат за 30 дней по MCC 7995, 9406|Можно повторить запрос позже| |3325|Payment Constraint Invalid 30-days Payout for Money transfer Domestic|Исчерпан лимит на сумму выплат за 30 дней для денежных переводов внутри страны, составляющий `200 000 USD`|Можно повторить запрос позже| |3326|Payment Constraint Invalid 30-days Payout for Money transfer Cross-border|Исчерпан лимит на сумму трансграничных выплат за 30 дней для денежных переводов, составляющий `200 000 USD`|Можно повторить запрос позже| |3327|Payment Constraint Invalid 30-days Payout for Funds disbursement Domestic|Исчерпан лимит на сумму выплат за 30 дней по программе Funds disbursement внутри страны, составляющий `1 250 000 USD`|Можно повторить запрос позже| |3328|Payment Constraint Invalid 30-days Payout for Funds disbursement Cross-border|Исчерпан лимит на сумму трансграничных выплат за 30 дней по программе Funds disbursement, составляющий `500 000 USD`|Можно повторить запрос позже| |3329|Payment Constraint Weekly payout operations number exceeded for MCC 7995, 9406 Domestic|Исчерпан недельный лимит на количество выплат по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3330|Payment Constraint Weekly payout operations number exceeded for MCC 7995, 9406 Cross-border|Исчерпан недельный лимит на количество трансграничных выплат по MCC 7995, 9406|Можно повторить запрос позже| |3331|Payment Constraint Weekly payout operations number exceeded for Money transfer Domestic|Исчерпан недельный лимит на количество выплат для денежных переводов внутри страны|Можно повторить запрос позже| |3332|Payment Constraint Weekly payout operations number exceeded for Money transfer Cross-border|Исчерпан недельный лимит на количество трансграничных выплат для денежных переводов|Можно повторить запрос позже| |3333|Payment Constraint Weekly payout operations number exceeded for Funds disbursement Domestic|Исчерпан недельный лимит на количество выплат по программе Funds disbursement внутри страны|Можно повторить запрос позже| |3334|Payment Constraint Weekly payout operations number exceeded for Funds disbursement Cross-border|Исчерпан недельный лимит на количество трансграничных выплат по программе Funds disbursement|Можно повторить запрос позже| |3335|Payment Constraint 24 hour payout operations number exceeded for MCC 7995, 9406 Domestic|Исчерпан суточный лимит на количество выплат по MCC 7995, 9406 внутри страны|Можно повторить запрос позже| |3336|Payment Constraint 24 hour payout operations number exceeded for MCC 7995, 9406 Cross-border|Исчерпан суточный лимит на количество трансграничных выплат по MCC 7995, 9406|Можно повторить запрос позже| |3337|Payment Constraint 24 hour payout operations number exceeded for Money transfer Domestic|Исчерпан суточный лимит на количество выплат для денежных переводов внутри страны|Можно повторить запрос позже| |3338|Payment Constraint 24 hour payout operations number exceeded for Money transfer Cross-border|Исчерпан суточный лимит на количество трансграничных для денежных переводов|Можно повторить запрос позже| |3339|Payment Constraint 24 hour payout operations number exceeded for Funds disbursement Domestic|Исчерпан суточный лимит на количество выплат по программе Funds disbursement внутри страны|Можно повторить запрос позже| |3340|Payment Constraint 24 hour payout operations number exceeded for Funds disbursement Cross-border|Исчерпан суточный лимит на количество трансграничных выплат по программе Funds disbursement|Можно повторить запрос позже| |3341|Payout was declined due to card constraints|Выполнение операции отклонено в связи с ограничениями на стороне эмитента|Следует связаться со службой технической поддержки| |3355|Payment Constraint 24 hour operations number exceeded for same card|Исчерпан суточный лимит на количество операций по карте|Можно повторить запрос позже| |3356|The operation is not allowed for this card|Выполнение операции запрещено для данной карты|Действий не требуется| |3357|Payment Constraint 30-days operations number exceed for same card|Исчерпан лимит на количество операций по карте за 30 дней|Можно повторить запрос позже| |3358|Operation amount is less than limit|Сумма операции меньше установленного лимита|Следует скорректировать запрос| |3360|Payment amount cannot exceed 50 EUR for prepaid non-reloadable card|Если отправитель перевода использует предоплаченную непополняемую карту, сумма списания не должна превышать `50 EUR`|Следует скорректировать запрос| |3362|Payment Constraint Invalid 30-days Payout for MCC 7995, 9406|Исчерпан лимит на сумму выплат за 30 дней по MCC 7995, 9406, составляющий `50 000 USD`|Можно повторить запрос позже| |3363|Trace ID must be present in recurring payment and MIT|При обработке запроса возникла ошибка|Следует связаться со службой технической поддержки| |3400|AFT Payment Constraint for Commercial cards|Выполнение операции отклонено из-за ограничений на осуществление переводов с использованием коммерческих карт|Следует скорректировать запрос| |3402|Payment Constraint 25000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|При использовании платёжных карт физических лиц сумма однократного списания не может превышать `25 000 USD`|Следует скорректировать запрос| |3403|Payment Constraint 50000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|При использовании карт для малого бизнеса сумма однократного списания не может превышать `50 000 USD`|Следует скорректировать запрос| |3404|Payment Constraint 25000 USD Amount limit exceeded for MoneySend payout by Consumer cards|При использовании платёжных карт физических лиц сумма однократного зачисления не может превышать `25 000 USD`|Следует скорректировать запрос| |3406|Payment Constraint 50000 USD Amount limit exceeded for MoneySend payout by Small business cards|При использовании карт для малого бизнеса сумма однократного зачисления не может превышать `50 000 USD`|Следует скорректировать запрос| |3407|Payment Constraint Invalid 30-days MoneySend payout for Consumer cards|При использовании платёжных карт физических лиц сумма зачислений не может превышать `25 000 USD` за 30 дней|Можно повторить запрос позже| |3408|Payment Constraint Invalid 30-days MoneySend payout for Small business cards|При использовании карт для малого бизнеса сумма зачислений не может превышать `50 000 USD` за 30 дней|Можно повторить запрос позже| |3409|Payment Constraint 2500 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|При использовании платёжных карт физических лиц сумма однократного списания не может превышать `2 500 USD`|Следует скорректировать запрос| |3410|Payment Constraint 2500 USD Amount limit exceeded for MoneySend payout by Consumer cards|При использовании платёжных карт физических лиц сумма однократного зачисления не может превышать `2 500 USD`|Следует скорректировать запрос| |3411|Payment cannot be made due to location of the sender's card issuer outside the Europe Region|Платёжная карта отправителя должна быть выпущена эмитентом европейского региона|Следует скорректировать запрос| |3412|Payment Constraint 25000 USD Amount limit exceeded for MoneySend payout by Small business cards|При использовании карт для малого бизнеса сумма однократного зачисления не может превышать `25 000 USD`|Следует скорректировать запрос| |3413|Payment Constraint 25000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|При использовании карт для малого бизнеса сумма однократного списания не может превышать `25 000 USD`|Следует скорректировать запрос| |3414|Payment Constraint 50000 USD Amount limit exceeded for MoneySend payout by Consumer cards|При использовании платёжных карт физических лиц сумма однократного зачисления не может превышать `50 000 USD`|Следует скорректировать запрос| |3415|Payment Constraint 100000 USD Amount limit exceeded for MoneySend payout by Small business cards|При использовании карт для малого бизнеса сумма однократного зачисления не может превышать `100 000 USD`|Следует скорректировать запрос| |3416|Payment Constraint 50000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|При использовании платёжных карт физических лиц сумма однократного списания не может превышать `50 000 USD`|Следует скорректировать запрос| |3417|Payment Constraint 100000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|При использовании карт для малого бизнеса сумма однократного списания не может превышать `100 000 USD`|Следует скорректировать запрос| |3418|Payment Constraint 75000 USD Amount limit exceeded for MoneySend payout by Small business cards|При использовании карт для малого бизнеса сумма однократного зачисления не может превышать `75 000 USD`|Следует скорректировать запрос| |3419|Payment Constraint 75000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|При использовании карт для малого бизнеса сумма однократного списания не может превышать `75 000 USD`|Следует скорректировать запрос| |3431|Money transfer is not possible for two identical cards|Номер карты отправителя перевода, переданный в запросе, совпадает с номером карты получателя перевода|Следует скорректировать запрос| |3432|The request must contain either the identifier of the saved card or complete card details|В запросе переданы как полные сведения о платёжной карте, так и идентификатор реквизитов в объектах `sender` и \(или\) `recipient`|Следует скорректировать запрос| |3433|The request contains complete card details for both cards. This endpoint is for making a payment using saved card data only|Запрос содержит полные сведения о картах отправителя и получателя, однако эта конечная точка предназначена для запросов на проведение платежей с использованием сохранённых платёжных данных|Следует скорректировать запрос| |3434|The sender's card expired|Срок действия платёжной карты отправителя истёк|Следует скорректировать запрос| |3435|The recipient's card expired|Срок действия платёжной карты получателя истёк|Следует скорректировать запрос| |3436|The sender's card is invalid|Недопустимо выполнение операции с платёжной картой отправителя|Следует скорректировать запрос| |3437|The recipient's card is invalid|Недопустимо выполнение операции с платёжной картой получателя|Следует скорректировать запрос| |3438|Saved sender card has no expiration date|Необходимо указать срок действия платёжной карты отправителя|Следует скорректировать запрос| |3439|The saved card has no expiration date|Необходимо указать срок действия платёжной карты|Следует скорректировать запрос| |3450|Payment Constraint Invalid 24 Hour AFT for Money transfer Domestic|Исчерпан суточный лимит на сумму списаний для денежных переводов внутри страны, составляющий `100 000 USD`|Можно повторить запрос позже| |3451|Payment Constraint Invalid Weekly AFT for Money transfer Domestic|Исчерпан недельный лимит на сумму списаний для денежных переводов внутри страны, составляющий `250 000 USD`|Можно повторить запрос позже| |3452|Payment Constraint Invalid 30-days AFT for Money transfer Domestic|Исчерпан лимит на сумму списаний за 30 дней для денежных переводов внутри страны, составляющий `500 000 USD`|Можно повторить запрос позже| |3470|Payment was declined due to sender's card constraints|Выполнение операции отклонено из-за ограничений на использование определённых видов платёжных карт отправителем перевода|Следует связаться со службой технической поддержки| |3471|Payment was declined due to recipient's card constraints|Выполнение операции отклонено из-за ограничений на использование определённых видов платёжных карт получателем перевода|Следует связаться со службой технической поддержки| |3472|Payment was declined due to location of the recipient's card issuer|Выполнение операции отклонено из-за ограничений, связанных с регионом платёжной карты получателя|Следует связаться с курирующим менеджером| |3480|Payment cannot be made due to location of the sender's card issuer outside the EEA|Страна платёжной карты отправителя должна входить в регион Европейской экономической зоны \(EEA\)|Следует скорректировать запрос| |3490|Required fields for Debt Repayment are missing|В запросе не переданы обязательные параметры для проведения операции по погашению задолженности|Следует скорректировать запрос| |3491|Invalid card type for Debt Repayment|Недопустимый тип карты для проведения операции по погашению задолженности|Следует скорректировать запрос| |3606|Payment Constraint Invalid 30-days MoneySend Funding Transaction for Consumer cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт физических лиц за 30 дней|Можно повторить запрос позже, по истечении текущего 30-дневного периода| |3607|Payment Constraint Invalid 30-days MoneySend Funding Transaction for Small business cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт для малого бизнеса за 30 дней|Можно повторить запрос позже, по истечении текущего 30-дневного периода| |3609|Operation amount must be equal to the initial amount|Сумма операции должна быть равна сумме исходной операции|Следует скорректировать запрос| |3610|Refund unavailable for the current operation|Выполнение возврата запрещено для данной операции|Следует связаться со службой технической поддержки| |3611|AFT reversal must be used to refund within the first 24 hours of the original AFT|Отменить исходную операцию можно только в течение первых суток после её выполнения|Следует связаться со службой технической поддержки| |3612|One or more required money transfer fields are empty|Необходимо дополнить информацию об отправителе и \(или\) получателе|Следует скорректировать запрос| |3613|Duplicate operation|Выполнение операции отклонено. Операция с такими идентификатором пользователя и суммой платежа уже существует|Можно повторить запрос позже| |3617|Not allowed mcc for pan with product code = F2|Выполнение операций с использованием карт данной категории \(F2\) не допускается для мерчантов с данным видом деятельности \(в соответствии с MCC\)|Следует связаться со службой технической поддержки| |3618|Payment Constraint 10000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Средства не могут быть зачислены, поскольку сумма однократного зачисления при использовании платёжных карт физических лиц не может превышать `10 000 USD`|Можно разбить зачисление на несколько, не превышающих установленного лимита| |3619|Payment Constraint 10000 USD Amount limit exceeded for MoneySend payout by Small business cards|Средства не могут быть зачислены, поскольку сумма однократного зачисления при использовании платёжных карт для малого бизнеса не может превышать `10 000 USD`|Можно разбить зачисление на несколько, не превышающих установленного лимита| |3620|Payment Constraint 125000 USD Amount limit exceeded for MoneySend payout by Consumer cards|Средства не могут быть зачислены, поскольку сумма однократного зачисления при использовании платёжных карт физических лиц не может превышать `125 000 USD`|Можно разбить зачисление на несколько, не превышающих установленного лимита| |3621|Payment Constraint 125000 USD Amount limit exceeded for MoneySend payout by Small business cards|Средства не могут быть зачислены, поскольку сумма однократного зачисления при использовании платёжных карт для малого бизнеса не может превышать `125 000 USD`|Можно разбить зачисление на несколько, не превышающих установленного лимита| |3622|Payment Constraint 125000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Средства не могут быть списаны, поскольку сумма однократного списания при использовании платёжных карт физических лиц не может превышать `125 000 USD`|Можно разбить списание на несколько, не превышающих установленного лимита| |3623|Payment Constraint 125000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Средства не могут быть списаны, поскольку сумма однократного списания при использовании платёжных карт для малого бизнеса не может превышать `125 000 USD`|Можно разбить списание на несколько, не превышающих установленного лимита| |3624|Payment Constraint 10000 USD Amount limit exceeded for MoneySend Funding Transaction by Consumer cards|Средства не могут быть списаны, поскольку сумма однократного списания при использовании платёжных карт физических лиц не может превышать `10 000 USD`|Можно разбить списание на несколько, не превышающих установленного лимита| |3625|Payment Constraint 10000 USD Amount limit exceeded for MoneySend Funding Transaction by Small business cards|Средства не могут быть списаны, поскольку сумма однократного списания при использовании платёжных карт для малого бизнеса не может превышать `10 000 USD`|Можно разбить списание на несколько, не превышающих установленного лимита| |3626|Payment Constraint Invalid 24 Hour payout for MoneySend by Consumer cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт физических лиц в сутки|Можно повторить запрос позже, по истечении суток| |3627|Payment Constraint Invalid 24 Hour payout for MoneySend by Small business cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт для малого бизнеса в сутки|Можно повторить запрос позже, по истечении суток| |3628|Payment Constraint Invalid 24 Hour funding for MoneySend by Consumer cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт физических лиц в сутки|Можно повторить запрос позже, по истечении суток| |3629|Payment Constraint Invalid 24 Hour funding for MoneySend by Small business cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт для малого бизнеса в сутки|Можно повторить запрос позже, по истечении суток| |3630|Payment Constraint Invalid Weekly payout for MoneySend by Consumer cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт физических лиц в неделю|Можно повторить запрос позже, по истечении текущего 7-дневного периода| |3631|Payment Constraint Invalid Weekly payout for MoneySend by Small business cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт для малого бизнеса в неделю|Можно повторить запрос позже, по истечении текущего 7-дневного периода| |3632|Payment Constraint Invalid Weekly funding for MoneySend by Consumer cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт физических лиц в неделю|Можно повторить запрос позже, по истечении текущего 7-дневного периода| |3633|Payment Constraint Invalid Weekly funding for MoneySend by Small business cards|Средства не могут быть списаны, поскольку превышен лимит по количеству списаний с использованием платёжных карт для малого бизнеса в неделю|Можно повторить запрос позже, по истечении текущего 7-дневного периода| |3634|Payment Constraint Invalid 24 Hour for Payout mcc 7995, 9406 by Consumer cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт физических лиц в сутки для мерчанта с кодом MCC, соответствующим 7995 или 9406|Можно повторить запрос позже, по истечении суток| |3635|Payment Constraint Invalid Weekly for Payout mcc 7995, 9406 by Consumer cards|Средства не могут быть зачислены, поскольку превышен лимит по количеству зачислений с использованием платёжных карт физических лиц в неделю для мерчанта с кодом MCC, соответствующим 7995 или 9406|Можно повторить запрос позже, по истечении текущего 7-дневного периода| |3900|Payment Constraint 50000 USD Amount limit exceeded for Money transfer|Сумма списания или зачисления не может превышать `50 000 USD` для денежных переводов|Следует скорректировать запрос| |3901|Payment Constraint 25000 USD Amount limit exceeded for Money transfer|Сумма списания или зачисления не может превышать `25 000 USD` для денежных переводов|Следует скорректировать запрос| |9999|Awaiting processing|Ожидается окончание обработки запроса|Необходимо подождать| ## Коды от Risk Control System \(RCS\) {#section_fgg_scs_xzb .section} |Код|Сообщение|Описание|Действие| |---|---------|--------|--------| |1401|RCS reject. PAN is Blacklisted in RCS|PAN карты пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1402|RCS reject. Customer is Blacklisted in RCS|Пользователь в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1403|RCS reject. Cardholder is Blacklisted in RCS|Имя держателя карты в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1404|RCS reject. IIN is Blacklisted in RCS|IIN карты пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1405|RCS reject. IP is Blacklisted in RCS|IP-адрес пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1406|RCS reject. Email is Blacklisted in RCS|Электронный адрес пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1407|RCS reject. Phone is Blacklisted in RCS|Номер телефона пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1408|RCS reject. Card is compromised|Карта пользователя утеряна или украдена|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1409|RCS Reject. Interval too short|Превышен лимит на частоту операций|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1410|RCS reject. Domain is forbidden|Домен адреса электронной почты пользователя в чёрном списке RCS|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1411|RCS reject. Country is forbidden|Для данной страны выполнение операции запрещено|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1412|RCS reject. Country mismatch|Не совпадают данные по странам пользователя|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1413|RCS reject. Country limit exceeded|Превышен лимит стран, из которых выполнялись операции|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1414|RCS Reject. Country is forbidden for cross-border transaction|Для данной страны выполнение AFT-операции запрещено|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1415|RCS reject. Rejected by Scoring system|Операция отклонена как неблагонадёжная по результатам оценки через систему взвешенных коэффициентов|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1421|RCS reject. Invalid amount|Указанная сумма платежа вне допустимого диапазона|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1422|RCS reject. Amount limit exceeded|Превышен лимит суммы платежа|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1431|RCS reject. Allowed number of cards exceeded|Превышен лимит на количество карт, используемых для проведения платежа|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1432|RCS reject. Allowed number of emails exceeded|Превышен лимит на количество адресов электронной почты, используемых для проведения платежа|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1433|RCS reject. Count limit exceeded|Превышен лимит на количество операций|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1434|RCS reject. Duplicate operation|Предположительно дублирующийся платеж|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1435|RCS reject. Allowed number of users exceeded|Превышен лимит на количество разных идентификаторов пользователя|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1437|RCS reject. Allowed number of names exceeded|Превышен лимит на количество различающихся написаний имени пользователя, которые определяются системой RCS как имена разных держателей карт|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1441|RCS reject. Rejected by compliance restriction|Платёж отклонён согласно ограничениям законодательства|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1450|RCS reject. Rejected by sanctions lists|Платёж отклонён из-за совпадения с одним или несколькими санкционными списками лиц|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1451|RCS reject. Rejected by AML restriction|Платёж отклонён после AML-проверки|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1452|RCS reject. Rejected by AML UK sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML UK|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1453|RCS reject. Rejected by AML US sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML US|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1455|RCS reject. Rejected by AML phrase list|Платёж отклонён из-за совпадения имени держателя карты со списком запрещённых слов|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1456|RCS reject. Rejected by holdername format validation|Платёж отклонён из-за правил валидации имени держателей карты|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1457|RCS reject. Rejected by AML EU sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML EU|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1458|RCS reject. Rejected by AML UN sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML UN|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1459|RCS reject. Rejected by AML NL sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML NL|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1460|RCS reject. Rejected by AML UAE sanction list|Платёж отклонён из-за совпадения с санкционным списком лиц AML UAE|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1461|RCS reject. Restricted card product code|Код продукта переданной карты запрещён|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1462|RCS reject. Restricted card type|Тип переданной карты запрещён|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1463|RCS reject. Cardholder name mismatch|Отказ из-за несовпадения имён держателя карты|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |1499|RCS reject. Machine Learning recommendation|Операция отклонена как неблагонадёжная по результатам оценки с помощью искуственного интеллекта|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | ## Коды от внешних карточных платёжных систем {#section_pxs_scs_xzb .section} |Код|Сообщение|Описание|Действие| |---|---------|--------|--------| |10000|General decline|Выполнение операции отклонено платёжной системой по неизвестной причине|Можно попробовать еще раз| |10100|Declined by external provider|Выполнение операции отклонено платёжной системой без объяснения причины|Можно попробовать еще раз| |10101|Decline due to amount or frequency limit|Выполнение операции отклонено из-за превышения ограничений суммы или частоты платежа|Следует скорректировать запрос или Можно попробовать еще раз| |10110|Subscription is canceled by customer on the issuer side|Выполнение операции отклонено из-за отмены пользователем дальнейшего выполнения списаний в рамках повторяемой оплаты|Обязательных действий не требуется. Можно зарегистрировать новую повторяемую оплату | |101011|Decline due to amount limit|Выполнение операции отклонено из-за превышения ограничений суммы|Следует скорректировать запрос| |101012|Decline due to amount limit per period for the customer|Выполнение операции отклонено из-за превышения ограничений суммы для одного пользователя за установленный период|Можно повторить запрос позже| |101013|Decline due to frequency limit|Выполнение операции отклонено из-за превышения попыток проведения платежа|Можно повторить запрос позже| |101014|Too much declined operations per period for the customer|Выполнение операции отклонено из-за превышения отклонённых попыток проведения для одного пользователя за установленный период|Можно повторить запрос позже| |10102|Incorrect data entered|Выполнение операции отклонено по причине ввода некорректных данных карты|Следует скорректировать запрос| |101021|Incorrect PAN|Выполнение операции отклонено, так как введён недействительный номер карты|Следует скорректировать запрос| |10103|Incorrect PIN or CVV|Выполнение операции отклонено по причине ввода некорректного PIN или CVV карты|Следует скорректировать запрос| |10104|Incorrect 3DS password|Выполнение операции отклонено по причине ввода некорректного пароля 3DS|Можно попробовать еще раз| |10105|Insufficient funds on card|Выполнение операции отклонено из-за недостатка средств на счёте карты|Можно попробовать еще раз| |10106|Card expired|Выполнение операции отклонено по причине ввода некорректной даты окончания срока действия карты|Следует скорректировать запрос| |10107|Allowable PIN tries exceeded|Выполнение операции отклонено по причине многократного ввода некорректного PIN|Можно попробовать еще раз| |10108|Maestro MO/TO operation is prohibited for this country|Выполнение операции отклонено, так как страна проведения MO/TO оплаты не входит в список доступных|Следует скорректировать запрос| |10109|COF payment registration or customer payment data saving is not approved by external provider|Регистрация COF платежа или сохранение данных пользователя не подтверждены платёжной системой|Можно повторить запрос позже| |10110|Subscription is canceled by customer on the issuer side|Выполнение операции отклонено из-за отмены пользователем дальнейшего выполнения списаний в рамках повторяемой оплаты|Обязательных действий не требуется. Можно зарегистрировать новую повторяемую оплату | |10112|Insufficient Funds. Retry later|Выполнение операции отклонено из-за недостатка средств на счёте карты|Следует повторить запрос позже| |10113|Insufficient Funds. Do not retry|Выполнение операции отклонено из-за недостатка средств на счёте карты|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10114|Declined by 3DS Check|Выполнение операции отклонено по результатам проведения аутентификации 3‑D Secure|Можно повторить запрос позже| |10201|Refer to card issuer|Выполнение операции отклонено эмитентом|Можно рекомендовать пользователю следующие действия: - обратиться к эмитенту, чтобы уточнить характер и способы решения выявленной проблемы с картой - воспользоваться другим платёжным инструментом, чтобы провести искомый платёж | |10202|Issuer inoperative|Выполнение операции отклонено по причине недоступности эмитента карты|Можно попробовать еще раз| |10203|Pick-up card|Выполнение операции отклонено из-за получения особого ответа от банка о том, что карта скомпрометирована|Действий не требуется| |10204|Restrictions for the customer card|Выполнение операции отклонено по причине наложенных ограничений на карту пользователя. Пожалуйста, свяжитесь с эмитентом|Следует скорректировать запрос| |10205|Not enrolled for 3DS|Выполнение операции отклонено по причине того, что карта пользователя не поддерживает 3‑D Secure аутентификацию|Следует скорректировать запрос| |10206|Restrictions for the customer data|Выполнение операции для указанного пользователя заблокировано со стороны внешнего провайдера|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10301|Operation was cancelled|Выполнение операции отклонено участником процесса|Можно попробовать еще раз| |10401|Declined by PSP risk system|Выполнение операции отклонено риск-департаментом платёжной системы. Не показывайте данное сообщение пользователю|Следует скорректировать запрос| |10402|Suspicious operation|Выполнение операции отклонено антимошеннической системой платёжной системы|Действий не требуется| |10403|Fraud/Security. Try again using 3DS authentication|Выполнение операции отклонено антимошеннической системой платёжной системы, так как необходима аутентификация 3‑D Secure|Следует выполнить процедуру аутентификации 3‑D Secure| |10404|Suspected fraud. Do not try again|Выполнение операции отклонено антимошеннической системой платежной системы|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10405|Fraud or closed account. Do not try again|Выполнение операции отклонено антимошеннической системой платёжной системы|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10501|Refer to acquirer|Выполнение операции отклонено из-за некорректного взаимодействия с платёжной системой|Следует связаться со службой технической поддержки| |10502|Error during operation validation|Выполнение операции отклонено во время проведения процесса валидации данных|Следует скорректировать запрос| |10503|Incorrect acquirer settings|Выполнение операции отклонено из-за некорректных настроек. Пожалуйста, свяжитесь с эквайером|Следует связаться со службой технической поддержки| |10504|Insufficient funds on acquirer balance|Выполнение операции отклонено из-за недостатка средств на счёте эквайера|Следует связаться со службой технической поддержки| |10505|PSP system is inoperative|Выполнение операции отклонено по причине недоступности платёжной системы. Пожалуйста, попробуйте отправить запрос позднее|Можно попробовать еще раз| |10601|Try again|Выполнение операции отклонено. Пожалуйста, попробуйте отправить запрос повторно|Можно попробовать еще раз| |10602|Time-out|Выполнение операции отклонено из-за истечения времени ожидания. Пожалуйста, попробуйте отправить запрос повторно|Можно попробовать еще раз| |10603|Operation could not be authorized. Try again later|Операция не может быть проведена в данный момент. Пожалуйста, попробуйте отправить запрос позднее|Можно попробовать еще раз| |10701|Wrong requests sequence|Выполнение операции отклонено по причине некорректной последовательности отправки запросов|Следует скорректировать запрос| |10702|Invalid request|Выполнение операции отклонено по причине некорректного формата запроса|Следует связаться со службой технической поддержки| |10703|Incorrect eci|Выполнение операции отклонено, так как эквайером получен некорректный код ECI|Следует связаться со службой технической поддержки| |10704|Card holder not found|Выполнение операции отклонено, так как не передан обязательный для эквайера параметр с именем держателя карты|Следует связаться со службой технической поддержки| |10705|The request contains no fields of the customer object|Выполнение операции отклонено, так как не переданы обязательные для эквайера параметры с информацией о пользователе|Следует связаться со службой технической поддержки| |10706|Refund unavailable for current operation|Проведение возврата отклонено эквайером|Следует связаться со службой технической поддержки| |10707|Required rental information is not present|Выполнение операции отклонено, так как не переданы параметры с информацией об аренде|Следует связаться со службой технической поддержки| |10708|Required flight details is not present|Выполнение операции отклонено, так как не переданы параметры с информацией о рейсе|Следует связаться со службой технической поддержки| |10709|Additional customer 3‑D Secure authentication required|Выполнение операции отклонено эмитентом, так как пользователь не прошел проверку 3‑D Secure|Следует связаться со службой технической поддержки| |10722|Strong Customer Authentication mandated according to PSD2|Выполнение операции отклонено, так как не была выполнена аутентификация, соответствующая требованиям SCA \(Strong Customer Authentication\)|Следует связаться со службой технической поддержки| |10801|External provider approved but did not process the operation|Платежная система подтвердила, но не провела операцию|Следует связаться со службой технической поддержки| |10805|Life cycle \(Mastercard use only\)|Выполнение операции отклонено эмитентом, так как номер карты или окончание срока действия карты указаны некорректно|Попробуйте изменить запрос перед повторной отправкой| |10806|Policy \(Mastercard use only\)|Выполнение операции отклонено эмитентом|Пожалуйста, свяжитесь со службой технической поддержки| |10807|Fraud/Security|Выполнение операции отклонено эмитентом из-за подозрения в мошенничестве|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10810|Life cycle. Do not try again|Выполнение операции отклонено эмитентом, так как номер карты или окончание срока действия карты указаны некорректно|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10811|Policy. Do not try again|Выполнение операции отклонено эмитентом|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |10812|Invalid card. Do not try again|Выполнение операции отклонено эмитентом|Обязательных действий не требуется. Для получения информации о возможных дальнейших действиях можно связаться со специалистами технической поддержки | |19999|Awaiting processing|Ожидается окончание обработки запроса на стороне платёжной системы. Пожалуйста, подождите|Необходимо подождать| ## Коды от внешних альтернативных платёжных систем {#section_qsg_tcs_xzb .section} |Код|Сообщение|Описание|Действие| |---|---------|--------|--------| |20000|General decline|Выполнение операции отклонено по неизвестной причине|Можно попробовать еще раз| |20100|Declined by external provider|Выполнение операции отклонено платежной системой без объяснения причины|Можно попробовать еще раз| |20101|Decline due to amount or frequency limit|Выполнение операции отклонено из-за превышения ограничений суммы или частоты платежа|Следует скорректировать запрос или Можно попробовать еще раз| |201011|Decline due to amount limit|Выполнение операции отклонено из-за превышения ограничений суммы|Следует скорректировать запрос| |201012|Decline due to amount limit per period for the customer|Выполнение операции отклонено из-за превышения ограничений суммы для одного пользователя за установленный период|Можно повторить запрос позже| |201013|Decline due to frequency limit|Выполнение операции отклонено из-за превышения попыток проведения платежа|Можно повторить запрос позже| |201014|Too much declined operations per period for the customer|Выполнение операции отклонено из-за превышения отклоненных попыток проведения для одного пользователя за установленный период|Можно повторить запрос позже| |20102|Incorrect account data entered|Выполнение операции отклонено по причине ввода пользователем некорректных данных аккаунта|Следует скорректировать запрос| |20103|Incorrect login or password|Выполнение операции отклонено по причине ввода пользователем некорректных данных для входа в аккаунт|Следует скорректировать запрос| |20104|Password attempts entry exceeded|Выполнение операции отклонено по причине многократного ввода пользователем некорректного пароля для входа в аккаунт|Можно попробовать еще раз| |20105|Insufficient funds on customer account|Выполнение операции отклонено из-за недостатка средств на счете аккаунта пользователя|Можно попробовать еще раз| |20106|Customer account is no longer available|Выполнение операции отклонено по причине того, что аккаунт пользователя истек или недоступен|Следует скорректировать запрос| |20107|Customer account does not support requested currency|Выполнение операции отклонено по причине того, что аккаунт пользователя не поддерживает указанную валюту|Попробуйте изменить запрос перед повторной отправкой| |20109|COF payment registration or customer payment data saving is not approved by external provider|Регистрация COF платежа или сохранение данные пользователя не подтверждены платежной системой|Можно повторить запрос позже| |20201|Restrictions for the customer account|Выполнение операции отклонено по причине наложенных ограничений на аккаунт пользователя. Пожалуйста, свяжитесь с платежной системой|Следует скорректировать запрос| |20202|PSP system is unavailable|Выполнение операции отклонено по причине недоступности платежной системы. Пожалуйста, попробуйте отправить запрос позднее|Можно попробовать еще раз| |20203|Compromised customer account|Выполнение операции отклонено из-за получения особого ответа от банка о том, что аккаунт пользователя скомпрометирован|Действий не требуется| |20204|Crediting this customer account is blocked|Выполнение операции отклонено. Выплата на аккаунт пользователя невозможна. Пожалуйста, свяжитесь с внешней платежной системой|Следует скорректировать запрос| |20205|Payment method is not available for customer country|Платежный метод недоступен для страны пользователя|Действий не требуется| |20206|Difficulties on the mobile operator side|Выполнение операции отклонено из-за технических проблем на стороне мобильного оператора|Можно повторить запрос позже| |20301|Account owner cancelled operation|Выполнение операции отклонено владельцем аккаунта|Можно попробовать еще раз| |20302|Unacceptable password|Пароль не отвечает требуемым параметрам. Пожалуйста, попробуйте другой|Следует скорректировать запрос| |20303|Customer is not permitted to perform the action|Невозможно выполнить запрос, так как недостаточно прав|Следует скорректировать запрос| |20304|Incorrect amount paid|Выполнение операции отклонено из-за неверной суммы, оплаченной пользователем|Попробуйте отправить запрос повторно| |20401|Declined by PSP risk system|Выполнение операции отклонено риск-департаментом платежной системы. Не показывайте данное сообщение пользователю|Следует скорректировать запрос| |20402|Suspicious operation|Выполнение операции отклонено антимошеннической системой платежной системы|Отказ риск-системой| |20450|The Verification of Payee cannot be performed due to technical reasons.|Инициированная проверка Verification of Payee не может быть выполнена из-за ошибок при взаимодействии платформы и сервиса провайдера|Можно попробовать повторить операцию через несколько минут При повторении ошибки следует связаться со службой технической поддержки | |20451|Payout or refund cannot be processed based on the Verification of Payee result.|Инициированная операция не может быть выполнена из-за несоответсвия итогового статуса проверки Verification of Payee одному из одобренных вариантов \([подробнее](ru_verification_of_payee.md)\)|Можно уведомить пользователя о несоответствии в написании указанного имени и имени владельца счёта и предложить повторить попытку, уточнив имяПри повторении ошибки можно связаться со службой технической поддержки | |20501|Refer to acquirer|Выполнение операции отклонено из-за некорректного взаимодействия с платежной системой|Следует связаться со службой технической поддержки| |20502|Error during operation validation|Выполнение операции отклонено во время проведения процесса валидации данных|Следует скорректировать запрос| |20503|Incorrect acquirer settings|Выполнение операции отклонено из-за некорректных настроек. Пожалуйста, свяжитесь с эквайером|Следует связаться со службой технической поддержки| |20504|Insufficient funds on acquirer balance|Выполнение операции отклонено из-за недостатка средств на счете эквайера|Следует связаться со службой технической поддержки| |20601|Try again|Выполнение операции отклонено. Пожалуйста, попробуйте отправить запрос повторно|Можно попробовать еще раз| |20602|Time-out|Выполнение операции отклонено из-за истечения времени ожидания. Пожалуйста, попробуйте отправить запрос повторно|Можно попробовать еще раз| |20603|Operation could not be authorized. Try again later|Операция не может быть проведена в данный момент. Пожалуйста, попробуйте отправить запрос позднее|Можно попробовать еще раз| |20604|Notification is not delivered|Выполнение операции отклонено. Невозможно доставить оповещение|Следует связаться со службой технической поддержки| |20701|Wrong requests sequence|Выполнение операции отклонено по причине некорректной последовательности отправки запросов|Следует скорректировать запрос| |20702|Invalid request. Try again|Выполнение операции отклонено по причине некорректного формата запроса|Следует связаться со службой технической поддержки| |20703|Invoice not found|Выполнение операции отклонено по причине получения неверного invoice\_id|Следует связаться со службой технической поддержки| |20705|Merchant account is blocked|Аккаунт мерчанта заблокирован|Следует связаться со службой технической поддержки| |20706|Operation not supported by provider|Выполнение данной операции не поддерживается провайдером|Следует связаться со службой технической поддержки| |20801|Payment provider approved but did not process the operation|Платежная система подтвердила, но не провела операцию|Следует связаться со службой технической поддержки| |20802|The payment provider did not confirm neither successful nor negative status of the payment transaction|Платежная система не может подтвердить статус платежа|Необходимо подождать, действий не требуется| |20812|The service provider did not confirm the account crediting|Выполнение операции отклонено, потому что платёжная система не подтвердила зачисление средств на счёт пользователя|Можно попробовать еще раз| |20899|The payment is processed on the provider side. It can take up to several days. Inform customer if needed.|Платёж обрабатывается на стороне провайдера или платёжной системы. Обработка может занимать вплоть до нескольких дней. Если актуально, стоит уведомить об этом пользователя|Дополнительных действий по взаимодействию с платформой не требуется| |29999|Awaiting processing|Ожидается окончание обработки запроса на стороне платежной системы. Пожалуйста, подождите|Необходимо подождать, действий не требуется| ## Коды от веб-сервиса мерчанта {#section_t4r_tcs_xzb .section} |Код|Сообщение|Описание|Действие| |---|---------|--------|--------| |30000|Operation was declined by merchant|Выполнение операции отклонено мерчантом|Действий не требуется| |30100|Operation was declined by merchant for an unknown reason|Выполнение операции отклонено мерчантом без объяснения причины|Действий не требуется| |30301|Merchant did not confirm operation processing|Мерчант не подтвердил выполнение операции|Действий не требуется| |30302|Merchant did not respond during the operation confirmation process|Не получен ответ от мерчанта в процессе подтверждения операции|Действий не требуется| |30303|The amount or currency confirmed by the merchant is different from the requested one|Сумма или валюта, подтвержденная мерчантом, отличается от запрошенной|Действий не требуется| |30401|Empty draws list|Список сумм, доступных к оплате, пустой|Действий не требуется| **На уровень выше:**[Работа с информацией о платежах](ru_platform_payment_information.md) --- # Payment Page {#ru_PP_about .concept} раздел с материалами о работе с платёжной формой Payment Page В этом разделе представлены материалы о работе с платёжной формой Payment Page. ## Обзор {#section_dkz_lr1_btb .section} Вводная статья с информацией о платёжной форме, общей схемой её использования и обзором возможностей — [Общая информация](ru_PP_general.md). ## Интеграция {#section_tjy_s2b_dbb .section} Материалы о том, как подключить Payment Pageв общем случае и в отдельных частных: - [Быстрый старт](ru_pp_quickstart.md)— о том, как оперативно организовать приём платежей с максимальным использованием готовых решений, таких как SDK и примеры исходного кода. - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как строится работа с платёжной платформой через Payment Page и как можно организовывать эту работу со стороны веб-сервиса в различных случаях. - [Интеграция с использованием SDK](ru_sdk_overview.md)— о том, как применять SDK для мобильных приложений иработы с подписью. - [Интеграция с использованием плагинов](ru_CMS.md)— о том, как встраивать платёжную форму в сайты на базе различных CMS и профильных платформ с помощью плагинов. - [Встраивание облегчённой редакции Payment Page для карточных платежей](ru_pp_microframe_solution.md)— о том, как встраивать в веб-сервис облегчённую редакцию платёжной формы для классических карточных платежей. - [Встраивание кнопок для платежей с использованием методов Apple Pay и Google Pay](ru_pp_embedded_payment_buttons.md)— о том, как встраивать в веб-сервис кнопки для „быстрых“ платежей с использованием методов Apple Pay и Google Pay, с поддержкой возможностей сбора сведений о пользователе и указания параметров доставки на стороне сервисов этих методов. ## Управление формой {#section_hh3_ms1_btb .section} Материалы о разных способах работы платёжной формы и управления ими: - [Способы открытия платёжной формы](ru_PP_Integration.md)— о вариантах открытия платёжной формы, в том числе в отдельной вкладке, модальном окне и объекте iframe. - [Способы перенаправления пользователей к сторонним сервисам](ru_PP_pm_redirect_mode.md)— о вариантах открытия вспомогательных страниц при работе с разными платёжными методами. - [Способы возвращения пользователей к веб-сервису](ru_PP_redirect_modes.md)— о вариантах перенаправления пользователей с платёжной формы к веб-сервису по заданным адресам. ## Основные действия {#section_tqt_nt1_btb .section} Материалы об основных действиях, которые можно выполнять с помощью платёжной формы, с описанием пользовательских сценариев и форматов запросов и оповещений: - [Проведение оплат](ru_pp_purchase.md)— о проведении оплат с незамедлительным списанием средств. - [Блокировка средств](ru_pp_purchase_auth.md)— о выполнении блокировки средств в рамках двухстадийной оплаты. - [Регистрация повторяемых оплат](ru_pp_recurring.md)— о регистрации оплат с последующими списаниями. - [Проведение выплат](ru_pp_payout.md)— о проведении выплат. - [Проверка платёжных инструментов](ru_pp_account_verification.md)— о выполнении условного списания или блокировки средств с целью проверки действительности платёжного инструмента. - [Формирование токенов](ru_pp_token.md)— о вызове платёжной формы для регистрации платёжных данных и формировании их токена. ## Дополнительные возможности {#section_lll_nv1_btb .section} Материалы о различных возможностях, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг — [Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md)и [Индивидуальное оформление](ru_PP__design_customisation.md). ## Параметры вызова {#section_ow3_b3l_pjc .section} Спецификация с описанием структуры параметров, которые могут использоваться в запросах на открытие платёжной формы Payment Page — [Спецификация Payment Page API](ru_PP_Parameters.md). - **[Общая информация](ru_PP_general.md)** статья с вводной информацией о платёжной форме Payment Page, общей схемой её использования и обзором её возможностей - **[Быстрый старт](ru_pp_quickstart.md)** инструкция по оперативной организации приёма платежей через Payment Page, с использованием SDK и примеров исходного кода - **[Организация взаимодействия](ru_pp_interaction_organisation.md)** статья о том, как строится работа с платёжной платформой через Payment Page и как можно организовывать эту работу со стороны веб-сервиса в различных случаях - **[Интеграция с использованием SDK](ru_sdk_overview.md)** статьи о порядке применения SDK для интеграции Payment Page в мобильные приложения и для создания и проверки подписи к данным - **[Интеграция с использованием плагинов](ru_CMS.md)** статьи о порядке применения плагинов для встраивания Payment Page в сайты на базе различных CMS и профильных платформ - **[Встраивание облегчённой редакции Payment Page для карточных платежей](ru_pp_microframe_solution.md)** статья о порядке работы с облегчённой редакцией платёжной формы Payment Page для классических карточных платежей - **[Встраивание кнопок для платежей с использованием методов Apple Pay и Google Pay](ru_pp_embedded_payment_buttons.md)** статья о порядке работы со специализированной редакцией платёжной формы Payment Page для глубокой интеграции с сервисами Apple Pay и Google Pay - **[Управление формой](ru_pp_ux_configuration.md)** статьи о способах работы основной редакции платёжной формы Payment Page, включая способы её открытия, перенаправления от неё к сторонним сервисам и возвращения к веб-сервису, а также о возможностях управления этими способами работы - **[Основные действия](ru_pp_basic_actions.md)** статьи об основных действиях, которые можно выполнять с помощью платёжной формы, с описанием пользовательских сценариев, а также форматов запросов и оповещений, актуальных при работе с классическими карточными платежами - **[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md)** статьи о вспомогательных процедурах и дополнительных возможностях Payment Page, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг - **[Индивидуальное оформление](ru_PP__design_customisation.md)** статья о возможностях оформлять платёжную форму Payment Page с помощью специализированного конструктора, встроенного в интерфейс Dashboard - **[Спецификация Payment Page API](ru_PP_Parameters.md)** спецификация с описанием структуры параметров, которые могут использоваться в запросах на открытие платёжной формы Payment Page --- # Общая информация {#ru_PP_general .concept} статья с вводной информацией о платёжной форме Payment Page, общей схемой её использования и обзором её возможностей **На уровень выше:**[Payment Page](ru_PP_about.md) ## Введение {#ru_pp_general_introduction} Payment Page — это платёжная форма от Ecommpay: гибко конфигурируемый программный модуль с пользовательским интерфейсом, который позволяет проводить оплаты, выплатыи выполнять другие действия с применением различных платёжных методов.Payment Page может использоваться на сайтах и в мобильных приложениях и позволяет работать с платёжными картами даже при отсутствии у мерчанта сертификата PCI DSS. ![](images/ru_functional_pp.svg) Вызов Payment Page осуществляется через API, и со стороны мерчанта может использоваться как сам API, так и специализированные компоненты, облегчающие работу с ним: подключаемая JavaScript-библиотека, SDK для проектов на разных языках программирования и подключаемые модули для сайтов на базе ряда распространённых CMS. Такое разнообразие технических решений позволяет оперативно настраивать работу с Payment Page в самых разных проектах. Открытие Payment Page на пользовательском устройстве может выполняться в отдельной вкладке браузера, в модальном окне и в объекте iframe HTML-страницыс использованием типового или индивидуального оформления. Конкретный способ открытия, а также способы выполнения промежуточных действий и отображения итоговой информации можно задавать при вызове формы. И это разнообразие, в свою очередь, позволяет гибко подстраивать работу Payment Page под самые разные пользовательские сценарии. ![](images/ecommpay/ru_pp_general_1.svg "Payment Page в объекте iframe HTML-страницы") ![](images/ecommpay/ru_pp_general_2.svg "Payment Page в модальном окне поверх HTML-страницы") ![](images/ecommpay/ru_pp_general_3.svg "Payment Page в виде отдельной HTML-страницы, в текущей или новой вкладке браузера") Далее в этом разделе представлены основные сведения о схеме работы и возможностях Payment Pageс эмулированием её работы в различных ситуациях. ## Схема работы {#ru_pp_general_interaction} При работе с Payment Page все взаимодействия с платёжной платформой — со стороны пользовательского устройства и серверной части веб-сервиса — выполняются с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2, а в качестве пользовательского браузера могут использоваться актуальные версии таких браузеров, как Google Chrome, Safari, Opera, Mozilla Firefox, Microsoft Edge, QQ Browser, Mi Browser, Samsung Internet, 360 Secure Browser и ряда других. Подробную информацию о работе Payment Page в разных средах можно получить у специалистов технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). Для описания общей схемы работы полезно разграничивать пользователя, клиентскую и серверную части веб-сервиса, платёжную платформу, Payment Page и платёжную среду. ![](images/ru_paymentpage_functional.svg "Схема взаимодействия") В общем случае работа с Payment Page строится следующим образом: 1. Пользователь инициирует вызов платёжной формы в пользовательском интерфейсе веб-сервиса, с помощью кнопки оплаты или иным заданным способом. 2. В клиентской части веб-сервиса формируется набор параметров вызова Payment Page и передаётся к серверной части. 3. В серверной части веб-сервиса при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад в клиентскую часть. При этом важно, чтобы подписывался именно итоговый набор параметров, с учётом всех требований API и предпочтений по вызову платёжной формы: иначе запрос не будет корректным. 4. На стороне клиентской части веб-сервиса выполняются формирование запроса на открытие Payment Page и отправка этого запроса в платёжную платформу. 5. На стороне платёжной платформы выполняются подготовка Payment Page с учётом параметров вызова и передача к пользовательскому устройству данных для отображения формы. 6. Платёжная форма отображается в пользовательском интерфейсе. 7. Пользователь выполняет необходимые действия в платёжной форме: выбирает платёжный метод \(если он не был задан при вызове\),указывает реквизиты и другую информацию и подтверждает готовность провести оплатуили выполнить другое целевое действие \(например, проверить карту\). 8. От Payment Page к платёжной платформе отправляется запрос на выполнение целевого действия с учётом всех данных, введённых пользователем. 9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам. 10. В платёжной среде, на стороне требуемых систем, выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 11. В платёжной платформе обрабатывается итоговая информация, после чего на заданный URL мерчанта отправляется программное оповещение о результате \(как и при работе с другими интерфейсами платёжной платформы\). 12. Информация о результате передаётся из платёжной платформы в Payment Page. 13. Информация о результате отображается в пользовательском интерфейсе в соответствии с заданными настройками: на странице Payment Page или на странице веб-сервиса, к которой выполняется перенаправление. Эта схема отображает ключевые моменты со стороны мерчанта, но в отдельных случаях может варьироваться в части промежуточных взаимодействий между пользователем, Payment Page, платёжной платформой и сервисами платёжной среды на шагах 7–10.Так, при проведении платежей возможны дополнительные взаимодействия, например для выполнения аутентификации 3‑D Secure или для подтверждения платежа в сервисе альтернативной платёжной системы, апри вызове Payment Page для сохранения платёжных данных на шаге 9 не регистрируется платёж и опускается шаг 10. Подобные нюансы влияют на пользовательские сценарии, и, с одной стороны, при выполнении промежуточных взаимодействий на шагах 7–10 не требуется никаких дополнительных действий со стороны веб-сервиса, а с другой стороны, за счёт подбора параметров вызова Payment Page на шагах 2–3 можно существенно влиять на то, с чем и как сталкивается пользователь. Чтобы конфигурировать работу с платёжной формой под потребности конкретного проекта, можно использовать описанные далее возможности и совместно со специалистами технической поддержки Ecommpay настраивать оптимальные сценарии. Базовый пользовательский сценарий можно представить следующим образом: 1. Пользователь подтверждает готовность оплатить свой заказ, переходит на Payment Pageи выбирает метод оплаты. \(При этом выполняются шаги 1–6 и частично шаг 7 общей схемы взаимодействия.\) ![](images/ecommpay/ru_pp_general_4.svg) 2. Пользователь указывает необходимые реквизитыплатёжного инструмента, подтверждает готовность провести оплату выбранным способом и ожидает информацию о результате. \(При этом выполняются шаги 7–12 общей схемы взаимодействия.\) ![](images/ecommpay/ru_pp_general_5.svg) 3. Пользователь получает информацию о результате оплаты. \(При этом выполняется шаг 13 общей схемы взаимодействия.\) ![](images/ecommpay/ru_pp_general_6.svg) Технически в рамках описанной схемы со стороны мерчанта могут использоваться как исключительно свои решения для вызова Payment Page и разбора программных оповещений, так и решения с использованием компонентов Ecommpay. К таким компонентам относятся: - Подключаемая JavaScript-библиотека. Она подключается к клиентской части веб‑сервиса и поддерживает разные способы вызова платёжной формы \(при выполнении шага 4\)и обработку событий в пользовательском интерфейсе, в том числе для работы со встроенными в интерфейс веб-сервиса кнопками для „быстрых“ платежей с использованием методов Apple Pay и Google Pay. - Наборы средств разработки \(SDK\) для веб-сервисов, разработанных на разных языках программирования. Они встраиваются в серверную часть веб-сервиса и позволяют формировать подпись \(при выполнении шага 3\) и обрабатывать оповещения \(передаваемые на шаге 11\). - Наборы средств разработки для мобильных приложений, работающих на платформах Android и iOS. Они встраиваются в клиентскую часть приложения и позволяют работать с платёжной формой, адаптированной под мобильные интерфейсы \(с поддержкой шагов 2 и 4 и без необходимости использования браузера на шагах 6–13\). - Подключаемые модули для сайтов на базе ряда распространённыхCMS. Они подключаются в административной панели CMS и обеспечивают все необходимые действия как в клиентской, так и в серверной части сайта, без необходимости программирования со стороны мерчанта. Наконец, важным дополнением к приведённой схеме является информация о контроле работы Payment Page со стороны мерчанта. По умолчанию индикация открытия платёжной формы и действий с ней не используется, но такую индикацию можно настроить. При использовании JavaScript-библиотеки Ecommpay можно получать и обрабатывать информацию об открытии формы или об ошибке при её открытии, о подтверждении операции или о закрытии формы, а также о других интерфейсных событиях. А после подтверждения целевого действия в Payment Page и регистрации платежа в платёжной платформе для получения информации о состоянии этого платежа можно использовать запросы через Gate и средства интерфейса Dashboard. ## Возможности {#ru_pp_general_capabilities} ### Поддержка разных целевых действий {#section_jzp_qby_mlb .section} С помощью Payment Page можно решать следующие задачи: - *Проведение оплат.* Это наиболее распространённый вариант использования платёжной формы — с проведением оплат в одну стадию, при которых в рамках одного сеанса работы Payment Page осуществляется разовый перевод денежных средств от пользователя к мерчанту, например за совершаемую покупку. - *Блокировка средств.* При таком варианте использования в рамках сеанса работы Payment Page осуществляется блокировка денежных средств на счёте пользователя, и мерчант получает возможность уже в дальнейшем \(через Gate или Dashboard либо автоматически по истечении заданного периода\) списать нужную сумму или вернуть деньги пользователю. Это может быть актуально, например, при бронировании номера в отеле или аренде автомобиля. - *Регистрация повторяемых списаний.* При выстраивании долгосрочных отношений с пользователями могут быть удобны неоднократные списания средств без указания платёжных реквизитов или вовсе без пользовательского участия \(например, при платежах по подписке\). В платёжной платформе для этого поддерживаются повторяемые оплаты, и с помощью Payment Page можно регистрировать все типы этих оплат — регулярные, автоматические и экспресс \(OneClick\) — указывая соответствующие параметры при вызове платёжной формы. - *Проведение выплат.* Этот вариант использования позволяет переводить денежные средства от мерчанта к пользователю с предварительной регистрацией таких переводов через Gate. - *Проверка платёжных инструментов.* Этот вариант использования позволяет подтвердить возможность работы с конкретным платёжным инструментом\(как правило, картой\), например для последующего проведения выплаты пользователю. В рамках сеанса работы Payment Page при этом осуществляется один условный \(нулевой\) перевод денежных средств от пользователя к мерчантуили одна реальная \(ненулевая\) блокировка средств пользователя с последующей отменой. - *Сохранение платёжных данных.* При таком варианте использования в рамках сеанса работы Payment Page не проводится никаких финансовых операций, даже условных на нулевую сумму, но регистрируется информация о платёжном инструменте пользователя и для этой информации создаётся безопасный идентификатор — токен. Работа с токенами актуальна для платёжных карт и позволяет сохранять платёжные данные пользователя, например при его регистрации в веб-сервисе, и использовать эти данные в дальнейшем для проведения оплат и выплатс упрощёнными пользовательскими сценариями. Конкретное целевое действие задаётся через параметры вызова Payment Page и определяет основу сценария работы с платёжной формой. При этом в рамках разных сценариев допустимы различные вариации: с указанием и сохранением платёжных данных, со сбором дополнительной информации и использованием иных возможностей, представленных далее. ### Поддержка разных способов указания данных {#section_uf5_gwn_nlb .section} При использовании Payment Page поддерживаются разные способывыбора платёжного методаиуказания платёжных данных. *Платёжный метод* может быть выбран одним из следующих способов: - *На форме из всех доступных.* Это базовый вариант, при котором пользователь выбирает метод из числа всех, подключённых мерчанту в рамках используемого проекта. - *На форме из заданных.* В каких-то случаях, например с учётом региональных особенностей, может быть актуально отобразить пользователю не все, а только некоторые из подключённых методов. Тогда нужное подмножество задаётся в параметрах вызова Payment Page, и пользователь выбирает из этого подмножества. - *Вне формы до её вызова.* В некоторых ситуациях выбор платёжного метода может быть сделан на стороне веб-сервиса до вызова Payment Page \(в «корзине», например\). Тогда целевой метод задаётся в параметрах вызова Payment Page, и пользователь начинает работу с платёжной формойс указания реквизитов, минуя выбор метода. *Платёжные данные* могут быть указаны одним из следующих способов: - *Через ввод на форме.* В этом случае пользователь обязательно заполняет на форме все требуемые поля. Для карт из числа таких полей можно исключить имя держателя карты, по согласованию с курирующим менеджером Ecommpay, после анализа и оценки рисков. - *Через выбор или ввод на форме.* В этом варианте, когда при вызове Payment Page был указан идентификатор пользователя, пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем. В дополнение к выбранным реквизитам для некоторых инструментов требуется подтверждение, такое как ввод проверочного кода \(CVC, CVV, CID\) при работе с платёжными картами. - *Через выбор до вызова формы.* В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты, и платёжная форма открывается с указанием всех реквизитов кроме проверочного кода \(CVC, CVV, CID\), который необходимо указать непосредственно на форме. Помимо этих способов, при которых с платёжной формой взаимодействует пользователь, Payment Page может использоваться *для проведения платежей MO/TO*, при которых *с формой работает сотрудник мерчанта*, принимающий заказ пользователя. Тип такого заказа \(Mail Order или Telephone Order\) указывается при вызове Payment Page и учитывается в сценарии взаимодействия с формой. ### Поддержка дополнительных функций {#section_bh5_hwn_nlb .section} В дополнение к базовым сценариям \(в каждом из которых так или иначе присутствуют выбор платёжного метода,указание данных и последующие обязательные шаги\) при выполнении целевых действий в Payment Page можно использовать следующее: - *Выбор валюты платежа пользователем.* При использовании этой функциональности пользователь может выбрать на форме одну из заданных валют для проведения платежа. И далее, если требуется, на стороне платёжной платформы выполняется конвертация по актуальному курсу. - *Сбор дополнительной информации о пользователе.* Эта функциональность позволяет использовать на платёжной форме дополнительные поля, например для указания адреса, номера телефона и даты рождения пользователя. Состав таких полей можно выбирать из числа поддерживаемых в платформе, а среди выбранных можно определять обязательные и необязательные к заполнению пользователем. - *Предоставление повторных попыток ввода данных.* При использовании этой функциональности в случае ошибки при выполнении целевого действия пользователю отображается соответствующее сообщение \(например, о недостатке средств на балансе указанной карты\) и предложение повторить попытку.И далее, если пользователь соглашается попробовать ещё раз, он можетвыбрать тот же или иной платёжный метод и не вводить повторно данные, введённые им при предыдущей попытке. - *Каскадное проведение платежей.* Эта функциональность схожа с повторными попытками ввода данных: если что-то пошло не так, то пользователь может попробовать ещё раз. Но в этом случае обеспечивается защита не от ошибок со стороны пользователя, а от ошибок и сбоев со стороныпровайдеров и платёжных систем. Для этого, в соответствии с заданными настройками, последовательно выполняются дополнительные попытки проведения платежа через резервные платёжные системыили провайдеров. - *Отправка уведомлений пользователю.* Использование этой функциональности позволяет отправлять уведомления о проведении платежей на электронную почту пользователя. При этом можно настраивать состав и формат отправляемых писем, а также использовать разные шаблоны для разных типов и статусов операций \(это, прежде всего, актуально для статусов `success` и `decline`\). Все эти функции подключаются и настраиваются совместно со специалистами технической поддержки по согласованию с курирующим менеджером Ecommpay, что позволяет общими усилиями подобрать и адаптировать лучшее решение к каждой конкретной ситуации. ### Выполнение вспомогательных процедур {#section_v1n_3wn_nlb .section} Для проведения платежей могут требоваться вспомогательные процедуры, такие как аутентификация держателя карты со стороны эмитента. Необходимость выполнения этих процедур, как правило, зависит от протоколов и правил провайдеров иплатёжных систем, но в какой-то части могут учитываться и предпочтения мерчанта. И эти предпочтения стоит согласовывать с курирующим менеджером Ecommpay. В остальном при работе с Payment Page со стороны мерчанта не требуется каких-либо действий по таким процедурам. Но вполне полезно знать об их наличии и о том, когда и как это касается пользователей. К поддерживаемым в работе Payment Page вспомогательным процедурам относятся: - *Аутентификация 3‑D Secure.* Эта аутентификация \(Three-Domain Secure\) применяется при работе с платёжными картами для защиты от мошенничества. В пользовательском сценарии при выполнении аутентификации 3‑D Secure либо выполняется перенаправление к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\). - *Аутентификация по инициативе мерчанта.* Эта аутентификация поддерживается со стороны некоторых провайдеров и по желанию мерчанта может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения. Такое может быть актуально, когда, например, со стороны эмитента применяются недостаточно надёжные методы подтверждения подлинности пользователя. В пользовательском сценарии при выполнении аутентификации по инициативе мерчанта отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. - *Проверка адреса пользователя \(Address Verification Service, AVS\).* Эта проверка призвана обеспечить дополнительный уровень защиты от мошенничества при работе с платёжными картами за счёт сопоставления адреса, указанного при проведении конкретного платежа, с адресом, зарегистрированным для держателя указанной карты на стороне эмитента. Проверка адреса обязательна для операций, совершаемых на территории Великобритании, и также может применяться в США, Австралии, Канаде и Новой Зеландии. В пользовательском сценарии для выполнения такой проверки обязательными для указания становятся почтовый индекс и адрес. - *Дополнение информации о платеже.* Эта процедура позволяет проводить платежи в тех случаях, когда со стороны платёжной системы или провайдера запрашиваются дополнительные данные, которые необязательны в общем случае, но необходимы в конкретной ситуации. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. В пользовательском сценарии при выполнении этой процедуры отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на форме. И после заполнения этих полей проведение платежа продолжается стандартным образом. При наличии вопросов о выполнении вспомогательных процедур всегда можно обращаться к соответствующим разделам документации и к специалистам технической поддержки Ecommpay. ### Поддержка разных вариантов отображения итоговой информации {#section_ytj_jwn_nlb .section} При работе с Payment Page информацию о результате целевого действия можно отображать как *в платёжной форме*, так и *в веб-сервисе*. - В первом случае используется типовая итоговая страница, с сообщением о том, что действие выполнено \(и его статус — `success`\) или отклонено \(и его статус — `decline`\), и с кнопкой возвращения к веб-сервису, если это необходимо. - Во втором случае итоговая страница Payment Page не используется и пользователь сразу перенаправляется к веб-сервису, где может получать итоговую информацию в произвольной форме — в соответствии с предпочтениями мерчанта и логикой работы веб-сервиса. При этом конкретный способ — отобразить итоговую страницу Payment Page без кнопки перенаправления или с таковой либо сразу перенаправить к веб-сервису — можно задавать в параметрах вызова платёжной формы, а для адресации перенаправлений можно использовать адреса, заданные по умолчанию или указанные непосредственно при вызове формы, как одинаковые, так и разные для статусов `success` и `decline`. Такое многообразие решений позволяет обеспечивать необходимую вариативность и отображать разные итоговые страницы для разных целевых действий, регионов работы, групп пользователей и так далее. В тех случаях, когда это нужно. ### Контроль работы с формой и результатов целевых действий {#section_sdd_kwn_nlb .section} Процесс работы пользователей с Payment Page контролируется, прежде всего, со стороны Ecommpay, но при этом доступны и возможности для контроля со стороны мерчанта. К таким возможностям относятся: - *Контроль интерфейсных событий.* При использовании JavaScript-библиотеки Ecommpay можно получать и обрабатывать информацию о таких событиях, как открытие формы и ошибка при её открытии, подтверждение целевого действия пользователем и закрытие им формы и так далее, до конечного результата. Это позволяет оперативно реагировать на значимые события, связанные с платёжной формой, непосредственно в клиентской части веб-сервиса. Так, можно уточнить у пользователя причину закрытия формы или дополнительно уведомить его о скором завершении времени на ввод данных. И, конечно, за счёт такого контроля можно дополнительно анализировать действия пользователей при работе с Payment Page в разных ситуациях. - *Ограничение времени заполнения формы.* При вызове Payment Page можно задавать время, отводимое пользователю на ввод данных и подтверждение целевого действия. В таких случаях в интерфейсе отображается таймер с обратным отсчётом и по истечении заданного времени, если пользователь не подтвердил целевое действие, выдаётся сообщение об ошибке. Это позволяет избежать ситуаций с „подвисанием“ открытых форм на нежелательно долгое или вовсе неопределённое время и контролировать предоставление услуг пользователям \(что, например, может быть актуально при продаже билетов, распродаже товаров и иных событиях с привязкой ко времени\). - *Контроль результатов.* Для контроля результатов целевых действий, выполняемых через Payment Page, со стороны мерчанта можно использовать разные средства: - Во-первых, *программные оповещения*, которые автоматически отправляются на заданные URL по итогам выполнения целевых действий и содержат детальную информацию о результатах. Через эти оповещения можно обеспечивать оперативный автоматический контроль ситуации на стороне серверной части веб-сервиса. - Во-вторых, специальные *запросы к Gate API и Data API*, с помощью которых можно получать детальную информацию об отдельных платежах и группах платежей в тех случаях, когда это необходимо со стороны веб-сервиса. - В-третьих, *средства интерфейса Dashboard*, с помощью которого можно обеспечивать контроль и анализ ситуации сотрудниками, как по отдельным платежам, так и по сводным показателям. Совокупность этих средств позволяет контролировать со стороны мерчанта практически все аспекты, которые могут быть значимы при использовании платёжной формы. ### Поддержка разных вариантов оформления платёжной формы {#section_odv_kwn_nlb .section} В дополнение к различным функциональным возможностям при работе с Payment Page можно гибко конфигурировать дизайн формы — в плане аспектов её «поведения» и оформления. К таким аспектам относятся: - *Способы вызова формы.* Вызов Payment Page из веб-сервиса может быть реализован как через переход по кнопке, так и через другие интерфейсные события. В подключаемой JavaScript-библиотеке Ecommpay для этого доступны соответствующие методы, а если вызов Payment Page осуществляется через API, то со стороны мерчанта можно поддержать необходимую функциональность непосредственно в веб-сервисе. - *Способы отображения формы.* Payment Page поддерживает следующие варианты отображения: - в объекте iframe HTML-страницы; - в модальном окне поверх HTML-страницы; - в виде отдельной HTML-страницы, в текущей или новой вкладке браузера. И эти варианты можно легко варьировать для разных типов устройств и ситуаций, указывая нужный способ при вызове формы. - *Способы перенаправлений с формы.* При выполнении целевых действий через Payment Page порой необходимы перенаправления пользователя к сторонним сервисам — например, для аутентификации 3‑D Secureилиподтверждения оплаты на стороне платёжной системы. Для таких перенаправлений могут использоваться варианты с отдельной HTML-страницей \(в текущей или новой вкладке браузера\) и с объектом iframe в HTML-странице. Конкретный вариант настраивается специалистами технической поддержки Ecommpay с учётом предпочтений мерчанта. - *Варианты оформления формы.* Для Payment Page можно применять как типовое оформление от Ecommpay, так и индивидуальное — в соответствии с предпочтениями мерчанта. Для настройки индивидуального оформления можно использовать соответствующий [конструктор](ru_PP__design_customisation.md), а с вопросами и предложениями, выходящими за рамки возможностей конструктора, можно обращаться к курирующему менеджеру. - *Языковые настройки формы.* В интерфейсе Payment Page поддерживаются различные языки, и при вызове формы можно указывать необходимый или использовать решение по умолчанию, при котором платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию\), и пользователю отображается выпадающий список с возможностью изменять этот язык. За счёт настройки таких составляющих можно гармонично встраивать Payment Page практически в любой веб-сервис, подчёркивая его специфику и характер. ## Интерфейс {#ru_pp_emulator} Для предварительного знакомства с пользовательским интерфейсом Payment Page можно использовать демонстрационную версию [на сайте Ecommpay](https://ecommpay.com/core-functionalities/integrations/hosted-payment-page/). Эта версия позволяет эмулировать базовый сценарий разовой оплаты с использованием различных платёжных методов и способов открытия платёжной формы актуального 5-го поколения. В дополнение к этому можно использовать представленный здесь эмулятор, который позволяет получить представление о различных сценариях работы с использованием платёжной формы 4-го поколения. |Эмулятор позволяет воспроизводить возможные сценарии работы условного веб-сервиса, Payment Page и сторонних сервисов \(таких, как Access Control Servers\) при выполнении разных целевых действий с применением платёжных карт. При этом можно выбирать и сопоставлять различные сценарии. Вместе с тем, следует учитывать, что представленные сценарии не гарантируют их буквального воспроизведения в реальных условиях \(с точностью до каждого знака и пикселя\). Они рассчитаны на то, чтобы давать наглядное представление о том, какие шаги и действия могут требоваться от пользователей в различных условиях и как при этом \(в целом\) может выглядеть Payment Page. В случае с Payment Page 5-го поколения логика работы, как правило, остаётся такой же, но при этом могут меняться общий стиль и отдельные элементы пользовательского интерфейса. Иллюстрации Payment Page 5-го поколения для большинства актуальных сценариев представлены в статьях настоящей документации. **Прим.:** Для работы эмулятора платёжной формы необходимы файлы cookie. При отказе от их использования эмулятор не загружается. Также стоит учитывать, что время загрузки эмулятора может существенно колебаться, в зависимости от характеристик используемых каналов связи, устройств и браузеров. Типичное время загрузки — в диапазоне от 30 до 50 секунд. При значительно дольшем ожидании и при ошибках загрузки рекомендуется перезагружать страницу. || --- # Быстрый старт {#ru_pp_quickstart} инструкция по оперативной организации приёма платежей через Payment Page, с использованием SDK и примеров исходного кода **На уровень выше:**[Payment Page](ru_PP_about.md) ## Введение {#ru_pp_quickstart_overview} Эта инструкция — о том, как организовать приём платежей через Payment Page. С тем, чтобы платёжная форма вызывалась из веб-сервиса и возвращала пользователей к нему. И чтобы при этом можно было использовать проверенные быстрые решения — с чёткими инструкциями, библиотеками и примерами кодана одном из трёх популярных языков программирования — PHP, Python или JavaScript. ![](images/ecommpay/ru_pp_quickstart_1.svg) Если вам актуально что-то другое, можно сориентироваться в вариантах. - Если надо научиться делать платёжные ссылки для открытия Payment Page, можно разобраться с тем, как работать с ними вручную [через Dashboard](ru_dbl_payments.md) и автоматически [через Gate](ru_gate_invoice.md). - Если надо основательно разобраться со схемой и возможностями работы с Payment Page, можно пройти [сюда](ru_pp_interaction_organisation.md). - Если актуально что-то ещё, можно обратиться к другим разделам \(например, начав [здесь](ru_PP_general.md)\) и к специалистам Ecommpay. На этом с вводными всё. Можно переходить к делу. ## Краткая теория {#ru_pp_quickstart_theory} ### Проекты и ключи {#section_wpk_bnd_4tb .section} Работу с платёжной платформой Ecommpayможно сравнить с использованием услуг гостиницы. Так, для заселения в гостиницу обычно необходимо получить номер и ключ от него, а для начала работы с платформой надо получить... *проект и ключ* от него. И как с номерами в гостиницах, в платформе может предоставляться разное количество проектов для одного клиента — под разные цели и задачи — при этом для каждого проекта \(как и для каждого гостиничного номера\) необходим свой ключ. Как правило, для работы достаточно одного тестового и одного рабочего проектов. Это типичный случай, и в рамках быстрого старта мы исходим из него. Если вам по какой-либо причине необходимо больше проектов, это стоит обсудить с курирующим менеджером, но начать всё также можно с одного тестового проекта. Если у вас уже есть идентификатор тестового проекта \(`project_id`\) и секретный ключ для него \(`secret_key`\), можно приготовиться к их использованию и переходить дальше. Если же вы ещё не бронировали тестовый проект, самое время сделать это[через заявку](https://ecommpay.com/sign-up/) на основном сайте компании и вернуться сюда. ### Схема работы {#section_idx_mnd_4tb .section} Чтобы корректно вызывать Payment Page, надо настроить сбор параметров, их подписывание и вызов формы. При этом подписывание данных \(для которого необходим секретный ключ\) важно выполнять в серверной части веб-сервиса, а вызов формы — в клиентской. Также для оперативного контроля результатов полезно настроить в серверной части приём оповещений от платёжной платформы. В целом это выглядит так. | |В клиентской части веб‑сервиса|В серверной части веб‑сервиса|В платёжной платформе| |--|------------------------------|-----------------------------|---------------------| |1|Формируем заказ. Фиксируем параметры платежа и передаём их в серверную часть \(чтобы подписать\)|–|–| |2|–|Дополняем \(если это актуально\) и подписываем параметры платежа, после чего передаём информацию в клиентскую часть|–| |3|Формируем и отправляем в платёжную платформу запрос на открытие Payment Page|–|–| |4|–|–|Принимаем запрос, готовим и открываем форму пользователю, обрабатываем его действия и проводим платёж, после чего отправляем оповещение о результате платежа и возвращаем пользователя к веб-сервису| |5|–|Принимаем оповещение о результате платежа и обновляем статус заказа|–| |6|Отображаем пользователю информацию об оплате заказа и дальнейших действиях \(если они необходимы, например для доставки товара\)|–|–| В отдельных случаях, например при работе с облегчённой редакцией платёжной формы, взаимодействие веб-сервиса с платформой может строиться иначе. Реализовывать эту схему в клиентской и серверной частях веб-сервиса в общем случае можно самыми разными способами. Здесь, в рамках быстрого старта, для удобства и скорости запуска все необходимые процедуры описываются с максимальным использованием уже готовых компонентов \(таких как SDK\) и примеров кода. Но вы всегда можете варьировать наши готовые компоненты со своими решениями. ### Параметры вызова формы {#section_ol1_v4d_4tb .section} Чтобы открыть пользователю платёжную форму, в простейшем случае достаточно определиться с суммой и валютой платежа и добавить к этим двум параметрам три идентификатора: проекта, платежа и пользователя. Таким образом, обязательных параметров всего пять.\(И технически к ним ещё обязательна подпись.\) |Параметр|Описание| |--------|--------| |`project_id` integer |Идентификатор проекта. Его вместе с ключом выдаёт Ecommpay и его важно точно указывать даже в тестовых запросах. Иначе… стоит ждать реакцию, как при попытке зайти в чужой гостиничный номер. Пример: `57123 ` | |`payment_id` string |Идентификатор платежа. Он может быть произвольным, но каждый раз должен быть уникальным в рамках используемого проекта. Иначе стоит ждать ошибку вызова. Пример: `payment_443 ` | |`payment_amount` integer |Сумма платежа. В тестовых запросах может быть произвольной, а в реальных должна точно соответствовать сумме заказа. Приводится в дробных единицах валюты. Пример: `1815` \(для суммы `18,15`\) | |`payment_currency` string |Код валюты платежа. Приводится в трёхбуквенном формате ISO 4217 alpha-3.В тестовых запросах могут использоваться любые из действующих кодов, а в реальных каждый раз должен использоваться код той валюты, в которой инициируется платёж. Для сверки можно использовать [справочник валют](ru_currency_codes.md). Пример: `EUR` | |`customer_id` string |Идентификатор пользователя.Может быть произвольным и повторяемым в разных запросах, но для каждого реального пользователя должен быть однозначно сопоставляемым с его учётной записью в веб-сервисе и уникальным в рамках проекта.Иначе возможны различные коллизии, в том числе с отображением сохранённых данных платёжных инструментов одного пользователя другому. Пример: `customer_112` | При работе с облегчённой редакцией платёжной формы обязательный набор параметров дополняется: в этом случае вместе с перечисленными параметрами также необходимо передавать доменное имя веб-сервиса \(`merchant_domain`\), служебный код платёжного метода \(`force_payment_method` со значением `card`\) и указатель режима работы Payment Page \(`mode` со значением `purchase`\). Как именно собирать эти параметры\(и в том числе, какие из них задавать в клиентской части, а какие в серверной\) — решать вам\(с оглядкой на архитектуру вашего веб-сервиса и иные факторы\). При этом для первых тестовых вызовов сбор параметров можно не автоматизировать вовсе, если что, этим можно заняться и после первичного тестирования работы с формой. Здесь же остаётся сказать, что в дополнение к обязательным параметрам можно использовать и другие, для управления видом и поведением платёжной формы, но поскольку с этими параметрами лучше разбираться после того, как настроен базовый вызов Payment Page, предметный разговор о них [дальше](ru_pp_quickstart.md#section_um4_xf2_4tb). ## Базовая реализация {#ru_pp_quickstart_basic_implementation} ### Варианты работы {#section_c2x_wqd_4tb .section} Реализовывать функции веб-сервиса для работы с платёжной формой и оповещениями можно по-разному, в том числе за счёт создания своих программных решенийи за счёт применения CMS-модулей. В рамках быстрого старта мы рассматриваем два варианта реализации: - с применением в серверной части веб-сервиса SDK от Ecommpay; - с использованием в серверной части веб-сервиса готового кода от Ecommpay Различия между этими вариантами можно считать вкусовыми.С SDK может быть чуть проще, а также доступнее при работе с другими языками программирования \(полный набор материалов о работе с SDK представлен [в отдельном разделе](ru_sdk_overview.md)\). С примерами кода же может быть чуть прозрачнее и гибче в плане встраивания в свои решения \(в том числе при работе с подписыванием данных\). Но оба варианта достаточно быстры и полноценны, и вы можете выбрать любой из них. Вместе с тем, независимо от варианта реализации серверных функций, в клиентской части веб-сервиса в рамках быстрого старта мы рассматриваем разные варианты вызова платёжной формы, в том числе с использованием библиотек от Ecommpay. И в целом задачи реализации сводятся к следующим. |В серверной части|В клиентской части| |-----------------|------------------| |- подключить библиотеки \(при работе с SDK\) - обеспечить дополнение параметров \(насколько актуально\) - обеспечить подписывание данных - обеспечить приём оповещений |- подключить библиотеки \(если актуально\) - обеспечить сбор параметров \(насколько актуально\) - обеспечить вызов формы - реализовать функции для обработки интерфейсных событий \(если актуально\) | Сбор и дополнение параметров, как и было сказано в теоретическом обзоре, могут выполняться разными способами\(для первичного тестирования допустимо и вручную\) и остаются за вами. Остальные действия разобраны далее. ### Работа с SDK {#section_kj3_kvd_4tb .section} Подключаем и настраиваем. **1 Подключаем SDK** 1. Если не делали этого ранее, загружаем, устанавливаем и настраиваем менеджер зависимостей Composer \([https://getcomposer.org/](https://getcomposer.org/)\). 2. В командной строке операционной системы переходим в каталог с исходным кодом веб-сервиса и выполняем команду `composer require ecommpay/paymentpage-sdk`. 3. Подключаем скрипт `autoload.php` в исходном коде веб-сервиса. ```language-php // Подключение библиотек require` __DIR__.'../../vendor.autoload.php'; ```   **2 Обеспечиваем подписывание данных** Когда для всех необходимых параметров определены их значения\(и только в таком случае\), можно собирать эти данные в серверной части веб-сервиса и формировать подпись и URL для вызова платёжной формы. Как это делать, можно разобрать на примере. ```language-php // Подписывание данных и формирование ссылки // создание объекта класса Payment и указание идентификаторов проекта и платежа $payment = new ecommpay Payment('57123', 'payment_443'); // указание других обязательных параметров $payment->setPaymentAmount(1815)->setPaymentCurrency('EUR'); // сумма и валюта платежа $payment->setCustomerId('customer_112'); // идентификатор пользователя // создание объекта класса Gate и указание секретного ключа $gate = new ecommpay\Gate(''); // формирование ссылки для вызова платёжной формы $url = $gate->getPurchasePaymentPageUrl($payment); ```   **3 Настраиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-php // Работа с оповещениями // создание объекта класса Gate и указание секретного ключа $gate = new ecommpay\Gate(''); // создание объекта класса Callback и указание JSON-строки с данными // из оповещения ($data), с проверкой целостности данных $callback = $gate->handleCallback($data); // использование методов для работы с оповещениями Callback::getPaymentId(); // получение идентификатора платежа Callback::getPaymentStatus(); // получение статуса платежа Callback::getPayment(); // получение всей информации из оповещения ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. **1 Подключаем SDK** 1. Если не делали этого ранее, загружаем, устанавливаем и настраиваем систему управления пакетами pip \([https://pip.pypa.io/en/stable/](https://pip.pypa.io/en/stable/)\). 2. В командной строке операционной системы переходим в каталог с исходным кодом веб-сервиса и выполняем команду `pip install ecommpay-sdk`. 3. Подключаем библиотеки из SDK в исходном коде веб-сервиса. ```language-python # Подключение библиотек from payment_page_sdk.gate import Gate from payment_page_sdk.payment import Payment ```   **2 Обеспечиваем подписывание данных** Когда для всех необходимых параметров определены их значения\(и только в таком случае\), можно собирать эти данные в серверной части веб-сервиса и формировать подпись и URL для вызова платёжной формы. Как это делать, можно разобрать на примере. ```language-python # Подписывание данных и формирование ссылки # создание объекта класса Payment и указание идентификаторов проекта и платежа payment = Payment('57123', 'payment_443') # указание других обязательных параметров payment.payment_amount = 1815 # сумма платежа payment.payment_currency = 'EUR' # валюта платежа payment.customer_id = 'customer_112' # идентификатор пользователя # создание объекта класса Gate и указание секретного ключа gate = Gate('') # формированием ссылки для вызова платёжной формы payment_url = gate.get_purchase_payment_page_url(payment) ```   **3 Настраиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-python # Работа с оповещениями # создание объекта класса Gate и указание секретного ключа gate = Gate('') # создание объекта класса Callback и указание JSON-строки с данными # из оповещения (data), с проверкой целостности данных callback = gate.handle_callback(data) # использование методов для работы с оповещениями callback.get_payment_id() # получение идентификатора платежа callback.get_payment_status() # получение статуса платежа callback.get_payment() # получение всей информации из оповещения ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. **1 Подключаем SDK** 1. Если не делали этого ранее, загружаем, устанавливаем и настраиваем систему управления пакетами: Yarn \([https://yarnpkg.com/en/docs/getting-started](https://yarnpkg.com/en/docs/getting-started)\) или npm \([https://www.npmjs.com/package/ecommpay](https://www.npmjs.com/package/ecommpay)\). 2. В командной строке операционной системы переходим в каталог с исходным кодом веб-сервиса и выполняем одну из команд: `yarn add ecommpay` или `npm install ecommpay`. 3. Подключаем модули в исходном коде веб-сервиса. ``` {#codeblock_bdr_mnx_w1c .language-javascript} const { Payment } = require('ecommpay'); const { Callback } = require('ecommpay'); ```   **2 Обеспечиваем подписывание данных** Когда для всех необходимых параметров определены их значения\(и только в таком случае\), можно собирать эти данные в серверной части веб-сервиса и формировать подпись и URL для вызова платёжной формы. Как это делать, можно разобрать на примере. ```language-javascript // Подписывание данных и формирование ссылки // создание объекта класса Payment и указание идентификатора проекта и секретного ключа const payment = new Payment('57123', 'payment_443'); // указание идентификатора платежа payment.paymentId = 'payment_443; // указание других обязательных параметров payment.paymentAmount = 1815 // сумма платежа payment.paymentCurrency = 'EUR' // валюта платежа payment.customerId = 'customer_112' // идентификатор пользователя // получение ссылки для вызова платёжной формы const url = payment.getUrl(); ```   **3 Настраиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-javascript // Работа с оповещениями // создние объекта класса Callback и указание секретного ключа const callback = new Callback(, req.body); // использование методов для работы с оповещениями app.post('/payment/callback', function(req, res) { const callback = new Callback(<*secret\_key*>, req.body); if (callback.isPaymentSuccess()) { const paymentCont = callback.payment(); // получение всей информации о платеже const paymentId = callback.getPaymentId(); // получение идентификатора платежа // Здесь размещается исходный код для обработки оповещения проведённого платежа } }); ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. ### Работа с кодом {#section_k1p_t12_4tb .section} Встраиваем и используем. **1 Обеспечиваем подписывание данных** ```language-php // Кодирование алгоритма class Signer { const ALGORITHM = 'sha512'; const ITEMS_DELIMITER = ';'; /** * Generate signature * * @param array $params * @param string $secretKey * @param array $ignoreParamKeys * @param bool $doNotHash * * @return string */ public static function sign(array $params, string $secretKey, array $ignoreParamKeys = [], bool $doNotHash = false): string { $paramsPrepared = self::getParamsToSign($params, $ignoreParamKeys, 1, ''); $stringToSign = implode(self::ITEMS_DELIMITER, $paramsPrepared); return $doNotHash ? $stringToSign : base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $secretKey, true)); } /** * Get parameters to sign * * @param array $params * @param array $ignoreParamKeys * @param int $currentLevel * @param string $prefix * * @return array */ private static function getParamsToSign( array $params, array $ignoreParamKeys = [], int $currentLevel = 1, string $prefix = '' ): array { $paramsToSign = []; foreach ($params as $key => $value) { if (in_array($key, $ignoreParamKeys, true)) { continue; } $paramKey = ($prefix ? $prefix . ':' : '') . $key; if (is_object($value)) { $value = get_object_vars($value); } if (is_array($value)) { $subArray = self::getParamsToSign($value, $ignoreParamKeys, $currentLevel + 1, $paramKey); $paramsToSign = array_merge($paramsToSign, $subArray); } else { if (is_bool($value)) { $value = $value ? '1' : '0'; } else { $value = (string)$value; } $paramsToSign[$paramKey] = (string)$paramKey . ':' . $value; } } if ($currentLevel == 1) { ksort($paramsToSign, SORT_NATURAL); } return $paramsToSign; } // Пример использования // указание секретного ключа и параметров вызова платёжной формы $secretKey = "jwfbfjhewbrw33383kr3js9d987"; $params = [ 'project_id' => 57123, 'payment_amount' => 1815, 'payment_currency' => 'EUR', 'customer_id' => 'customer_112', 'payment_id' => 'payment_443', ]; // формирование подписи $params['signature'] = Signer::sign($params, $secretKey); // получение ссылки для вызова платёжной формы $uriParams = http_build_query($params); $link = implode('?', ['https://paymentpage.ecommpay.com/payment', $uriParams]); ```   **2 Обеспечиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-php // Работа с оповещениями. Пример сверки полученной подписи с расчётной require_once 'Signer.php'; $secretKey = ''; $requestBody = '{ "project_id": 57123, "payment": { "id": "payment_443", "type": "purchase", "status": "success", "date": "2022-03-03T10:50:29+0000", "method": "card", "sum": { "amount": 1815, "currency": "EUR" }, "description": "Test payment" }, "customer": { "id": "customer_112", "ip": "127.0.0.1", "phone": "60358490238", "email": "jane.doe@testmail.com" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-03-03T10:50:29+0000", "sum_initial": { "amount": 1815, "currency": "EUR" }, "code": "0", "message": "Success" }, "signature": "zwoFECy7H+WZFziw9IgR9031Uu878TuIv3dhFyHvCuvzIdRAzDQA==" }'; $requestBodyArray = json_decode($requestBody, true); $actualSignature = $requestBodyArray['signature']; unset($requestBodyArray['signature']); $expectedSignature = Signer::sign($requestBodyArray, $secretKey); print_r('Actual signature: ' . $actualSignature . PHP_EOL); print_r('Expected signature: ' . $expectedSignature . PHP_EOL); if ($expectedSignature === $actualSignature) { print_r('Signatures are equal'); } else { print_r('Signatures are not equal'); } print_r(PHP_EOL); ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. **1 Обеспечиваем подписывание данных** ```language-python # Кодирование алгоритма import hmac import base64 import hashlib class Signer: def getSign(self, params, key): byteKey = key.encode() paramsPrepared = self.getParamsToSign(params) toSignString = ';'.join(paramsPrepared.values()) hmacObj = hmac.new(byteKey, toSignString.encode(), hashlib.sha512) return base64.b64encode(hmacObj.digest()) def getParamsToSign(self, params, currentLevel = 1, prefix = ''): paramsToSign = dict() for paramKey in params.keys(): newParamKey = (prefix + ':' if prefix else '') + paramKey if isinstance(params[paramKey], (dict)): subDict = self.getParamsToSign(params[paramKey], currentLevel + 1, newParamKey) paramsToSign.update(subDict) else: if isinstance(params[paramKey], (bool)): value = '1' if params[paramKey] == True else '0' else: value = str(params[paramKey]) paramsToSign[newParamKey] = str(newParamKey + ':' + value) sortedParams = dict() for key in sorted(paramsToSign.keys()): sortedParams[key] = paramsToSign[key] return sortedParams # Пример использования # указание параметров вызова платёжной формы и секретного ключа import urllib.parse import Signer params = { 'project_id': 57123, 'payment_amount': 1815, 'payment_currency': 'EUR', 'customer_id': 'customer_112', 'payment_id': 'payment_443', } # формирование подписи signer = Signer.Signer() params['signature'] = signer.getSign(params, '') print(params['signature']) # получение ссылки для вызова платёжной формы jointParams = urllib.parse.urlencode(params) link = '?'.join(['https://paymentpage.ecommpay.com/payment', jointParams]) ```   **2 Обеспечиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-python # Работа с оповещениями. Пример сверки полученной подписи с расчётной from Signer import Signer import base64 secretKey = '' params = { "project_id": 57123, "payment": { "id": "payment_443", "type": "purchase", "status": "success", "date": "2022-03-03T10:50:29+0000", "method": "card", "sum": { "amount": 1815, "currency": "EUR" }, "description": "Gagarin set" }, "customer": { "id": "customer_112", "ip": "127.0.0.1", "phone": "60358490238", "email": "jane.doe@testmail.com" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-03-03T10:50:29+0000", "sum_initial": { "amount": 1815, "currency": "EUR" }, "code": "0", "message": "Success" }, "signature": "zwoFECy7H+WZFziw9IgR90SEmC+o3qXD7OIaHqgQuqcSwBC09W6yQA==" } signer = Signer() actualSign = params['signature'] del params['signature'] expectedSign = signer.getSign(params, secretKey).decode() print('Actual signature:' + actualSign) print('Expected signature:' + expectedSign) if (expectedSign == actualSign): print('Signature is correct') else: print('Signature is incorrect') ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. **1 Обеспечиваем подписывание данных** ```language-javascript // Кодирование алгоритма import hmacSHA512 from 'crypto-js/hmac-sha512'; import encBase64 from 'crypto-js/enc-base64'; export class Signer { getSign(params, key) { const paramsPrepared = this.getParamsToSign(params, 1); const joinedString = Object.values(paramsPrepared).join(';'); const hash = hmacSHA512(joinedString, key); return hash.toString(encBase64); } getParamsToSign( params, prefix = '', ) { let paramsToSign = {}; let value = ''; let keys = Object.keys(params); let key = ''; for (let i = 0; i < keys.length; i++) { key = keys[i]; let paramKey = (prefix ? prefix + ':' : '') + key; if (typeof params[key] === 'object') { let subParams = this.getParamsToSign( params[key], paramKey, ); Object.assign(paramsToSign, subParams); } else { if (typeof params[key] === 'boolean') { value = params[key] === true ? '1' : '0'; } else { value = params[key].toString(); } paramsToSign[paramKey] = paramKey + ':' + value; } } let orderedKeys = Object.keys(paramsToSign).sort(); let ordered = {}; for (let k = 0; k < orderedKeys.length; k++) { ordered[orderedKeys[k]] = paramsToSign[orderedKeys[k]]; } return ordered; } } // Пример использования import { Signer } from './signer.js'; // указание параметров вызова платёжной формы и секретного ключа let params = { project_id: 57123, payment_amount: 1815, payment_currency: 'EUR', customer_id: 'customer_112', payment_id: 'payment_443', }; // формирование подписи params['signature'] = new signer().getSign(params, ''); // получение ссылки для вызова платёжной формы const uriParams = Object.keys(params) .sort() .reduce((paramsArray, key) => { paramsArray.push(key + '=' + encodeURIComponent(params[key])); return paramsArray; }, []); const link = [ 'https://paymentpage.ecommpay.com/payment', uriParams.join('&'), ].join('?'); ```   **2 Обеспечиваем приём оповещений** Чтобы оперативно узнавать о результатах платежей и получать другую значимую информацию, следует настроить приём и обработку программных оповещений от платёжной платформы. Это делается в три шага: 1. Определяем и задаём в платёжной платформе адрес для приёма веб-сервисом оповещений по проекту\(сначала можно задать один общий адрес, а после — несколько, под разные события\). Для этого открываем в интерфейсе Dashboard раздел **Проекты** и используем инструменты на вкладке **Оповещения**. 2. Настраиваем проверку целостности и разбор оповещений, поступающих на указанный URL, с использованием SDK. 3. Настраиваем отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК` если подпись корректна и `400 Bad Request` если подпись некорректна. ```language-java // Работа с оповещениями. Пример сверки полученной подписи с расчётной import { Signer } from './Signer'; const secretKey = ''; const params = { "project_id": 57123, "payment": { "id": "payment_443", "type": "purchase", "status": "success", "date": "2022-03-03T10:50:29+0000", "method": "card", "sum": { "amount": 1815, "currency": "EUR" }, "description": "Gagarin set" }, "customer": { "id": "customer_112", "ip": "127.0.0.1", "phone": "60358490238", "email": "jane.doe@testmail.com" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-03-03T10:50:29+0000", "sum_initial": { "amount": 1815, "currency": "EUR" }, "code": "0", "message": "Success" }, "signature": "zwoFECy7H+WZFziw9IgR90SHvCuvqXD7OIaHqgQuqcSwBC09W6yQA==" }; const actualSignature = params['signature']; delete params.signature; const expectedSignature = (new signer()).getSign(params, secretKey); console.log('Actual: ' + actualSignature); console.log('Expected: '+expectedSignature); if (actualSignature == expectedSignature) { console.log('Signatures is correct'); } else { console.log('Signature is incorrect'); } ``` Описания используемых статусов платежей можно найти [в отдельном разделе](ru_platform_payment_model.md), а описание оповещений и работы с ними — [в отдельной статье](ru_platform_callbacks.md). При этом важно помнить, что в случаях, когда пользователь не подтверждает оплату в платёжной форме, платёж не регистрируется \(и статуса по нему тоже нет\). Извлечённую из оповещений информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего веб-сервиса. ### Действия в клиентской части {#section_ch3_gc2_4tb .section} Открывать Payment Page в клиентской части веб-сервиса можно по-разному, и для наглядности можно попробовать несколько способов даже в рамках быстрого старта. Самый простой способ — открывать платёжную форму в отдельной вкладке браузера. Чтобы открыть платёжную форму в виде отдельной HTML-страницы, следует использовать ссылку, полученную при подписывании данных.Это ссылка формата `https://paymentpage.ecommpay.com/payment?`, где `` — строка с названиями и значениями параметров вызова. HTTP-запрос с применением метода GET в таком случае может выглядеть следующим образом: ```language-xml GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000& customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1 Host: https://paymentpage.ecommpay.com ``` Для использования других способов — с открытием платёжной формы в модальном окне и в элементе iframe — необходимо подключить две библиотеки: CSS для корректного отображения формы и JavaScript для вызова формы.Это делается через добавление ссылок на библиотеки в заголовочной части HTML-страницы. ```language-xml ... // подключение CSS-библиотеки // подключение JavaScript-библиотеки ... ``` Также для вызова платёжной формы с помощью JavaScript-библиотеки необходимо использовать подписанный набор параметров в виде JavaScript-объекта. Его можно формировать из ссылки, полученной при подписывании данных\(в PHP для этого можно использовать функции `parse_url` и `parse_str`\), или используя серверный код для формирования подписи \(без составления ссылки\)и добавляя подпись к остальным параметрам. Подключив библиотеки и разобравшись с параметрами, можно пробовать. Чтобы открыть Payment Page в модальном окне, можно использовать метод `run` JavaScript-объекта `EPayWidget`. При обращениях к этому методу следует указывать объект с параметрами вызова Payment Page \(`configObj`\) и HTTP-метод отправки запросов \(`method`\): ```language-json EPayWidget.run( { payment_id: 'payment_443', // идентификатор платежа payment_amount: 1815, // сумма платежа payment_currency: 'EUR', // код валюты платежа project_id: 57123, // идентификатор проекта customer_id: 'customer_112', // идентификатор пользователя signature: 'YWb6Z20ByxpQ30hfTI' }, // подпись 'post') // HTTP-метод ``` Чтобы открыть Payment Page в элементе iframe, как и в случае с модальным окном, можно использовать метод `run` JavaScript-объекта `EPayWidget`. В этом случае следует указывать объект с параметрами вызова Payment Page \(`configObj`\), идентификатор элемента, в котором необходимо отобразить платёжную форму \(`target_element`\), и HTTP-метод отправки запросов \(`method`\): ```language-json EPayWidget.run( { payment_id: 'payment_443', // идентификатор платежа payment_amount: 1815, // сумма платежа payment_currency: 'EUR', // код валюты платежа project_id: 57123, // идентификатор проекта customer_id: 'customer_112', // идентификатор пользователя signature: 'YWb6Z20ByxpQ30hfTI', // подпись target_element: 'widget-container' }, // идентификатор элемента 'post') // HTTP-метод ``` Чтобы открыть облегчённую редакцию платёжной формы Payment Page, необходимо использовать метод `runEmbedded` JavaScript-объекта `EPayWidget`. В этом случае следует указывать объект с параметрами вызова Payment Page \(`configObj`\), идентификатор элемента \(`target_element`\) и доменное имя веб-сервиса \(`merchant_domain`\), в которых необходимо отобразить платёжную форму: ``` {#codeblock_drm_f4d_33c .language-json} const configObj = { target_element: "widget-container-card-embedded", payment_id: "X03937", payment_amount: 1960, payment_currency: "EUR", project_id: 22, merchant_domain: "cosmoshop.jupiter.example", force_payment_method : "card", signature: "0ByxpQ30hfTIjaCCsVIwVyabcDEF123" }; ``` Следует учитывать, что для работы с облегчённой редакцией платёжной формы необходимо реализовать специализированные функции обработки интерфейсных событий. Для начального знакомства этих способов вызова и открытия может быть вполне достаточно. Если же необходима более тонкая настройка, можно обращаться [к документации](ru_PP_Integration.md) и к нашим специалистам. ## Тестирование {#ru_pp_quickstart_testing} Когда мы открываем платёжную форму в рабочем режиме, с ней работает пользователь. А в тестовом режиме можно почувствовать себя на его месте и протестировать разные сценарии оплаты с его позиции. Главный вопрос при этом — какие реквизиты указывать? При работе с тестовым проектом можно использовать два вида платёжных реквизитов: *специальные* тестовые, позволяющие тестировать заданные сценарии работы, и *произвольные* реалистичные, позволяющие дополнительно проверить работу формы в разных случаях. В базовом случае можно использовать следующие тестовые номера платёжных карт\(для проведения платежей по заданным кратчайшим сценариям, без эмулирования аутентификации 3‑D Secure\): - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. ![](images/ecommpay/ru_pp_quickstart_2.svg) Для более масштабного тестирования можно использовать расширенный набор тестовых данных для [карточных](ru_test_cards.md) \(в том числе с аутентификацией 3‑D Secure\)и различных [альтернативных](ru_pm_testing.md)платежей, а также произвольные данные, включая реквизиты реальных карт, кошельков и других платёжных инструментов. Это безопасно, поскольку для всех данных в тестовой среде обеспечивается тот же уровень защиты, что и в рабочей, но реальные платежи при этом не проводятся. По итогам тестирования, убедившись в корректной работе с формой, можно считать реализованными базовые функции по проведению оплат и при желании переходить дальше — к различным дополнениям, которые могут быть полезны уже на первых порах работы с платёжной платформой, и к запуску решения в работу. ## Дополнения {#ru_pp_quickstart_additional_aspects} ### Контроль проведения платежей {#section_j4g_s22_4tb .section} После проведения нескольких тестовыхплатежей можно разобраться с тем, как контролировать общую ситуацию по платежам. Для этого следует открыть Dashboard и ознакомиться там с реестром и карточками платежей. ![](images/ecommpay/dbl/ru_quickstart_dbl_overview.svg "Реестр платежей") ![](images/ecommpay/dbl/ru_quickstart_dbl_payment_details.svg "Карточка платежа") При возникновении вопросов по работе с этим интерфейсом, как и в иных случаях, можно обращаться [к документации](ru_dbl_payments.md) и к нашим специалистам. ### Возврат средств {#section_c4b_pf2_4tb .section} Если по какой-либо проведённой оплате необходимо выполнить возврат, для этого также можно использовать Dashboard. При тестировании работы с платёжной платформой можно попробовать выполнить полные и частичные возвраты из карточек платежей. Для более глубокого освоения работы с возвратами, в том числе с массовыми, можно использовать [отдельную статью](ru_dbl_payments.md).Кроме того, полезно иметь в виду возвраты [через Gate](ru_Gate_Refund.md). ### Возможности управления формой {#section_um4_xf2_4tb .section} При работе с Payment Page можно оперировать различными возможностями, чтобы управлять видом и поведением формы, например, задавая подходящий язык, фильтруя методы оплаты или управляя способами возвращения пользователя к веб-сервису. Некоторые из таких возможностей требуют подключения через специалистов Ecommpay, иные можно использовать без обращений к кому-либо, просто настроив их через Dashboard или передавая дополнительные параметры в запросах на открытие Payment Page. При тестировании работы с Payment Page мы рекомендуем попробовать следующее: - *Настроить оформление платёжной формы с помощью конструктора*. Для этого следует перейти в раздел **Проекты** интерфейса Dashboard и воспользоваться инструментами вкладки **Payment Page Designer** \(подробнее — в статье [Индивидуальное оформление](ru_PP__design_customisation.md)\). - *Попробовать вызов платёжной формы на разных языках*. Чтобы открыть Payment Page на определённом языке, его код \(в двухбуквенном формате ISO 639-1 alpha-2\) следует передать в значении соответствующего параметра: `language_code`. Список поддерживаемых Ecommpay языков можно найти [здесь](ru_PP_WigetLanguages.md). - *Возвращать пользователя к веб-сервису после проведения платежей*. После проведения платежей в зависимости от их результатов можно перенаправлять пользователей к разным страницам веб-сервиса. Адреса таких страниц можно задать в разделе **Проекты** интерфейса Dashboard \(во вкладке **Ссылки для перенаправления**\), либо передавать их в конкретных запросах в значении параметров `merchant_success_url` и `merchant_fail_url`. - *И далее на ваш вкус*. Информацию о разных возможностях можно найти [в общем обзоре](ru_PP_general.md) и [в специализированном разделе](ru_PP_Additional.md), а полный перечень параметров вызова — [в отдельной статье](ru_PP_Parameters.md). С вопросами же, как обычно, можно обращаться к нашим специалистам. ## Запуск {#ru_pp_quickstart_launch_project} После реализации базовых функций, тестирования разных возможностей и определения необходимых вам сценариев работы можно переходить к запуску рабочего проекта. Важно, чтобы к этому моменту были решены организационные вопросы. В таком случае вопросы технические сводятся к настройке свойств проекта на стороне платёжной платформы и к началу использования идентификатора и ключа рабочего проекта. Успехов! --- # Организация взаимодействия {#ru_pp_interaction_organisation} статья о том, как строится работа с платёжной платформой через Payment Page и как можно организовывать эту работу со стороны веб-сервиса в различных случаях **На уровень выше:**[Payment Page](ru_PP_about.md) ## Общая информация {#ru_pp_interaction_organisation_overview} Платёжная форма Payment Page допускает различные варианты её использования для проведения оплат, выплати выполнения других целевых действий. Так, для вызова формы можно работать напрямую с Payment Page API или же использовать подключаемую библиотеку Ecommpay, а открытие формы может осуществляться в отдельной вкладке браузера или же непосредственно на странице веб-сервиса. И так далее. Вариативность работы Payment Page описана в разделе [Общая информация](ru_PP_general.md), а в данном разделе представлена информация о порядке и технических аспектах интеграции через Payment Page. К базовым условиям для работы с Payment Page независимо от используемых технических решений можно отнести следующие: - вызов платёжной формы должен осуществляться с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2; - данные в запросах и оповещениях должны кодироваться и обрабатываться с использованием кодировки UTF-8; - запросы должны отправляться на базовый адрес — https://paymentpage.ecommpay.com; - в качестве пользовательского браузера могут использоваться актуальные версии таких браузеров, как Google Chrome, Safari, Opera, Mozilla Firefox, Microsoft Edge, QQ Browser, Mi Browser, Samsung Internet, 360 Secure Browser и ряда других. Подробную информацию о работе Payment Page в разных средах можно получить у специалистов технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\), а информацию о вариантах интеграции, схемах работы и форматах запросов — в этом разделе. ## Порядок интеграции {#ru_pp_integration_step} Для интеграции с платёжной платформой Ecommpay через Payment Page необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с Ecommpay — отправить [заявку на подключение](https://ecommpay.com/apply-now/). 2. Если планируется проводить платежи с использованием карт платёжных систем Visa и Mastercard — предоставить курирующему менеджеру Ecommpay документы о соответствии [требованиям PCI DSS](ru_faq_integration.md#fig_fgk_rgs_4nb): - Для всех мерчантов — отчёт о результатах [ASV-сканирования](ru_glossary.md). Такие сканирования должны выполняться авторизованными поставщиками \(PCI SSC Approved Scanning Vendor, ASV\) ежеквартально, а также после каждого значительного изменения сетевой инфраструктуры.Мерчанты Ecommpay могут выбирать таких поставщиков самостоятельно и, если это актуально, могут задействовать поставщика, являющегося партнёром Ecommpay. Чтобы организовать сканирования через партнёра Ecommpay, можно обращаться к курирующему менеджеру. - Для мерчантов с количеством операций более 6 миллионов в год \(уровня 1\) — аттестат соответствия \(Attestation of Compliance, AOC\). - Для мерчантов с количеством операций до 6 миллионов в год \(уровней 2, 3 и 4\) — [опросный лист](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment) \(Self-Assessment Questionnaire, SAQ\). С вопросами о правилах заполнения опросных листов можно обращаться к курирующему менеджеру Ecommpay. 3. Если есть потребность в индивидуальном оформлении платёжной формы — согласовать с курирующим менеджером Ecommpay возможности использования [конструктора](ru_PP__design_customisation.md) или иных способов оформления. 4. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием различных платёжных методов\) и запуска решения в работу. 2. Выполнить подготовительные технические работы, собственными средствами или с использованием специализированных компонентов, предоставляемых Ecommpay: 1. Если актуально индивидуальное оформление платёжной формы с помощью [конструктора](ru_PP__design_customisation.md) — получить у специалистов технической поддержки учётную запись Dashboard с соответствующими правами и настроить вид формы. Если был согласован иной способ оформления — решить соответствующие вопросы с курирующим менеджером и специалистами технической поддержки. 2. Установить и подключить необходимые библиотекии \(или\) плагины. 3. Обеспечить возможности сбора параметров, необходимых для выполнения целевых действий, а также возможности формирования и отправки запросов на открытие Payment Page на стороне клиентской части веб-сервиса. 4. Обеспечить подписывание данных и корректное реагирование на оповещения на стороне серверной части веб-сервиса. 3. Совместно со специалистами технической поддержки Ecommpay протестировать выполнение целевых действий и запустить решение по взаимодействию веб-сервиса с платёжной платформой в работу. После тестирования и мониторинга, когда подтверждается корректность выполнения целевых действий на рабочем трафике, специалисты технической поддержки переводят работу с веб-сервисом в режим штатной поддержки. При возникновении вопросов о работе через Payment Page можно обращаться к курирующему менеджеру и специалистам технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ## Схема взаимодействия {#ru_pp_interaction_scheme} При использовании Payment Page выполнение любого целевого действия подразумевает взаимодействия между тремя основными сторонами: пользователем, веб-сервисом и Payment Page. В общем случае эти взаимодействия осуществляются следующим образом: - Взаимодействие веб-сервиса и Payment Page строится на обмене HTTP-сообщениями по принципу «запрос-ответ». В такой схеме от клиентской части веб-сервиса к Payment Page отправляются запросы, а от Payment Page отправляются синхронные ответы к клиентской части веб-сервиса и асинхронные оповещения к серверной части веб-сервиса. Как правило, отправляются итоговые оповещения о результатах выполнения целевых действий, но в некоторых случаях могут отправляться и промежуточные оповещения, например при выполнении пользователем повторных попыток ввода данных.Кроме того, со стороны веб-сервиса может использоваться отслеживание интерфейсных событий в Payment Page, контролируемых с помощью встраиваемой библиотеки. - Взаимодействие пользователя и Payment Page осуществляется через пользовательский интерфейс платёжной формы и технически также основано на обмене HTTP-сообщениями по принципу «запрос-ответ» между пользовательским браузером и Payment Page. Порядок взаимодействия между этими и другими сторонами представлен далее на схеме. ![](images/ru_pp_interaction_concept_uml.svg) 1. Пользователь на стороне клиентской части веб-сервиса инициирует выполнение целевого действия. 2. На стороне клиентской части веб-сервиса выполняется сбор параметров, необходимых для формирования запроса на открытие Payment Page, и их передача в серверную часть веб-сервиса. 3. На стороне серверной части веб-сервиса выполняется обработка поступившего запроса: - проверка параметров; - дополнение полученных параметров хранящейся на стороне серверной части информацией, если это необходимо; - формирование подписи к набору параметров. 4. От серверной части веб-сервиса к его клиентской части направляется ответ на запрос. 5. На стороне клиентской части выполняется приём ответа, а затем формирование и отправка на заданный URL Ecommpay запроса на открытие Payment Page. 6. Запрос на открытие Payment Page поступает в платёжную платформу. 7. В платёжной платформе выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи. 8. Осуществляется подготовка Payment Page согласно настройкам проекта и параметрам вызова. 9. Пользователю отображается подготовленная платёжная форма. 10. Пользователь выполняет необходимые действия. 11. Запрос на проведение платежа поступает в платёжную платформу. 12. Выполняются дальнейшая обработка запроса и его отправка в платёжную среду. 13. На стороне платёжной среды выполняется обработка платежа. 14. От платёжной среды к платёжной платформе направляется уведомление о результате платежа. 15. От платёжной платформы к веб-сервису направляется оповещение о результате платежа. 16. От платёжной платформы к Payment Page направляется информация о результате проведения платежа. 17. Результат платежа отображается пользователю на Payment Page. ## Настройка веб-сервиса {#ru_pp_interaction_preparing_webservice_page} ### Общая информация {#section_lkl_dlz_1mb .section} Для начала работы с Payment Page на стороне веб-сервиса должны быть обеспечены: - сбор параметров, необходимых для проведения платежа; - формирование подписи; - открытие Payment Page; - обработка оповещений; - корректное реагирование на оповещения с отправкой ответов об их приёме. Для этого можно использовать как только собственные решения, так и специализированные компоненты, предоставляемые Ecommpay: подключаемую JavaScript-библиотеку, SDK для проектов на разных языках программированияи подключаемые модули для сайтов на базе ряда распространённыхCMS. Использование таких компонентов помогает полностью или частично снять необходимость в задействовании собственных решений. С помощью компонентов, предоставляемых Ecommpay, могут выполняться следующие действия: | |**JavaScript-библиотека**|**SDK для веб-сервисов**|**SDK для мобильных приложений**|**Плагины для CMS**| |- Сбор параметров |–|–|+|+| |- Формирование подписи |–|+|–|+| |- Открытие Payment Page |+|–|+|+| |- Обработка оповещений |–|+|–|+| |- Реагирование на оповещения |–|–|–|+| Информация о настройке веб-сервиса с использованием собственных решений и каждого из специализированных компонентов, предоставляемых Ecommpay, представлена далее. ### Использование собственных решений {#section_rcw_r43_jlb .section} Для настройки взаимодействия с Payment Page с использованием собственных решений на стороне веб-сервиса необходимо обеспечить выполнение всех требуемых действий в клиентской и серверной частях. 1. На стороне клиентской части веб-сервиса: - Подготовить решение для сбора данных, необходимых для вызова платёжной формы. Минимальный набор таких данных для проведения оплаты содержит идентификаторы проекта, платежа и пользователя, а также сумму и код валюты платежа. - Если выбран способ открытия Payment Page в модальном окне или в элементе iframe HTML-страницы — подключить CSS-библиотеку \([https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css)\), добавив её к странице веб-сервиса с помощью элемента ``, который следует разместить внутри заголовка страницы. **Внимание:** Следует учитывать, что для корректной работы платёжной формы CSS-библиотека от Ecommpay должна подключаться через сеть доставки содержимого \(Content Delivery Network, CDN\); локальное хранение этой библиотеки не допускается. ```language-xml ... ... ``` Это необходимо для корректного отображения платёжной формы при указанных способах открытия. Если же выбран способ открытия в отдельной вкладке браузера, подключение этой библиотеки не требуется. - Реализовать отправку собранных данных в серверную часть веб-сервиса для их подписывания и обеспечить приём подписанных данных от серверной части. - Реализовать возможности вызова Payment Page выбранными способами: в отдельной вкладке браузера, в модальном окне и \(или\) в элементе iframe HTML-страницы. - Если необходимо фиксировать определённые интерфейсные события — открывать Payment Page в модальном окне или в элементе iframe HTML-страницы и реализовать функции для обработки таких событий. 2. На стороне серверной части веб-сервиса: - Обеспечить приём данных для подписывания от клиентской части веб-сервиса. - Реализовать алгоритм формирования подписи данных. - Обеспечить отправку подписанных данных в клиентскую часть веб-сервиса. - Обеспечить приём оповещений от платёжной платформы, с проверкой подписи и отправкой ответов о приёме, а также обработку информации из этих оповещений. ### Настройка политики обеспечения безопасности контента {#section_m5x_m2v_njc .section} При работе с платёжной формой рекомендуется использовать доступные инструменты для обеспечения безопасности контента, чтобы снижать риски внедрения сторонних данных и скриптов \(Cross-Site Scripting, XSS\), а также других видов кибератак. Прежде всего, это касается настройки директив Content Security Policy. С их помощью можно ограничивать на используемых HTML-страницах допустимые источники цифровых ресурсов, таких как скрипты, фреймы, изображения и элементы оформления — через явное указание доменов, с которых разрешена загрузка конкретных видов контента. В случаях с открытием платёжной формы в виде отдельной HTML-страницы применение директив Content Security Policy не актуально, однако при использовании других способов открытия \(со встраиванием в веб-сервис через модальное окно или элемент iframe\), как и при использовании специализированных редакций для классических карточных платежей и сервисов Apple Pay и Google Pay, директивы Content Security Policy играют важную роль в обеспечении безопасности платежей. Более того, если директивы Content Security Policy не содержат разрешений для необходимых источников \(как минимум, для базового адреса открытия Payment Page\), то платёжная форма может работать некорректно. Чтобы настроить директивы Content Security Policy на стороне веб-сервиса, необходимо добавить актуальные директивы в HTTP-заголовок `Content-Security-Policy`. ``` {#codeblock_ejr_n4k_mjc} Content-Security-Policy: script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com; style-src https://paymentpage.ecommpay.com; img-src https://applepay.cdn-apple.com; frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com ``` После настройки или изменения директив Content Security Policy рекомендуется проверять корректность работы Payment Page \(в тестовом режиме, с указанием тестового проекта\). При этом желательно проверять, по крайней мере, следующее: 1. Отсутствие ошибок, связанных с Content Security Policy, в консоли браузера. 2. Корректность работы платёжной формы в используемых со стороны веб-сервиса сценариях. 3. При использовании метода Apple Pay — корректность работы с этим методом \(включая корректность отображения всех интерфейсных элементов\). При возникновении вопросов, касающихся работы с директивами Content Security Policy или использования других инструментов для обеспечения безопасности контента, можно обращаться к специалистам технической поддержки Ecommpay. ### Использование JavaScript-библиотеки {#section_wvv_kvj_jlb .section} JavaScript-библиотека Ecommpay подключается к клиентской части веб-сервиса и позволяет открывать Payment Page в модальном окне и в элементе iframe HTML-страницы.Кроме того, использование такой библиотеки позволяет отслеживать информацию об интерфейсных событиях в платёжной форме: выборе платёжного метода, изменении значений полей ввода и других \([подробнее](ru_pp_ui_monitoring.md)\). Если используется JavaScript-библиотека, на стороне серверной части могут использоваться как собственные решения, так и SDK веб-сервисов. А на стороне клиентской части необходимо: - Подготовить решение для сбора данных, необходимых для вызова платёжной формы. Минимальный набор таких данных для проведения оплаты содержит идентификаторы проекта, платежа и пользователя, а также сумму и код валюты платежа. - Подключить CSS- и JavaScript-библиотеки \([https://paymentpage.ecommpay.com/shared/merchant.css](https://paymentpage.ecommpay.com/shared/merchant.css) и [https://paymentpage.ecommpay.com/shared/merchant.js](https://paymentpage.ecommpay.com/shared/merchant.js)\), добавив к странице веб-сервиса с помощью элементов `` для CSS-библиотеки и ` ... ``` - Реализовать отправку собранных данных в серверную часть веб-сервиса для их подписывания и обеспечить приём подписанных данных от серверной части. - Реализовать возможности вызова Payment Page по щелчку кнопки или по иному событию в пользовательском интерфейсе выбранным способом: в модальном окне или в элементе iframe HTML-страницы — с использованием JavaScript-объекта EPayWidget. - Если необходимо фиксировать определённые интерфейсные события — открывать Payment Page в модальном окне или в элементе iframe HTML-страницы и реализовать функции для обработки таких событий. ### Использование SDK для веб-сервисов {#section_jw3_lvj_jlb .section} SDK для веб-сервисов встраиваются в серверную часть веб-сервиса и позволяют осуществлять формирование подписи к запросам и обрабатывать оповещения. Если используются эти SDK, на стороне клиентской части могут использоваться как собственные решения, так и библиотека JavaScriptи SDK для мобильных приложений. А на стороне серверной части необходимо обеспечить: - Приём запросов от клиентской части веб-сервиса. - Формирование подписи с использованием библиотек из состава SDK. - Отправку подписанного набора параметров в клиентскую часть веб-сервиса. - Приём оповещений и отправку ответов о приёме, а также использовать методы, доступные для работы с оповещениями при использовании SDK для веб-сервисов. Подробная информация о подключении и использовании всех доступных SDK представлена в разделе [Интеграция с использованием SDK](ru_sdk_overview.md). ### Использование SDK для мобильных приложений {#section_osm_lvj_jlb .section} SDK для мобильных приложений встраиваются в клиентскую часть приложения и позволяют работать с платёжной формой, адаптированной под мобильные интерфейсы. Если используются эти SDK, на стороне серверной части могут использоваться как собственные решения, так и SDK для веб-сервисов. А на стороне клиентской части необходимо: - Подготовить страницу веб-сервиса для сбора данных, необходимых для вызова платёжной формы. Минимальный набор данных, который необходимо собрать для проведения оплаты, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. - Обеспечить выполнение других необходимых действий с использованием необходимых библиотек из состава SDK. Подробная информация о подключении и использовании всех доступных SDK представлена в разделе [Интеграция с использованием SDK](ru_sdk_overview.md). ### Использование плагина для CMS {#section_ekc_lvj_jlb .section} Плагины для CMS встраиваются через административный интерфейс и позволяют решать все необходимые задачи для работы через Payment Page. Дополнительных доработок веб-сервиса при использовании таких плагинов не требуется. Информация о подключении и использовании плагинов для веб-сервисов, созданных на базе рядаCMS, представлена разделе [Интеграция с использованием плагинов](ru_CMS.md). ## Порядок работы с запросами {#ru_pp_interaction_requests_processing_scheme} Взаимодействие между веб-сервисом и Payment Page начинается с отправки запроса на открытие Payment Page для выполнения целевого действия. При получении такого запроса в платёжной платформе выполняются следующие действия: - На этапе приёма запроса обеспечивается проверка наличия минимального набора параметров и корректности подписи. - Если данные корректны, то запрос переводится на этап обработки и отправляется ответ о приёме запроса в обработку. - Если обнаружены ошибки, то работа с запросом прекращается и пользователю отображается информация об ошибке. При этом оповещение к веб-сервису не направляется. - На этапе обработки запроса сначала на стороне платёжной платформы выполняется подготовка Payment Page согласно настройкам проекта и параметрам вызова, а затем выполняется взаимодействие с пользователем с применением интерфейса платёжной формы. - Если пользователь подтверждает выполнение целевого действия, то запрос переводится на этап выполнения. Для всех целевых действий, за исключением формирования токена, на этом этапе в платформе регистрируется платёж: создаётся объект `payment`. - Если пользователь не подтверждает выполнение целевого действия, то работа с запросом прекращается. В этом случае не регистрируется платёж и не отправляется оповещение к веб-сервису. - На этапе выполнения запроса обеспечивается выполнение всех необходимых действий для получения целевого результата. - Если запрос выполнен, то к веб-сервису направляется оповещение о результате. - Если при выполнении запроса возникла ошибка, то работа с запросом прекращается и к веб-сервису направляется оповещение с информацией об этой ошибке. ## Форматы данных {#ru_PP_Formats} ### Общая информация {#section_rb3_k4q_xvb .section} При работе с Payment Page, как и при работе с другими интерфейсами платёжной платформы Ecommpay, должны использоваться допустимые способы кодирования и форматы представления данных.Основные сведения о них представлены в настоящей статье и [в спецификации](ru_PP_Parameters.md) параметров вызова платёжной формы. Дополнительно, когда это актуально, следует использовать также специализированные [Справочники](ru_directory.md), описания конкретных платёжных методов в разделе [Платёжные методы](ru_pm_about.md) и статьи об используемых возможностях. Наконец, при возникновении вопросов и выявлении проблем, касающихся форматов данных, можно обращаться к специалистам технической поддержки Ecommpay. ### Кодирование данных {#section_wqp_l4q_xvb .section} При формировании запросов к платформе и при обработке полученных от платформы ответов и оповещений должна использоваться кодировка UTF-8. Кроме того, в некоторых случаях должны дополнительно применяться другие способы кодирования, в частности Base64.Такие случаи отдельно оговариваются в рамках настоящей документации, в том числе [в спецификации](ru_PP_Parameters.md) параметров вызова платёжной формы. ### Указание даты и времени {#section_ezl_m4q_xvb .section} При работе с платформой дата и время, как правило, указываются в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\), где `ГГГГ-ММ-ДД` — дата, `T` — служебный символ, `чч:мм:сс` — время, `чч:мм` — отклонение от всемирного координированного времени. Например, `2025-05-25T15:30:25+00:00`. Вместе с тем, в некоторых случаях дата и время могут указываться иначе.Такие случаи отдельно оговариваются в рамках настоящей документации, прежде всего [в спецификации](ru_PP_Parameters.md) параметров вызова платёжной формы и в описаниях конкретных платёжных методов. ### Указание сумм {#section_hhj_n4q_xvb .section} Суммы платежей и операций при работе с платформой, как правило, указываются в дробных единицах валюты, без применения десятичного разделителя. Так, 100 долларов США представляются в центах и указываются как 10000 \(но не 100 и не 100,00\).И аналогично для других валют с учётом их специфики. |Валюта|Сумма|Представление| |------|-----|-------------| |EUR|39,95|`3995`| |GBP|450,66|`45066`| |JPY|200|`200`| |KWD|150,155|`150155`| Количество дробных разрядов для каждой валюты определяется в соответствии со стандартом [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html) и представлено [в справочнике валют](ru_currency_codes.md). ### Указание кодов валют, стран и языков {#section_b3q_p4q_xvb .section} При работе с платёжной платформой Ecommpay могут применяться: - трёхбуквенные *коды валют* — в соответствии со стандартом [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html); - двухбуквенные *коды стран* — в соответствии со стандартом [ISO 3166-1](https://www.iso.org/ru/iso-3166-country-codes.html); - одно-, двух- и трёхсимвольные *коды территорий* \(таких как штаты, провинции и регионы\) — в соответствии стандартом [ISO 3166-2](https://www.iso.org/ru/iso-3166-country-codes.html); - *коды языков* — двухбуквенные в соответствии со стандартом [ISO 639-1](https://www.iso.org/ru/iso-639-language-codes.html) или иные, согласованные со специалистами Ecommpayи используемые, например, для открытия платёжной формы на определённом диалекте того или иного языка. Перечни таких кодов, за исключением кодов территорий и кодов языков, согласуемых отдельно, приведены в [справочниках](ru_directory.md). ## Формат запроса {#ru_pp_interaction_request_format} ### Общая информация {#section_ivx_zr1_dmb .section} При работе с Payment Page все данные от веб-сервиса должны передаваться *в запросах* — HTTP-сообщениях заданной структуры. При этом набор данных и параметры адресации таких запросов зависят от выбранного способа открытия платёжной формы. В этом разделе представлена информация о поддерживаемых методах отправки запросов на открытие Payment Page и параметрах адресации таких запросов. ### Методы отправки {#section_ntk_zvx_jlb .section} Вне зависимости от выбранного способа открытия Payment Page для отправки HTTP-запросов поддерживаются методы POST и GET. Выбор метода осуществляется на стороне веб-сервиса и не ограничивается со стороны платёжной платформы. По умолчанию, если в HTTP-запросе не указано другое, запросы идентифицируются как отправленные методом GET. Однако в связи с тем, что в некоторых браузерах максимальная длина URL может ограничиваться, при передаче таких сведений, как информация о товарных позицияхили «длинная запись», рекомендуется использовать метод POST. Основные характеристики методов POST и GET представлены далее. | |POST|GET| |--|----|---| |Уровень безопасности|Более высокий за счёт передачи параметров в теле запроса|Менее высокий в связи с передачей параметров в адресной строке| |Возможность передачи всех параметров Payment Page API|+|\*| |Возможность передавать в виде ссылки|–|+| \* Ограничение объёма передаваемых данных допустимой длиной URL. ``` GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1 Host: https://paymentpage.ecommpay.com ``` ``` POST /payment HTTP/1.1 Host: https://paymentpage.ecommpay.com { "payment_currency": EUR, "project_id": 42, "payment_amount": 1000, "customer_id": 123, "payment_id": "4438", "signature": "AE5hmtzdP0Dt7qGTg..." } ``` ### Параметры адресации {#section_jl5_zq1_dmb .section} При формировании запросов на открытие Payment Page в отдельной вкладке браузера адреса отправки указываются следующим образом: - Если используется метод GET отправки запросов, в качестве доменного имени запрашиваемого ресурса необходимо указывать базовый адрес Payment Page \(https://paymentpage.ecommpay.com\), а в качестве целевого адреса — URL, используемый для выполнения целевых действий через Payment Page, знак вопроса `?` и строку данных, состоящую из пар названий и значений параметров. Названия и значения разделяются знаками `=`, а сами пары разделяются знаками `&`. ``` // URL, используемый для выполнения целевых действий через Payment Page /payment // Строка данных payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D // Полный адрес https://paymentpage.ecommpay.com/payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D ``` - Если используется метод POST отправки запросов, в качестве доменного имени запрашиваемого ресурса необходимо указывать базовый адрес Payment Page \(https://paymentpage.ecommpay.com\), а в качестве целевого адреса — URL, используемый для выполнения целевых действий через Payment Page. Данные в этом случае передаются в теле запроса. При формировании запросов на открытие Payment Page в элементе iframe или в модальном окне, как правило, адреса отправки указывать не требуется. ## Формат ответа {#ru_pp_interaction_response_format} Со стороны Payment Page получение запроса подтверждается отправкой к пользовательскому браузеру ответа — HTTP-сообщения заданной структуры — в рамках того же сеанса. Передаваемые в ответе данные включают в себя: - сведения о приёме запроса, если запрос принят в обработку; - сведения об ошибке, если запрос не может быть принят в обработку. Перечень кодов ответов и пояснительных фраз, используемых в ответах, приведён далее в таблице. |Код с пояснением|Описание| |----------------|--------| |200 OK|Запрос успешно принят, можно ожидать итоговое оповещение. Пользователю отображается платёжная форма | |400 Bad Request|Запрос не может быть принят из-за отсутствия в наборе данных обязательного параметра, например идентификатора проекта, или из-за некорректной подписи. Пользователю отображается сообщение об ошибке | |404 Not Found|Запрос не может быть обработан из-за некорректно указанных `project_id` или `urlBase`. Пользователю отображается сообщение об ошибке | |500 Internal Error|Запрос не может быть обработан из-за сбоя в платёжной платформе. Пользователю отображается сообщение об ошибке | ## Формат оповещения {#ru_pp_interaction_callback_format} Для передачи промежуточной и итоговой информации о результате обработки и выполнения запроса в рамках асинхронного взаимодействия используются оповещения — HTTP-запросы, отправляемые методом POST от платёжной платформы на согласованные адреса. Общая структура оповещений описана далее, а подробная информация о работе с ними — в разделе [Работа с оповещениями](ru_platform_callbacks.md). В каждом оповещении от платформы содержатся следующие элементы в порядке перечисления: - стартовая строка с указанием метода передачи запроса \(`POST`\), URL веб-сервиса для отправки оповещений о результатах \(в примере — `/notify/success`\), протокола и его версии \(`HTTP/1.1`\); - поля заголовка, в том числе поле `Host` с указанием доменного имени веб-сервиса \(в примере — `webservice.com`\); - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним. Далее представлен пример оповещения с информацией о результате проведения платежа. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения. ```language-json POST /notify/success HTTP/1.1 Content-Length: 1237 User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1 Content-Type: application/json Host: webservice.com { "account":{ "number":"431422******0056", "token":"1234567890", "type":"visa", "card_holder":"TEST TEST", "id":1234, "expiry_month":"**", "expiry_year":"****" }, "customer":{ "id":"12345", "phone":"***********" }, "payment":{ "date":"2019-06-07T11:38:31+0000", "id":"1234567890", "method":"card", "status":"success", "sum":{ "amount":17500, "currency":"EUR" }, "type":"purchase", "description":"Deposit to 1234567890" }, "project_id":25, "processingDateTime":"2019-06-07T11:38:30+0000", "country":"BE", "product_name":"Visa", "issuer_name":"", "operation":{ "id":1234567890, "type":"sale", "status":"success", "date":"2019-06-07T11:38:32+0000", "created_date":"2019-06-07T11:37:56+0000", "request_id":"1234567890-1234567890", "sum_initial":{ "amount":17500, "currency":"EUR" }, "sum_converted":{ "amount":17500, "currency":"EUR" }, "provider":{ "id":11, "payment_id":"098765432", "date":"2019-06-07T11:38:30+0000", "auth_code":"", "endpoint_id":1 }, "code":"0", "message":"Success", "eci":"05" }, "signature":"qwertyuioiuytrewqwertyuu123434" } ``` --- # Интеграция с использованием SDK {#ru_sdk_overview} статьи о порядке применения SDK для интеграции Payment Page в мобильные приложения и для создания и проверки подписи к данным ## SDK для мобильных приложений {#section_lx5_fgq_pvb .section} Чтобы проводить платежи через платёжную платформу Ecommpay непосредственно из интерфейсов мобильных приложений,без перенаправлений к браузерам для открытия платёжной формы, можно использовать специализированные наборы средств разработки\(SDK\). Они обеспечивают функциональное взаимодействие для обмена всей необходимой информацией между клиентскими частями приложений и платёжной платформой, а также позволяют применять различные пользовательские интерфейсы: для этого в SDK UI & Core входят интерфейсные компоненты от Ecommpay, а в SDK Core предусматривается возможность использования собственных интерфейсных компонентов мерчанта. В настоящее время для использования доступны следующие версии SDK для мобильных приложений. | |![](images/universal/pr_lang_logos/android.svg)|![](images/universal/pr_lang_logos/apple.svg)| |--|-----------------------------------------------|---------------------------------------------| |**UI & Core** с пользовательским интерфейсом от Ecommpay | для Android 5.0 и выше: - [универсальный SDK](ru_sdk_ui_and_core_android.md) - [SDK для платформы Flutter 3.3.0 и выше](ru_sdk_flutter.md) - [SDK для платформы React Native 0.75.3 и выше](ru_sdk_react_native.md) | для iOS 15.6 и выше: - [универсальный SDK](ru_sdk_ui_and_core_ios.md) - [SDK для платформы Flutter 3.3.0 и выше](ru_sdk_flutter.md) - [SDK для платформы React Native 0.75.3 и выше](ru_sdk_react_native.md) | |**Core** с возможностью использования собственного пользовательского интерфейса | [для Android 5.0 и выше](ru_sdk_core_android.md) | [для iOS 11.0 и выше](ru_sdk_core_ios.md) | С вопросами об условиях и порядке использования SDK для мобильных приложений, а также с предложениями о расширении их функциональности, всегда можно обращаться к курирующему менеджеру Ecommpay; с вопросами о способах интеграции, тестирования и применения этих SDK — к специалистам технической поддержки. ## SDK для работы с подписью {#section_o1r_2pd_qvb .section} Чтобы обеспечивать работу с цифровой подписью, необходимой для программного взаимодействия с платёжной платформой Ecommpay, можно использовать специализированные наборы средств разработки \(SDK\). Они позволяют подписывать наборы параметров, включаемых в запросы, и проверять корректность подписи в ответах и оповещениях от платформы \(подробнее о соответствующих алгоритмах — [в отдельной статье](ru_platform_signature.md)\). В работе таких SDK должны использоваться секретные ключи шифрования, получаемые для каждого из проектов от Ecommpay, поэтому эти SDK следует применять в серверной части веб-сервисов, с обеспечением надлежащих мер безопасности. В настоящее время для использования доступны SDK для работы с подписьюна следующих языках программирования: - [C\#](ru_sdk_net.md) с использованием .NET 6.0 и выше - [Go](ru_sdk_go.md) 1.8 и выше - [Java](ru_sdk_java.md) с использованием JDK 8 и выше - [JavaScript](ru_sdk_javascript.md) с использованием Node.js 4.x - [PHP](ru_sdk_php.md) 7.0 и выше - [Python](ru_sdk_python.md) 3.5 и выше С вопросами об условиях и порядке использования SDK для работы с подписью, а также с предложениями о расширении их функциональности всегда можно обращаться к курирующему менеджеру Ecommpay; с вопросами о способах интеграции, тестирования и применения этих SDK — к специалистам технической поддержки. - **[SDK UI & Core для Android](ru_sdk_ui_and_core_android.md)** статья о порядке применения SDK UI & Core для интеграции платёжной формы с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе Android - **[SDK UI & Core для iOS](ru_sdk_ui_and_core_ios.md)** статья о порядке применения SDK UI & Core для интеграции платёжной формы с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе iOS - **[SDK Flutter для Android и iOS](ru_sdk_flutter.md)** статья о порядке применения SDK Flutter для интеграции платёжной формы в мобильные приложения на платформах Android и iOS - **[SDK React Native для Android и iOS](ru_sdk_react_native.md)** статья о порядке применения SDK React Native для интеграции платёжной формы в мобильные приложения на платформах Android и iOS - **[SDK Core для Android](ru_sdk_core_android.md)** статья о порядке применения SDK Core для интеграции платёжной формы с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе Android - **[SDK Core для iOS](ru_sdk_core_ios.md)** статья о порядке применения SDK Core для интеграции платёжной формы с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе iOS - **[SDK для C\# на платформе .NET](ru_sdk_net.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке C\# на платформе .NET - **[SDK для Go](ru_sdk_go.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Go - **[SDK для Java](ru_sdk_java.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Java - **[SDK для JavaScript](ru_sdk_javascript.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке JavaScript - **[SDK для PHP](ru_sdk_php.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке PHP - **[SDK для Python](ru_sdk_python.md)** статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Python **На уровень выше:**[Payment Page](ru_PP_about.md) --- # SDK UI & Core для Android {#ru_sdk_ui_and_core_android} статья о порядке применения SDK UI & Core для интеграции платёжной формы с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе Android **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_ui_and_core_android_overview} ### Введение {#section_spc_d32_2vb .section} Mobile SDK UI & Core для Android — это набор средств разработки с открытым программным кодом, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, работающих на платформе Android. SDK UI & Core для Android позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой для отправки и приёма необходимой информации при проведении платежей, а также обеспечивает интерфейсное взаимодействие с пользователем. Кроме того, за счёт открытого программного кода при использовании SDK UI & Core для Android можно гибко настраивать пользовательский интерфейс, адаптируя его под специфику приложения. SDK UI & Core для Android можно встраивать в мобильные приложения, работающие на платформе Android версии 5.0 и выше. Библиотеки SDK UI & Core для Android и примеры кода расположены на портале GitHub. Для работы с ними можно использовать следующие ссылки: - Список версий SDK UI & Core для Android: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/releases) - Примеры кода: [https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example](https://github.com/ITECOMMPAY/mobile-sdk-android-ui/tree/master/integration-example) ### Возможности {#section_rdk_l32_2vb .section} При работе с SDK UI & Core для Android доступны следующие возможности: - Проведение платежей различных типов с прямым использованием платёжных карти с применением метода Google Pay, а также других платёжных методов, доступных в рамках проекта мерчанта. К поддерживаемым типам платежей относятся: - одностадийные разовые оплаты; - двухстадийные разовые оплаты \(с блокировкой средств через SDK и последующим списанием через Gate или Dashboard\); - повторяемые оплаты \(с регистрацией через SDK и последующим управлением списаниями через Gate или Dashboard\). **Прим.:** При проведении платежей с использованием карт и метода Google Pay задействуется платёжный интерфейс, описанный в этой статье, а при проведении платежей с использованием других платёжных методов — платёжная форма Payment Page. - Проверка действительности платёжных карт \(с проведением условных платежей на нулевые суммы\). - Контроль состояния платежей. - Поддержка различных вспомогательных процедур и дополнительных возможностей для повышения проходимости платежей, включая: - дополнение информации о платежах; - повторные попытки проведения платежей; - каскадное проведение платежей; - сбор данных о пользователях. - Поддержка различных дополнительных возможностей для улучшения пользовательского опыта, включая: - сохранение платёжных данных пользователей; - управление языком платёжного интерфейса; - отправку пользователям уведомлений с информацией о товарных позициях по проведённым платежам. - Возможности индивидуального оформления платёжного интерфейса, включая его стилизацию за счёт использования логотипа и настройки цветовой палитры, а также более глубокую адаптацию к специфике приложения за счёт работы с открытым программным кодом SDK. ### Схема работы {#section_lws_232_2vb .section} В общем случае одностадийные оплаты с использованием SDK UI & Core для Android проводятся в соответствии со следующей схемой. ![](images/sdk/android/ru_sdk_ui_core_functional.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK UI & Core для Android этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта. 3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK UI & Core для Android. 4. С помощью SDK UI & Core для Android инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы выполняются подготовка платёжного интерфейса с учётом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса. 6. В мобильном приложении пользователю отображается форма оплаты. 7. Пользователь выбирает платёжный метод \(если он не был задан при открытии платёжной сессии\),указывает необходимую информацию и подтверждает готовность провести оплату. 8. От SDK UI & Core для Android к платёжной платформе отправляется запрос на проведение оплаты. 9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам иплатёжным системам. 10. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 11. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 12. От платёжной платформы к SDK UI & Core для Android направляется информация о результате оплаты. 13. Информация о результате отображается в пользовательском интерфейсе. ### Интерфейс {#section_rsg_3jf_fvb .section} При проведении платежейс использованием платёжных карт и альтернативного метода Google Pay пользователю отображается интерфейс, разработанный специалистами Ecommpay. Со стороны мерчанта можно настраивать цвет этого интерфейса и добавлять логотип. ![](images/sdk/android/all_sdk_ui_core_design_color.svg "Варианты индивидуального оформления") ![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Страница указания платёжных данных") ![](images/sdk/android/all_sdk_ui_core_design_result.png "Страница уведомления о результате платежа") ## Подготовка к использованию {#ru_sdk_ui_and_core_android_setup} ### Порядок интеграции {#section_slp_nvf_fvb .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK UI & Core для Android со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK UI & Core для Android и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Скачать и подключить библиотеки SDK UI & Core для Android. 2. Обеспечить сбор данных, необходимых для вызова платёжной формы. Минимальный набор данных, который необходимо собрать для вызова платёжной формы, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK UI & Core для Android, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования \(в том числе с использованием доступных платёжных методов\)и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK UI & Core для Android следует обращаться в службу технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Установка библиотек {#section_fr4_txf_fvb .section} Для приложений, работающих на платформе Android версии 5.0 и выше, поддерживается подключение библиотек SDK UI & Core для Android через MavenCentral. Чтобы подключить библиотеки, необходимо выполнить следующее: 1. Открыть в приложении модуль `build.gradle.kts`. 2. Указать в секции `repositories` репозиторий `mavenCentral`: ```language-json allprojects { repositories { google() mavenCentral() } } ``` 3. Добавить в секцию `dependencies` следующее: ```language-json implementation "com.ecommpay:msdk-ui:LATEST\_VERSION" ``` ### Обеспечение работы с подписью {#section_nsw_rbg_fvb .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта. Порядок работы с подписью представлен в разделе [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_ui_and_core_android_testing} Перед проведением реальных платежей через SDK UI & Core для Android рекомендуется протестировать проведение платежей с использованием тестового проекта. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде Ecommpay \(сделать это можно [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\). Также по согласованию со специалистами Ecommpay можно протестировать использование метода Google Pay идополнительных возможностей, таких как каскадное проведение платежей и сбор данных о пользователях. Чтобы протестировать проведение платежей, необходимо: 1. Открыть в приложении модуль `build.gradle.kts`. 2. Указать идентификатор тестового проекта \(`projectId`\) и секретный ключ от него \(`projectSecretKey`\). 3. Запустить процесс синхронизации `gradle`. Чтобы перейти в рабочий режим, необходимо заменить тестовые значения \(идентификатор рабочего проекта и секретный ключ от него\) на рабочие. ## Использование {#ru_sdk_ui_and_core_android_use} ### Вызов платёжной формы {#ru_sdk_ui_and_core_android_openingpf} SDK UI & Core для Android поддерживает выполнение таких целевых действий как проведение одностадийных разовых оплат, блокировка средств пользователей в рамках проведения двухстадийных оплат, регистрация повторяемых оплат и проверка действительности платёжных карт. Для инициирования таких действий требуется определённый набор параметров: обязательный минимум параметров передаётся в объекте `EcmpPaymentInfo`, в то время как остальные параметры могут быть переданы в объекте `EcmpPaymentOptions`, запрошены у пользователя, а также получены со стороны платёжной платформы. Для вызова платёжной формы необходимо выполнить следующие действия: 1. Создать объект `EcmpPaymentInfo`. - Этот объект должен содержать следующие обязательные параметры: - `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay; - `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта; - `paymentCurrency` \(string\) — код валюты платежа в формате ISO-4217 alpha-3; - `paymentAmount` \(integer\) — сумма платежа в дробных единицах валюты; - `customerId` \(string\) — идентификатор пользователя в рамках проекта; - `signature` \(string\) — подпись запроса, составленная после указания всех целевых параметров. - Дополнительно могут использоваться и другие параметры, представленные [в следующей таблице](ru_sdk_ui_and_core_android.md#table_mhv_gqf_hvb). ```language-json val ecmpPaymentInfo = EcmpPaymentInfo( projectId = 77655, paymentId = payment_322, paymentAmount = 100, paymentCurrency = "USD", paymentDescription = "Cosmoshop payment", //Описание платежа customerId = "customer_003", regionCode = "DE", //Код страны проживания пользователя token = "o8i7u65y4t3rkjhgfdw3456789oikjhgfdfghjkl...", //Токен платёжных данных languageCode = "de", //Код языка отображения платёжного интерфейса receiptData = "eyAKICAicG9zaXRpb25zIjpbIAxLAogICAgICAgICJhbW91bnQiOjU5OTAsCiAgQ==", //Данные уведомления с информацией о товарных позициях hideSavedWallets = false, // Параметр отображения сохранённых платёжных данных forcePaymentMethod = card //Код предварительно выбранного платёжного метода ) ``` 2. Подписать параметры из объекта `EcmpPaymentInfo`. ```language-json ecmpPaymentInfo.signature = SignatureGenerator.generateSignature( paramsToSign = ecmpPaymentInfo.getParamsForSignature(), secret = SECRET_KEY ) ``` 3. Создать объект `EcmpPaymentOptions`. - Этот объект должен содержать следующие обязательные параметры: - Для любых платежей —параметр `actionType`, в котором необходимо указать целевое действие: тип операции `Sale`, `Auth` или `Verify`; - Для оплат с прямым использованием платёжных карт —параметр `CUSTOMER_EMAIL` или параметр `CUSTOMER_PHONE` объекта `additionalFields` \(по крайней мере один из них\) для отображения пользователю соответствующих полей на страницах платёжной формы. - Для аутентификации 3‑D Secure рекомендуется указать следующие параметры со сведениями о платёжном адресе: - `BILLING_COUNTRY` — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\); - `BILLING_POSTAL` — индекс платёжного адреса пользователя; - `BILLING_CITY` — название города платёжного адреса пользователя; - `BILLING_ADDRESS` — название улицы платёжного адреса пользователя. Эти параметры указываются в объекте `additionalFields` и соответствующие поля отображаются пользователю на страницах платёжной формы. **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование таких параметров может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. - Дополнительно могут использоваться и другие параметры, представленные [в следующей таблице](ru_sdk_ui_and_core_android.md#table_g34_3h5_hvb) Следующий пример помимо обязательных для любых платежейобъекта `EcmpPaymentInfo` и параметра `actionType` содержит обязательныйдля оплат с прямым использованием платёжных карт параметр `CUSTOMER_EMAIL` и ряд дополнительных параметров, в том числе в объекте `additionalFields`. ```language-json val paymentOptions = paymentOptions { paymentInfo = ecmpPaymentInfo actionType = EcmpActionType.Sale brandColor = "#800008" isDarkTheme = false logoImage = BitmapFactory.decodeResource(resources, R.drawable.example_logo) hideScanningCards = false isTestEnvironment = true merchantId = BuildConfig.GPAY_MERCHANT_ID merchantName = "Example Merchant Name" screenDisplayModes { mode(EcmpScreenDisplayMode.HIDE_DECLINE_FINAL_SCREEN) mode(EcmpScreenDisplayMode.HIDE_SUCCESS_FINAL_SCREEN) } additionalFields { field { type = EcmpAdditionalFieldType.CUSTOMER_EMAIL value = "mail@mail.com" } field { type = EcmpAdditionalFieldType.CUSTOMER_FIRST_NAME value = "firstName" } } } ``` 4. Создать объект `EcmpPaymentSDK`. ```language-json val sdk = EcmpPaymentSDK( context = applicationContext, paymentOptions = paymentOptions, ) ``` При необходимости платёжную форму можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок протестировать проведение оплат с определённым результатом. Для этого в запросе на открытие платёжной формы в объекте `EcmpPaymentSDK` следует передать значение `EcmpPaymentSDK.EcmpMockModeType.SUCCESS` для параметра `mockModeType` \(если необходим результат — платёж проведён\). Также можно использовать значения `EcmpPaymentSDK.EcmpMockModeType.DECLINE` \(если необходим результат — платёж отклонён\) и `EcmpPaymentSDK.EcmpMockModeType.DISABLED` \(для открытия формы в рабочем режиме\). 5. Открыть платёжный интерфейс. ```language-json sdk.openPaymentScreen(this, 1234) ``` ### Проведение платежей {#ru_sdk_ui_and_core_android_payments} По умолчанию в SDK UI and Core для Android настроено проведение разовых одностадийных оплат \(с типом действия `Sale`\). Для проведения оплат такого типа можно использовать приведённые выше примеры и дополнительно ничего не настраивать. Вместе с тем при работе с SDK UI & Core для Android можно проводить и двухстадийные оплаты \(с блокировкой средств через SDK и последующим списанием\). Для этого следует: 1. Вызвать платёжную форму, задав тип действия `EcmpActionType.Auth` в объекте `paymentOptions`: ```language-java (EcmpPaymentOptions.EcmpActionType.Auth); ``` 2. Когда потребуется, подтвердить списание средств через Dashboard \([подробнее](ru_dbl_payments.md)\) или через Gate \(с помощью запроса к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture)\). ### Проверка действительности платёжных карт {#ru_sdk_ui_and_core_android_verify} Проверка действительности платёжного инструмента может использоваться, когда необходимо проверить действительность карты без списания средств \(например, перед выплатой на эту карту\) или сохранить данные карты для их дальнейшего использования. По сути это условный платёж со списанием нулевой суммы. Для такой проверки следует вызвать платёжную форму, задав тип действия `EcmpActionType.Verify` в объекте `paymentOptions`: ```language-java (EcmpPaymentOptions.EcmpActionType.Verify); ``` ### Получение информации о платеже {#ru_sdk_ui_and_core_android_status} Для получения уведомлений о результатах проведения платежей используется метод `onActivityResult`. ```language-json override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) when (resultCode) { EcmpPaymentSDK.RESULT_SUCCESS -> { Toast.makeText(this, "Payment was finished successfully", Toast.LENGTH_SHORT).show() Log.d("PaymentSDK", "Payment was finished successfully") } EcmpPaymentSDK.RESULT_CANCELLED -> { Toast.makeText(this, "Payment was cancelled", Toast.LENGTH_SHORT).show() Log.d("PaymentSDK", "Payment was cancelled") } EcmpPaymentSDK.RESULT_DECLINE -> { Toast.makeText(this, "Payment was declined", Toast.LENGTH_SHORT).show() Log.d("PaymentSDK", "Payment was declined") } EcmpPaymentSDK.RESULT_ERROR -> { val errorCode = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_CODE) val message = data?.getStringExtra(EcmpPaymentSDK.EXTRA_ERROR_MESSAGE) Toast.makeText(this, "Payment was interrupted. See logs", Toast.LENGTH_SHORT).show() Log.d( "PaymentSDK", "Payment was interrupted. Error code: $errorCode. Message: $message" ) } } } ``` Допустимые коды результатов проведения платежей: - `RESULT_SUCCESS` — платёж проведён; - `RESULT_CANCELLED` — платёж отменён; - `RESULT_DECLINE` — платёж отклонён; - `RESULT_ERROR` — возникла ошибка при проведении платежа. ### Применение дополнительных возможностей {#ru_sdk_ui_and_core_android_additional_capabilities} #### Дополнение информации о платеже {#section_a2c_kvn_fvb .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Подробная информация о процедуре дополнения информации о платеже представлена [в отдельной статье](ru_pp_clarification.md). Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список данных, актуальных для конкретного платежа, отображается пользователю в платёжном интерфейсе. Пользователь указывает запрашиваемые данные, подтверждает проведение платежа и получает информацию о результате. #### Каскадное проведение платежей {#section_chg_3vn_fvb .section} В случаях, когда по каким-либо причинам попытка проведения платежа не завершилась успешно, можно использовать каскадное проведение платежей \([подробнее](ru_pp_cascading.md)\), которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеровбез изменения платёжного метода. Подключение этой возможности необходимо согласовывать со специалистами Ecommpay. Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK UI & Core для Android поступает уведомление, в котором содержится признак `cascading_with_redirect = true`. Пользователю при этом отображается страница с ошибкой и кнопкой для выполнения очередной попытки. Если в рамках дополнительной попытки не требуется аутентификация 3‑D Secure, то попытка выполняется без взаимодействия с пользователем, иначе — отображается страница с повторной аутентификацией. #### Сбор данных о пользователях {#section_xln_lvn_fvb .section} В некоторых случаях вместе с обязательными данными актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Подробная информация об использовании возможности сбора дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). #### Управление языком платёжного интерфейса {#section_mcq_5xc_xyb .section} По умолчанию при работе с SDK UI & Core в платёжном интерфейсе используется язык устройства пользователя, если он поддерживается для используемого проекта, или язык, определённый по умолчанию для остальных случаев \(в общем случае — английский\). Вместе с тем, если это актуально, можно задавать определённые языки для конкретных сеансов. Для этого в каждом таком случае при вызове платёжной формы необходимо передавать соответствующий код языка в параметре `languageCode` \([подробнее](ru_sdk_ui_and_core_android.md)\). **Внимание:** При указании языка, не поддерживаемого для используемого проекта, платёжная форма не открывается и пользователю отображается информация об ошибке. К числу поддерживаемых в платформе для интерфейса SDK и доступных для оперативного подключения в проектах относятся следующие языки. |Язык|Код| |----|---| |Английский|`en`| |Испанский|`es`| |Итальянский|`it`| |Латышский|`lv`| |Литовский|`lt`| |Немецкий|`de`| |Португальский|`pt`| |Русский|`ru`| |Украинский|`uk`| |Французский|`fr`| |Эстонский|`et`| #### Сохранение платёжных данных {#section_ygy_gvn_fvb .section} При работе с SDK UI & Core для Android поддерживается сохранение платёжных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Возможность сохранения платёжных данных подключается для каждого проекта отдельно; со стороны мерчанта необходимо сообщить специалистам технической поддержки подходящий вариант сохранения: *всегда* или *по выбору пользователя*. Информация об этой возможности представлена в отдельной статье \([подробнее](ru_PP_saved_data.md)\). В результате сохранения платёжных данных для каждого платёжного инструмента формируется идентификатор, ассоциированный с идентификатором конкретного пользователя \(`customerId`\). Для отображения пользователю сохранённых данных его платёжных инструментов в объекте `EcmpPaymentOptions` необходимо передавать параметр `hideSavedWallets` со значением `false`. ## Параметры вызова {#ru_sdk_ui_and_core_android_parameters} Для работы с SDK UI & Core для Android в объекте `EcmpPaymentInfo` можно использовать следующие дополнительные параметры. |Параметр|Описание| |:-------|:-------| |`paymentDescription` string |Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase` | |`receiptData` string |Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg` | |`token` string |Токен платёжных данных. Представляет собой строку длиной не более 255 символов. Пример: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c` | |`hideSavedWallets` boolean |Параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов. Возможные значения: - `true` — не отображать сохранённые данные. - `false` — отображать сохранённые данные. | |`forcePaymentMethod` string |Код предварительно выбранного платёжного метода в соответствии [с таблицей](ru_pm_codes.md). Пример: `card` | |`ecmpThreeDSecureInfo` object |Объект, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2| |`languageCode` string |Код языка отображения платёжного интерфейса в формате ISO 639-1 alpha-2. Должен соответствовать одному из языков, поддерживаемых для используемого проекта. Пример: `IT` | |`regionCode ` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `IT` | В объекте `EcmpPaymentOptions` можно использовать следующие дополнительные параметры. |Параметр|Описание| |:-------|:-------| |`merchantID` string |Идентификатор мерчанта в сервисе Google Pay.| |`merchantName` string |Наименование мерчанта в сервисе Google Pay.| |`logoImage` bitmap |Файл с логотипом мерчанта в формате BMP.| |`brandColor` string |Цвет платёжного интерфейса в шестнадцатеричном формате HEX. Пример: `#800080` | |`isTestEnvironment` boolean |Признак тестового платежа. Возможные значения: - `true` — тестовый платёж. - `false` — платёж в рабочем режиме. | |`additionalFields` list |Дополнительные поля с информацией о пользователе. Содержит список параметров и может включать их значения. Пример: `EcmpAdditionalField(EcmpAdditionalFieldType.CUSTOMER_EMAIL,"mail@mail.com")` | |`recipientInfo` object — объект, содержащий сведения о получателе платежа | |`pan` string |Номер карты. Пример: `5443011850290191` | |`card_holder` string |Имя и фамилия \(в соответствии с указанными на карте\). Пример: `Sonya Kovalevsky` | |`wallet_id` string |Номер электронного кошелька. Пример: `WID301185029011891` | |`wallet_owner` string |Имя и фамилия получателя. Пример: `Sonya Kovalevsky` | |`country` string |Код страны проживания в формате ISO 3166-1 alpha-2. Пример: `SE` | |`address` string |Адрес проживания. Пример: `Albanovaegen 28` | |`city` string |Город проживания. Пример: `Stockholm` | |`state` string |Штат проживания. Пример: `AB` | Параметры для работы с повторяемыми оплатами необходимо передавать в объекте `recurrentData`, который входит в объект `EcmpPaymentOptions`. |Параметр|Описание| |:-------|:-------| |`type` string |Категория регистрируемой повторяемой оплаты. Возможные значения: - `C` — экспресс-оплата \(OneClick\) - `U` — автооплата - `R` — регулярная оплата | |`period` string |Указатель базового периода списаний \(для регулярной оплаты\). Возможные значения: - `D` — ежедневно - `W` — еженедельно - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\) - `Q` — ежеквартально - `Y` — ежегодно | |`expiry_day` string |Номер календарного дня, в который должна быть завершена повторяемая оплата\(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\)| |`expiry_month` string |Порядковый номер месяца, в котором должна быть завершена повторяемая оплата\(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\)| |`expiry_year` integer |Порядковый номер года, в котором должна быть завершена повторяемая оплата\(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\)| |`scheduled_payment_id` string |Идентификатор платежа, в рамках которого следует выполнять списания \(для автоматического инициирования списаний\), должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта. Параметр следует передавать вместе с параметром `start_date` | |`start_date` string |Дата первого списания\(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`| |`time` string |Время выполнения последующих списаний\(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`| |`schedule` object — расписание проведения повторяемых оплат \(можно задать со стороны мерчанта\). Следует указать параметры `amount` и `date` | |`amount` integer |Фиксированная сумма последующих списаний в дробных единицах валюты| |`date` string |Дата списания в формате `ДД-ММ-ГГГГ`| **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. В объекте `ecmpThreeDSecureInfo` можно использовать следующие дополнительные объекты и параметры. Их использование позволит повысить вероятность выбора варианта аутентификации 3‑D Secure без дополнительных действий со стороны пользователя \(frictionless flow\). |Параметр|Описание| |:-------|:-------| |`threeDSecureInfo` — объект класса `ECMPThreeDSecureInfo`, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2| |`threeDSecurePaymentInfo` — объект класса `ECMPThreeDSecurePaymentInfo`, содержащий информацию о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации| |`challengeIndicator` string |Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения: - `01` — без предпочтений, - `02` — предпочтительно не выполнять, - `03` — предпочтительно выполнять, - `04` — обязательно выполнять | |`challengeWindow` string |Размер окна для открытия страницы аутентификации. Возможные значения: - `01` — 250 x 400 пикселей, - `02` — 390 x 400 пикселей, - `03` — 500 x 600 пикселей, - `04` — 600 x 400 пикселей, - `05` — полноэкранный режим | |`preorderDate` string |Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`| |`preorderPurchase` string |Индикатор предварительного заказа. Возможные значения: - `01` — не является предварительным заказом, - `02` — является предварительным заказом | |`reorder` string |Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения: - `01` — первичная покупка, - `02` — повторная покупка | |`threeDSecureGiftCardInfo` — объект класса `ECMPThreeDSecureGiftCardInfo`, содержащий информацию об оплате предоплаченными или подарочными картами| |`amount` integer |Общая сумма оплаты предоплаченными или подарочными картами в дробных единицах валюты| |`currency` string |Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 \(например, [GBP](references/ru/currencies/GBP.md)\)| |`count` integer |Количество предоплаченных или подарочных карт, использованных для оплаты| |`threeDSecureCustomerInfo` — объект класса `ECMPThreeDSecureCustomerInfo`, содержащий информацию о пользователе| |`addressMatch` string |Указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте `threeDSecureShippingInfo`. Возможные значения: - `Y` — адреса совпадают, - `N` — адреса не совпадают | |`billingRegionCode` string |Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма| |`homePhone` string |Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх \(например, `44991234567`\)| |`workPhone` string |Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх \(например, `44997654321`\)| |`threeDSecureAccountInfo` — объект класса `ECMPThreeDSecureAccountInfo`, содержащий информацию об учётной записи пользователя на стороне мерчанта;| |`additional` string |Дополнительная информация об учётной записи пользователя, например её идентификатор; в произвольном формате с использованием до шестидесяти четырёх символов| |`activityDay` integer |Количество попыток проведения оплаты за последние 24 часа, не более трёх символов \(`999`\)| |`activityYear` integer |Количество попыток проведения оплаты за последние 365 дней, не более трёх символов \(`999`\)| |`ageIndicator` string |Количество дней с момента создания учётной записи пользователя. Возможные значения: - `01` — платёж проводится без аутентификации в учётной записи, - `02` — учётная запись создана в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`authData` string |Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов| |`authMethod` string |Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения: - `01` — доступ без аутентификации; - `02` — аутентификация с использованием данных, сохранённых на стороне мерчанта; - `03` — аутентификация с использованием Federated ID \(например, Google Account или Facebook\); - `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\) | |`authTime` string |Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`| |`date` string |Дата создания учётной записи в формате `ДД-ММ-ГГГГ`| |`changeDate` string |Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`| |`changeIndicator` string |Количество дней с момента последних изменений в учётной записи, за исключением изменения или сброса пароля. Возможные значения: - `01` — изменения в день проведения платежа, - `02` — менее 30 дней, - `03` — от 30 до 60 дней, - `04` — более 60 дней | |`passChangeDate` string |Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`| |`passChangeIndicator` string |Количество дней с момента последнего изменения или сброса пароля. Возможные значения: - `01` — пароль не был изменён или сброшен, - `02` — пароль был изменён или сброшен в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`paymentAge` string |Дата добавления платёжных данных карты в формате `ДД-ММ-ГГГГ`| |`paymentAgeIndicator` string |Количество дней с момента сохранения данных платёжной карты, используемой для проведения платежа, в учётной записи пользователя. Возможные значения: - `01` — платёж проводится без аутентификации в учётной записи, - `02` — данные карты сохранены в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`provisionAttempts` integer |Количество попыток сохранения новых платёжных данных карты за последние 24 часа, не более трёх символов \(`999`\)| |`purchaseNumber` integer |Количество покупок, совершённых через эту учётную запись за последние 6 месяцев, не более четырёх символов \(`9999`\)| |`suspiciousActivity` string |Индикатор подозрительной активности. Возможные значения: - `01` — без подозрений, - `02` — с подозрительной активностью | |`threeDSecureShippingInfo` — объект класса `ECMPThreeDSecureShippingInfo`, содержащий информацию о доставке| |`address` string |Адрес доставки, не более ста пятидесяти символов| |`addressUsage` string |Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате `ДД-ММ-ГГГГ`| |`addressUsageIndicator` string |Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения: - `01` — указанный адрес используется впервые, - `02` — менее 30 дней назад, - `03` — от 30 до 60 дней назад, - `04` — более 60 дней назад | |`city` string |Название города доставки, не более пятидесяти символов| |`country` string |Код страны доставки в формате ISO 3166-1 alpha-2 \(например, [GB](references/ru/countries/GB.md)\)| |`deliveryEmail` string |Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов| |`deliveryTime` string |Срок доставки. Возможные значения: - `01` — электронная доставка в день покупки, - `02` — доставка в день покупки, - `03` — доставка на следующий день после покупки, - `04` — доставка более чем через один день после покупки | |`nameIndicator` string |Индикатор совпадения имени пользователя с именем получателя. Возможные значения: - `01` — имена совпадают, - `02` — имена не совпадают | |`postal` string |Почтовый индекс доставки, не более шестнадцати символов| |`regionCode` string |Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма. При указании значения этого параметра также необходимо указать значение параметра `country` в объекте `threeDSecureShippingInfo`| |`type` string |Способ доставки, выбранный пользователем. Возможные значения: - `01` — доставка на платёжный адрес держателя карты; - `02` — доставка на другой подтверждённый адрес; - `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым; - `04` — доставка в магазин; - `05` — электронная доставка; - `06` — без доставки \(например, в случае покупки билетов на мероприятие\); - `07` — другое | |`threeDSecureMpiResultInfo` — объект класса `ThreeDSecureMpiResultInfo`, содержащий информацию о предыдущей аутентификации пользователя.| |`acsOperationId` string |Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов.| |`authenticationFlow` string |Указатель варианта предыдущего прохождения аутентификации пользователем. Возможные значения: - `01` — frictionless flow, - `02` — challenge flow | |`authenticationTimestamp` string |Дата и время предыдущей успешной аутентификации пользователя.| --- # SDK UI & Core для iOS {#ru_sdk_ui_and_core_ios} статья о порядке применения SDK UI & Core для интеграции платёжной формы с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе iOS **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_ui_and_core_ios_overview} ### Введение {#section_xsr_sxj_lvb .section} Mobile SDK UI & Core для iOS — это набор средств разработки с открытым программным кодом, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, работающих на платформе iOS. SDK UI & Core для iOS позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой для отправки и приёма необходимой информации при проведении платежей, а также обеспечивает интерфейсное взаимодействие с пользователями. Кроме того, за счёт открытого программного кода при использовании SDK UI & Core для iOS можно гибко настраивать пользовательский интерфейс, адаптируя его под специфику приложения. SDK UI & Core для iOS можно встраивать в мобильные приложения, работающие на платформе iOS версии 15.6 и выше. Библиотеки SDK UI & Core для iOS и примеры кода расположены на портале GitHub. Для работы с ними можно использовать следующие ссылки: - Список версий SDK UI & Core для iOS: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/releases) - Примеры кода: [https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples](https://github.com/ITECOMMPAY/mobile-sdk-ios-ui/tree/master/IntegrationSamples) В этой статье представлена информация о работе с SDK UI & Core для iOS с примерами кода на языках Swift и Objective-C. ### Возможности {#section_avp_5xj_lvb .section} При работе с SDK UI & Core для iOS доступны следующие возможности: - Проведение платежей различных типовс прямым использованием платёжных карт и с применением метода Apple Pay, а также других платёжных методов, доступных в рамках проекта мерчанта. К поддерживаемым типам платежей относятся: - одностадийные разовые оплаты; - двухстадийные разовые оплаты \(с блокировкой средств через SDK и последующим списанием через Gate или Dashboard\); - повторяемые оплаты \(с регистрацией через SDK и последующим управлением списаниями через Gate или Dashboard\). **Прим.:** При проведении платежей с использованием карт и метода Apple Pay задействуется платёжный интерфейс, описанный в этой статье, а при проведении платежей с использованием других платёжных методов — платёжная форма Payment Page. - Проверка действительности платёжных карт \(с проведением условных платежей на нулевые суммы\). - Контроль состояния платежей. - Поддержка различных вспомогательных процедур и дополнительных возможностей для повышения проходимости платежей, включая: - дополнение информации о платежах; - повторные попытки проведения платежей; - каскадное проведение платежей; - сбор данных о пользователях. - Поддержка различных дополнительных возможностей для улучшения пользовательского опыта, включая: - сохранение платёжных данных пользователей; - управление языком платёжного интерфейса; - отправку пользователям уведомлений с информацией о товарных позициях по проведённым платежам. - Возможности индивидуального оформления платёжного интерфейса, включая его стилизацию за счёт использования логотипа и настройки цветовой палитры, а также более глубокую адаптацию к специфике приложения за счёт работы с открытым программным кодом SDK. ### Схема работы {#section_dc3_lyj_lvb .section} В общем случае одностадийные оплаты с использованием SDK UI & Core для iOS проводятся в соответствии со следующей схемой. ![](images/sdk/ios/ru_sdk_ui_core_functional_ios.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK UI & Core для iOS этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта. 3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK UI & Core для iOS. 4. С помощью SDK UI & Core для iOS инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы выполняются подготовка платёжного интерфейса с учётом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса. 6. В мобильном приложении пользователю отображается форма оплаты. 7. Пользователь выбирает платёжный метод \(если он не был задан при открытии платёжной сессии\), указывает необходимую информацию и подтверждает готовность провести оплату. 8. От SDK UI & Core для iOS к платёжной платформе отправляется запрос на проведение оплаты. 9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: кпровайдерам и платёжным системам. 10. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 11. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 12. От платёжной платформы к SDK UI & Core для iOS направляется информация о результате оплаты. 13. Информация о результате отображается в пользовательском интерфейсе. ### Интерфейс {#section_erq_4zj_lvb .section} При проведении платежейс использованием платёжных карт и альтернативного метода Apple Pay пользователю отображается интерфейс, разработанный специалистами Ecommpay. Со стороны мерчанта можно настраивать цвет этого интерфейса и добавлять логотип. ![](images/sdk/ios/all_sdk_ui_core_ios_design_color.svg "Варианты индивидуального оформления") ![](images/sdk/ios/all_sdk_ui_core_ios_design_card_details.svg "Страница указания платёжных данных") ![](images/sdk/ios/all_sdk_ui_core_ios_design_result.png "Страница уведомления о результате платежа") ## Подготовка к использованию {#ru_sdk_ui_and_core_ios_setup} ### Порядок интеграции {#section_j3s_v2k_lvb .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK UI & Core для iOS со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK UI & Core для iOS и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Скачать и подключить библиотеки SDK UI & Core для iOS. 2. Обеспечить сбор данных, необходимых для вызова платёжной формы. Минимальный набор данных, который необходимо собрать для вызова платёжной формы, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK UI & Core для iOS, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием доступных платёжных методов\) и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK UI & Core для iOS следует обращаться в службу технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Подключение библиотек в Swift {#section_ury_jjk_lvb .section} Для подключения библиотек к проекту мобильного приложения необходимо: 1. Перенести файл `ecommpaySDK.xcframework` в папку проекта мобильного приложения. 2. Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо: 1. Открыть цель \(target\) проекта. 2. Перейти в **General** \> **Embedded Binaries**. 3. Щёлкнуть **+**. 4. Щёлкнуть **Add Other**. 5. Выбрать файл `ecommpaySDK.xcframework`. 6. Щёлкнуть **Add**. 3. Добавить ключ **NSCameraUsageDescription** со значением `permission is needed in order to scan card` в файл **Info.plist**, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование. 4. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ **NSLocationWhenInUseUsageDescription** со значением `fraud prevention` в файл **Info.plist**. Ecommpay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым. Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить. 5. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ **Privacy - Photo Library Usage Description** и ключ **Privacy - Photo Library Additions Usage Description** с необходимыми значениями в файл **Info.plist**. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных. ### Подключение библиотек в Objective-C {#section_tlm_mjk_lvb .section} Для подключения библиотек к проекту мобильного приложения необходимо: 1. Перенести файл `ecommpaySDK.xcframework` в папку проекта мобильного приложения. 2. Добавить библиотеку к проекту. В Xcode версии 12 для этого необходимо: 1. Открыть цель \(target\) проекта. 2. Перейти в **General** \> **Embedded Binaries**. 3. Щёлкнуть **+**. 4. Щёлкнуть **Add Other**. 5. Выбрать файл `ecommpaySDK.xcframework`. 6. Щёлкнуть **Add**. 7. Выбрать раздел **Build Settings**. 8. Установить переключатель **Always embed swift embedded libraries** в положение **Yes**. 3. Добавить ключ **NSCameraUsageDescription** со значением `permission is needed in order to scan card` в файл **Info.plist**, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование. 4. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ **NSLocationWhenInUseUsageDescription** со значением `fraud prevention` в файл **Info.plist**. Ecommpay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым. Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить. 5. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ **Privacy - Photo Library Usage Description** и ключ **Privacy - Photo Library Additions Usage Description** с необходимыми значениями в файл **Info.plist**. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных. ### Подключение библиотек через CocoaPods {#section_ymc_ffk_lvb .section} Для приложений, работающих на платформе iOS 15.6 и выше поддерживается подключение библиотек SDK UI & Core для iOS через CocoaPods. Чтобы подключить библиотеки, необходимо выполнить следующее: 1. Открыть файл `Podfile` и добавить в него следующие строки: ``` target 'App' do # Pods for App pod 'EcommpaySDK_UI' end ``` 2. Добавить ключ **NSCameraUsageDescription** со значением `permission is needed in order to scan card` в файл **Info.plist**, чтобы предоставить пользователям возможность автоматического заполнения данных карты через её сканирование. 3. Если в мобильном приложении не используется запрос местоположения пользователя, добавить ключ **NSLocationWhenInUseUsageDescription** со значением `fraud prevention` в файл **Info.plist**. Ecommpay не запрашивает местоположение пользователя, если этого не делает мобильное приложение, но в соответствии с требованиями App Store значение ключа не должно быть пустым. Если мобильное приложение уже запрашивает информацию о местоположении пользователя, этот шаг можно пропустить. 4. Если мобильному приложению не предоставлено разрешение на сохранение данных на устройстве, необходимо добавить ключ **Privacy - Photo Library Usage Description** и ключ **Privacy - Photo Library Additions Usage Description** с необходимыми значениями в файл **Info.plist**. Указанные для данных ключей значения отображаются для пользователя при запросе разрешения на сохранение данных. ### Обеспечение работы с подписью {#section_anr_33k_lvb .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта. Порядок работы с подписью представлен в разделе [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_ui_and_core_ios_testing} При необходимости платёжную форму можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок — протестировать проведение оплат с определённым результатом. Для этого в запросе на открытие платёжной формы в объекте `PaymentOptions` можно передать следующие значения для параметра `mockModeType` \(значения указаны для языков Swift и Objective-C соответственно\): - `MockModeType.success` / `MockModeTypeSuccess` — если необходим результат «платёж проведён»; - `MockModeType.decline` / `MockModeTypeDecline` — если необходим результат «платёж отклонён». Если необходимо открыть платёжную форму в рабочем режиме, для параметра `mockModeType` следует передать значение `MockModeType.disabled` / `MockModeTypeDisabled`. Также проведение платежей можно протестировать через тестовую среду платёжной платформы Ecommpay. В этом случае необходимо подключиться к тестовой среде Ecommpay\(сделать это можно [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\) и использовать полученные идентификатор тестового проекта и соответствующий ему секретный ключ в значении обязательных параметров запроса на открытие платёжной формы. В исходных примерах кода, предоставленных на Github, заданы постоянные значения для этих параметров. ```language-c let secret = "your_secret" // секретный ключ для тестового проекта let project_id: Int32 = 10 // идентификатор тестового проекта ``` ```language-c #define SECRET @"your_secret" // секретный ключ для тестового проекта #define PROJECT_ID 10 // идентификатор тестового проекта ``` Чтобы перейти в рабочий режим, необходимо заменить тестовые значения \(идентификатор рабочего проекта и секретный ключ от него\) на рабочие. **Внимание:** Для тестирования проведения платежей с помощью SDK UI & Core для iOS с использованием Apple Pay не следует применять эмуляторы устройств. Для такого тестирования требуется соответствующее физическое устройство — при использовании эмулятора невозможно получить корректный токен от сервиса Apple Pay и, как следствие, провести платёж. Ошибки, полученные при использовании эмулятора, ожидаемы и не отображают фактическую ситуацию при проведении реальных платежей. ## Использование {#ru_sdk_ui_and_core_ios_use} ### Вызов платёжной формы {#ru_sdk_ui_and_core_ios_openingpf} SDK UI & Core для iOS поддерживает выполнение таких целевых действий как проведение одностадийных разовых оплат, блокировка средств пользователей в рамках проведения двухстадийных оплат, регистрация повторяемых оплат и проверка действительности платёжных карт. Для инициирования таких действий требуется определённый набор параметров: обязательный минимум передаётся в объекте `PaymentOptions`. Остальные параметры можно передать в этом же объекте, а также запросить их у пользователя или получить со стороны платёжной платформы. #### Вызов в Swift {#section_fgp_xsq_lvb .section} Для вызова платёжной формы необходимо выполнить следующие действия: 1. Импортировать библиотеку. ``` {#codeblock_ism_dwb_4cc .language-c} import ecommpaySDK ``` 2. Объявить библиотеку EcommpaySDK в любом месте приложения \(например, внутри метода `viewDidLoad`\). ``` {#codeblock_cfw_dwb_4cc .language-c} let ecommpaySDK = EcommpaySDK() ``` 3. Создать объект `PaymentOptions`. Этот объект должен содержать обязательные параметры для открытия платёжной формы: - `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay; - `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта; - `paymentCurrency` \(string\) — код валюты платежа в формате ISO-4217 alpha-3; - `paymentAmount` \(integer\) — сумма платежа в дробных единицах валюты; - `customerId` \(string\) — идентификатор пользователя в рамках проекта; Для оплат с прямым использованием платёжных карт такженеобходимо передавать параметр `additionalFields` с по крайней мере одним из следующих полей: `customer_email` или `customer_phone`. Чтобы задать целевое действие, необходимо указать тип операции `Sale`, `Auth` или `Verify` в параметре `action`. Дополнительно могут использоваться и другие параметры, представленные в разделе [Параметры вызова](ru_sdk_ui_and_core_ios.md). Пример объекта `PaymentOptions`, который содержит необязательные параметры \(описание платежа и страну пользователя\): ```language-c let paymentOptions = PaymentOptions(projectID: 10, paymentID: "internal_payment_id_1", paymentAmount: 1999, paymentCurrency: "USD", paymentDescription: "T-shirt with dog print", customerID: "10", regionCode: "US") ``` 4. Получить строку для подписывания указанных параметров. ```language-c paymentOptions.paramsForSignature(); ``` 5. Передать сгенерированную строку в серверную часть приложения. 6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть. 7. Добавить подпись в объект `PaymentOptions`. ```language-c paymentOptions.signature = signature; ``` 8. Вызвать платёжную форму. ``` {#codeblock_sxq_gwb_4cc .language-c} ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in print("ecommpaySDK finished with status \(result.status.rawValue)") ... } ``` После вызова платёжной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платёжная форма, в других случаях платёжная форма не открывается, а метод вызова платёжной формы возвращает код ошибки. #### Вызов в Objective-C {#section_dxl_1tq_lvb .section} Для вызова платёжной формы необходимо выполнить следующие действия: 1. Импортировать библиотеку. ``` {#codeblock_eyk_hwb_4cc .language-c} #import ``` 2. Объявить библиотеку EcommpaySDK в любом месте приложения \(например, внутри метода `viewDidLoad`\). ``` {#codeblock_wzk_3wb_4cc .language-c} EcommpaySDK *self.EcommpaySDK = [[EcommpaySDK alloc] init]; ``` 3. Создать объект `PaymentOptions`. Этот объект должен содержать обязательные параметры для открытия платёжной формы: - `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay; - `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта; - `paymentCurrency` \(string\) — код валюты платежа в формате ISO-4217 alpha-3; - `paymentAmount` \(integer\) — сумма платежа в дробных единицах валюты; - `customerId` \(string\) — идентификатор пользователя в рамках проекта; Для оплат с прямым использованием платёжных карт такженеобходимо передавать параметр `additionalFields` с по крайней мере одним из следующих полей: `customer_email` или `customer_phone`. Чтобы задать целевое действие, необходимо указать тип операции `Sale`, `Auth` или `Verify` в параметре `action`. Дополнительно могут использоваться и другие параметры, представленные в разделе [Параметры вызова](ru_sdk_ui_and_core_ios.md). Пример объекта `PaymentOptions`, который содержит необязательные параметры \(описание платежа и страну пользователя\): ```language-c PaymentOptions *paymentOptions = [[PaymentOptions alloc] initWithProjectID:10 paymentID:@"internal_payment_id_1" paymentAmount:1999 paymentCurrency:@"USD" paymentDescription:@"T-shirt with dog print" customerID:@"10" regionCode:@"US"]; ``` 4. Получить строку для подписывания указанных параметров. ```language-c paymentOptions.paramsForSignature(); ``` 5. Передать сгенерированную строку в серверную часть приложения. 6. Сгенерировать подпись на стороне серверной части приложения и передать её в клиентскую часть. 7. Добавить подпись в объект `PaymentOptions`. ```language-c [paymentOptions setSignature:signature] ``` 8. Вызвать платёжную форму. ``` {#codeblock_qbv_jwb_4cc .language-c} [self.EcommpaySDK presentPaymentAt:self paymentOptions:paymentOptions completionHandler:^(PaymentResult *result) { NSLog(@"EcommpaySDK finished with status %ld", (long)result.status); ... }]; ``` После вызова платёжной формы библиотека выполняет проверку на ошибки. При отсутствии ошибок открывается платёжная форма, в других случаях платёжная форма не открывается, а метод вызова платёжной формы возвращает код ошибки. ### Проведение платежей {#ru_sdk_ui_and_core_ios_payments} По умолчанию в SDK UI & Core для iOS настроено проведение разовых одностадийных оплат \(с типом действия `Sale`\). Для проведения оплат такого типа можно использовать приведённые выше примеры и дополнительно ничего не настраивать. Вместе с тем при работе с SDK UI & Core для iOS можно проводить и двухстадийные оплаты \(с блокировкой средств через SDK и последующим списанием\). Для этого следует: 1. Вызвать платёжную форму, задав тип действия `Auth` в объекте `paymentOptions`: ```language-c paymentOptions.action = .Auth ``` ```language-c [paymentOptions setAction: ActionTypeAuth]; ``` 2. Когда потребуется, подтвердить списание средств через Dashboard \([подробнее](ru_dbl_payments.md)\) или через Gate \(с помощью запроса к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture)\). ### Проверка действительности платёжных карт {#ru_sdk_ui_and_core_ios_verify} Проверка действительности платёжного инструмента может использоваться, когда необходимо проверить действительность карты без списания средств \(например, перед выплатой на эту карту\) или сохранить данные карты для их дальнейшего использования. По сути это условный платёж со списанием нулевой суммы. Для такой проверки следует вызвать платёжую форму, задав тип действия `Verify` в объекте `paymentOptions`: ```language-c paymentOptions.action = .Verify ``` ```language-c [paymentOptions setAction: ActionTypeVerify]; ``` ### Получение информации о платеже {#ru_sdk_ui_and_core_ios_status} Для получения информации о результатах проведения платежей используются запросы со следующими данными: ```language-c ecommpaySDK.presentPayment(at: self, paymentOptions: paymentOptions) { result in print("ecommpaySDK finished with status \(result.status.rawValue)") if let error = result.error { // в случае ошибки print("Error code:\(error.code) with message: \(error.message)") } } ``` ```language-c [self.ecommpaySDK presentPaymentAt:self paymentOptions:paymentOptions completionHandler:^(PaymentResult *result) { NSLog(@"EcommpaySDK finished with status %ld", (long)result.status); if(result.error != NULL) { // в случае ошибки NSLog(@"Error code: %@ with message: %@", error.codeString, error.message); } }]; ``` Допустимые коды результатов проведения платежей, передаваемые в параметре `PaymentResult.status`: |Код результата|Значение|Описание| |--------------|--------|--------| |`0`|Success|Платёж проведён| |`100`|Decline|Проведение платежа отклонено| |`200`|Cancelled|Проведение платежа отменено пользователем| |`500`|Error|Возникла ошибка при проведении платежа| ### Проведение платежей с использованием Apple Pay {#ru_sdk_ui_and_core_ios_applepay} Чтобы обеспечить возможность проведения платежей с использованием метода Apple Pay, предварительно необходимо: 1. Зарегистрировать в Apple идентификатор мерчанта \(Merchant ID\), позволяющий принимать платежи с использованием метода Apple Pay. Этот идентификатор действует бессрочно и может использоваться для разных сайтов и приложений iOS. Информация о регистрации этого идентификатора представлена в документации Apple: [Create a merchant identifier](https://help.apple.com/developer-account/#/devb2e62b839?sub=dev103e030bb). 2. Выпустить сертификат обработки платежей \(Payment Processing Certificate\). Этот сертификат используется в связке с идентификатором мерчанта и позволяет обеспечивать безопасность платёжных данных при проведении платежей с использованием метода Apple Pay. Информация о выпуске этого сертификата представлена в документации Apple: [Create a payment processing certificate](https://help.apple.com/developer-account/#/devb2e62b839?sub=devf31990e3f). 3. Передать специалистам технической поддержки Ecommpay сертификат обработки платежей, используя при этом оговорённые методы защиты. 4. Включить поддержку Apple Pay для проекта мобильного приложения в используемой среде разработки. Информация об этой настройке для среды Xcode представлена в документации Apple: [Enable Apple Pay](https://help.apple.com/xcode/mac/9.3/#/deva43983eb7?sub=dev44ce8ef13). После этого можно проводить платежи с использованием Apple Pay. Все основные процедуры — вызов платёжной формы и приём результатов — выполняются при этом так же, как и при работе с другими методами, а при формировании запросов необходимо передавать следующие данные в объекте `applePayOptions`: ```language-c setupApplePayparams(paymentOptions: PaymentOptions) { let applePayOptions = PaymentOptions.ApplePayOptions(applePayMerchantID: "merchant.example.com", applePayDescription: "Shop", countryCode: "US") paymentOptions.applePayOptions = applePayOptions } ``` ```language-c setApplePaySettings:(PaymentOptions *)paymentOptions { PaymentOptionsForApplePay *applePayOptions = [[PaymentOptionsForApplePay alloc] initWithApplePayMerchantID:@"merchant.example.com" applePayDescription:@"Shop" countryCode:@"US"]; } ``` Все параметры, передаваемые в объекте `applePayOptions` являются обязательными и необходимы для корректного формирования платёжной сессии Apple Pay. ### Применение дополнительных возможностей {#ru_sdk_ui_and_core_ios_additional_capabilities} #### Дополнение информации о платеже {#section_tk2_ngl_lvb .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Информация о процедуре дополнения информации о платеже представлена [в отдельной статье](ru_pp_clarification.md). Итоговый набор запрашиваемых данных зависит от требованийконкретного провайдера или платёжной системы и может варьироваться. Список данных, актуальных для конкретного платежа, отображается пользователю в платёжном интерфейсе. Пользователь указывает запрашиваемые данные, подтверждает проведение платежа и получает информацию о результате. #### Каскадное проведение платежей {#section_ydw_jgl_lvb .section} В случаях, когда по каким-либо причинам попытка проведения платежа не завершилась успешно, можно использовать каскадное проведение платежей \([подробнее](ru_pp_cascading.md)\), которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеровбез изменения платёжного метода. Подключение этой возможности необходимо согласовывать со специалистами Ecommpay. Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK UI & Core для iOS поступает уведомление, в котором содержится признак `cascading_with_redirect = true`. Пользователю при этом отображается страница с ошибкой и кнопкой для выполнения очередной попытки. Если в рамках дополнительной попытки не требуется аутентификация 3‑D Secure, то попытка выполняется без взаимодействия с пользователем, иначе — отображается страница с повторной аутентификацией. #### Сбор данных о пользователях {#section_mwh_4gl_lvb .section} В некоторых случаях вместе с обязательными данными актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Подробная информация об использовании возможности сбора дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). #### Управление языком платёжного интерфейса {#section_gsf_r5c_xyb .section} По умолчанию при работе с SDK UI & Core в платёжном интерфейсе используется язык устройства пользователя, если он поддерживается для используемого проекта, или язык, определённый по умолчанию для остальных случаев \(в общем случае — английский\). Вместе с тем, если это актуально, можно задавать определённые языки для конкретных сеансов. Для этого в каждом таком случае при вызове платёжной формы необходимо передавать соответствующий код языка в параметре `languageCode` \([подробнее](ru_sdk_ui_and_core_ios.md)\). **Внимание:** При указании языка, не поддерживаемого для используемого проекта, платёжная форма не открывается и пользователю отображается информация об ошибке. К числу поддерживаемых в платформе для интерфейса SDK и доступных для оперативного подключения в проектах относятся следующие языки. |Язык|Код| |----|---| |Английский|`en`| |Испанский|`es`| |Итальянский|`it`| |Латышский|`lv`| |Литовский|`lt`| |Немецкий|`de`| |Португальский|`pt`| |Русский|`ru`| |Украинский|`uk`| |Французский|`fr`| |Эстонский|`et`| #### Сохранение платёжных данных {#section_zxg_tdl_lvb .section} При работе с SDK UI & Core для iOS поддерживается сохранение платёжных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Возможность сохранения платёжных данных подключается для каждого проекта отдельно; со стороны мерчанта необходимо сообщить специалистам технической поддержки подходящий вариант сохранения: *всегда* или *по выбору пользователя*. Информация об этой возможности представлена в отдельной статье \([подробнее](ru_PP_saved_data.md)\). В результате сохранения платёжных данных для каждого платёжного инструмента формируется идентификатор, ассоциированный с идентификатором конкретного пользователя \(`customerId`\). Для отображения пользователю сохранённых данных его платёжных инструментов в объекте `PaymentOptions` необходимо передавать параметр `hideSavedWallets` со значением `false`. ## Параметры вызова {#ru_sdk_ui_and_core_ios_parameters} При проведении оплат с прямым использованием платёжных карт в объекте `PaymentOptions` необходимо передавать параметр `additionalFields` с по крайней мере одним из следующих полей. |Параметр|Описание| |:-------|:-------| |`customer_email` list |Адрес электронной почты пользователя. Пример: `AdditionalField(type: .customer_email, value: "Customer email")` | |`customer_phone` list |Номер телефона пользователя. Пример: `AdditionalField(type: .customer_phone, value: "Customer phone")` | Дополнительно при проведении таких оплат в параметре `additionalFields` рекомендуется передавать следующие сведения о платёжном адресе пользователя. **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование таких параметров может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. |Параметр|Описание| |:-------|:-------| |`billing_country` string |Код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\). Пример: `AdditionalField(type: .customer_billing_country, value: "SE")` | |`billing_city` string |Город платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_city, value: "Stockholm")` | |`billing_postal` string |Индекс платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_postal, value: "10691")` | |`billing_address` string |Название улицы платёжного адреса пользователя. Пример: `AdditionalField(type: .customer_billing_address, value: "Albanovaegen 28")` | Для работы с SDK UI & Core для iOS в объекте `PaymentOptions` можно использовать следующие дополнительные параметры. |Параметр|Описание| |:-------|:-------| |`paymentDescription` string |Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase` | |`receiptData` string |Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg` | |`hideSavedWallets` boolean |Параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов. Возможные значения: - `true` — не отображать сохранённые данные. - `false` — отображать сохранённые данные. | |`forcePaymentMethod` string |Код предварительно выбранного платёжного метода в соответствии [с таблицей](ru_pm_codes.md). Пример: `card` | |`threeDSecureInfo` object |Объект, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2| |`languageCode` string |Код языка отображения платёжного интерфейса в формате ISO 639-1 alpha-2. Должен соответствовать одному из языков, поддерживаемых для используемого проекта. Пример: `IT` | |`regionCode ` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `SE` | |`applePayMerchantID` string |Идентификатор мерчанта в сервисе Apple Pay.| |`applePayDescription` string |Сведения о мерчанте в сервисе Apple Pay.| |`countryCode` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Передаётся при проведении платежей с использованием Apple Pay. Пример: `SE` | |`logoImage` object |Файл с логотипом мерчанта в формате PNG или SVG.| |`brandColor` object |Цвет платёжного интерфейса, передаётся в виде объекта `UIColor`. Пример: `UIColor.green` | |`additionalFields` list |Дополнительные поля с информацией о пользователе. Содержит список параметров и может включать их значения. Пример: `AdditionalField(type: .customer_first_name, value: "Sonya")` | Параметры для работы с повторяемыми оплатами необходимо передавать в объекте `recurrentInfo`, который входит в объект `PaymentOptions`. |Параметр|Описание| |:-------|:-------| |`type` string |Категория регистрируемой повторяемой оплаты. Возможные значения: - `.OneClick` — экспресс-оплата - `.Autopayment` — автооплата - `.Regular` — регулярная оплата | |`period` string |Указатель базового периода списаний \(для регулярной оплаты\). Возможные значения: - `.Day` — ежедневно - `.Week` — еженедельно - `.Month` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\) - `.Quarter` — ежеквартально - `.Year` — ежегодно | |`expiryDay` string |Номер календарного дня, в который должна быть завершена повторяемая оплата\(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\)| |`expiryMonth` string |Порядковый номер месяца, в котором должна быть завершена повторяемая оплата\(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\)| |`expiryYear` integer |Порядковый номер года, в котором должна быть завершена повторяемая оплата\(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\)| |`scheduledPaymentID` string |Идентификатор, который необходимо присвоить повторяемой оплате \(для автоматического инициирования списаний\). Параметр следует передавать вместе с параметром `startDate` | |`startDate` string |Дата первого списания\(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`| |`time` string |Время выполнения последующих списаний\(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`| |`schedule` object — расписание проведения повторяемых оплат \(можно задать со стороны мерчанта\). Следует указать параметры `amount` и `date` | |`amount` integer |Фиксированная сумма последующих списаний в дробных единицах валюты| |`date` string |Дата списания в формате `ДД-ММ-ГГГГ`| **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. В объекте `threeDSecureInfo` можно использовать следующие дополнительные объекты и параметры. Их использование позволит повысить вероятность выбора варианта аутентификации 3‑D Secure без дополнительных действий со стороны пользователя \(frictionless flow\). |Параметр|Описание| |:-------|:-------| |`threeDSecureInfo` — объект класса `ThreeDSecureInfo`, включающий в себя дополнительные объекты и параметры, которые используются в процессе аутентификации 3‑D Secure 2| |`threeDSecurePaymentInfo` — объект класса `ThreeDSecurePaymentInfo`, содержащий информацию о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации| |`challengeIndicator` string |Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения: - `01` — без предпочтений, - `02` — предпочтительно не выполнять, - `03` — предпочтительно выполнять, - `04` — обязательно выполнять | |`challengeWindow` string |Размер окна для открытия страницы аутентификации. Возможные значения: - `01` — 250 x 400 пикселей, - `02` — 390 x 400 пикселей, - `03` — 500 x 600 пикселей, - `04` — 600 x 400 пикселей, - `05` — полноэкранный режим | |`preorderDate` string |Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`| |`preorderPurchase` string |Индикатор предварительного заказа. Возможные значения: - `01` — не является предварительным заказом, - `02` — является предварительным заказом | |`reorder` string |Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения: - `01` — первичная покупка, - `02` — повторная покупка | |`threeDSecureGiftCardInfo` — объект класса `ThreeDSecureGiftCardInfo`, содержащий информацию об оплате предоплаченными или подарочными картами| |`amount` integer |Общая сумма оплаты предоплаченными или подарочными картами в дробных единицах валюты| |`currency` string |Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 \(например, [GBP](references/ru/currencies/GBP.md)\)| |`count` integer |Количество предоплаченных или подарочных карт, использованных для оплаты| |`threeDSecureCustomerInfo` — объект класса `ThreeDSecureCustomerInfo`, содержащий информацию о пользователе| |`addressMatch` string |Указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте `threeDSecureShippingInfo`. Возможные значения: - `Y` — адреса совпадают, - `N` — адреса не совпадают | |`billingRegionCode` string |Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма| |`homePhone` string |Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх \(например, `44991234567`\)| |`workPhone` string |Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх \(например, `44997654321`\)| |`threeDSecureAccountInfo` — объект класса `ThreeDSecureAccountInfo`, содержащий информацию об учётной записи пользователя на стороне мерчанта| |`additional` string |Дополнительная информация об учётной записи пользователя, например её идентификатор; в произвольном формате с использованием до шестидесяти четырёх символов| |`activityDay` integer |Количество попыток проведения оплаты за последние 24 часа, не более трёх символов \(`999`\)| |`activityYear` integer |Количество попыток проведения оплаты за последние 365 дней, не более трёх символов \(`999`\)| |`ageIndicator` string |Количество дней с момента создания учётной записи пользователя. Возможные значения: - `01` — платёж проводится без аутентификации в учётной записи, - `02` — учётная запись создана в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`authData` string |Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов| |`authMethod` string |Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения: - `01` — доступ без аутентификации; - `02` — аутентификация с использованием данных, сохранённых на стороне мерчанта; - `03` — аутентификация с использованием Federated ID \(например, Google Account или Facebook\); - `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\) | |`authTime` string |Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`| |`date` string |Дата создания учётной записи в формате `ДД-ММ-ГГГГ`| |`changeDate` string |Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`| |`changeIndicator` string |Количество дней с момента последних изменений в учётной записи, за исключением изменения или сброса пароля. Возможные значения: - `01` — изменения в день проведения платежа, - `02` — менее 30 дней, - `03` — от 30 до 60 дней, - `04` — более 60 дней | |`passChangeDate` string |Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`| |`passChangeIndicator` string |Количество дней с момента последнего изменения или сброса пароля. Возможные значения: - `01` — пароль не был изменён или сброшен, - `02` — пароль был изменён или сброшен в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`paymentAge` string |Дата добавления платёжных данных карты в формате `ДД-ММ-ГГГГ`| |`paymentAgeIndicator` string |Количество дней с момента сохранения данных платёжной карты, используемой для проведения платежа, в учётной записи пользователя. Возможные значения: - `01` — платёж проводится без аутентификации в учётной записи, - `02` — данные карты сохранены в день проведения платежа, - `03` — менее 30 дней, - `04` — от 30 до 60 дней, - `05` — более 60 дней | |`provisionAttempts` integer |Количество попыток сохранения новых платёжных данных карты за последние 24 часа, не более трёх символов \(`999`\)| |`purchaseNumber` integer |Количество покупок, совершённых через эту учётную запись за последние 6 месяцев, не более четырёх символов \(`9999`\)| |`suspiciousActivity` string |Индикатор подозрительной активности. Возможные значения: - `01` — без подозрений, - `02` — с подозрительной активностью | |`threeDSecureShippingInfo` — объект класса `ThreeDSecureShippingInfo`, содержащий информацию о доставке| |`address` string |Адрес доставки, не более ста пятидесяти символов| |`addressUsage` string |Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате `ДД-ММ-ГГГГ`| |`addressUsageIndicator` string |Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения: - `01` — указанный адрес используется впервые, - `02` — менее 30 дней назад, - `03` — от 30 до 60 дней назад, - `04` — более 60 дней назад | |`city` string |Название города доставки, не более пятидесяти символов| |`country` string |Код страны доставки в формате ISO 3166-1 alpha-2 \(например, [GB](references/ru/countries/GB.md)\)| |`deliveryEmail` string |Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов| |`deliveryTime` string |Срок доставки. Возможные значения: - `01` — электронная доставка в день покупки, - `02` — доставка в день покупки, - `03` — доставка на следующий день после покупки, - `04` — доставка более чем через один день после покупки | |`nameIndicator` string |Индикатор совпадения имени пользователя с именем получателя. Возможные значения: - `01` — имена совпадают, - `02` — имена не совпадают | |`postal` string |Почтовый индекс доставки, не более шестнадцати символов| |`regionCode` string |Код штата, провинции или региона страны в формате ISO 3166-2, например `AB` для Стокгольма. При указании значения этого параметра также необходимо указать значение параметра `country` в объекте `threeDSecureShippingInfo`| |`type` string |Способ доставки, выбранный пользователем. Возможные значения: - `01` — доставка на платёжный адрес держателя карты; - `02` — доставка на другой подтверждённый адрес; - `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым; - `04` — доставка в магазин; - `05` — электронная доставка; - `06` — без доставки \(например, в случае покупки билетов на мероприятие\); - `07` — другое | |`threeDSecureMpiResultInfo` — объект класса `ThreeDSecureMpiResultInfo`, содержащий информацию о предыдущей аутентификации пользователя.| |`acsOperationId` string |Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов.| |`authenticationFlow` string |Указатель варианта предыдущего прохождения аутентификации пользователем. Возможные значения: - `01` — frictionless flow, - `02` — challenge flow | |`authenticationTimestamp` string |Дата и время предыдущей успешной аутентификации пользователя.| --- # SDK Flutter для Android и iOS {#ru_sdk_flutter} статья о порядке применения SDK Flutter для интеграции платёжной формы в мобильные приложения на платформах Android и iOS **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_flutter_overview} ### Введение {#section_gtz_fqk_rbc .section} Mobile SDK Flutter для Android и iOS\(далее по тексту SDK Flutter\) — это набор средств разработки с открытым программным кодом, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, разработанных с использованием „фреймворка“ Flutterдля работы на платформах Android и iOS. SDK Flutterреализован как „плагин“ в терминологии этого „фреймворка“ и позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой Ecommpayдля отправки и приёма необходимой информации при проведении платежей, а такжеобеспечивает интерфейсное взаимодействие с пользователем. SDK Flutter можно встраивать в мобильные приложения, разработанные с использованием „фреймворка“ Flutter \(версии 3.3.0 и выше\) и работающие на платформе Android \(версии 5.0 и выше\) или iOS \(версии 15.6 и выше\). Библиотеки SDK Flutter и примеры кода для работы с ним расположенына порталах GitHub и pub.dev. - [https://github.com/ITECOMMPAY/msdk-flutter-plugin](https://github.com/ITECOMMPAY/msdk-flutter-plugin) - [https://pub.dev/packages/ecommpay\_flutter\_plugin](https://pub.dev/packages/ecommpay_flutter_plugin) ### Возможности {#section_a5h_gqk_rbc .section} При работе с SDK Flutter доступны следующие возможности: - Проведение платежей различных типов с прямым использованием платёжных карти с применением методов Google Pay и Apple Pay\(в зависимости от используемой платформы\), а также других платёжных методов, доступных в рамках проекта мерчанта. К поддерживаемым типам платежей относятся: - одностадийные разовые оплаты; - двухстадийные разовые оплаты\(с блокировкой средств через SDK и последующим списанием через Gate или Dashboard\); - повторяемые оплаты\(с регистрацией через SDK и последующим управлением списаниями через Gate или Dashboard\). **Прим.:** При проведении платежей с использованием карт и методов Google Pay и Apple Pay задействуется платёжный интерфейс, описанный в этой статье, а при проведении платежей с использованием других платёжных методов — платёжная форма Payment Page. - Проверка действительности платёжных карт\(с проведением условных платежей на нулевые суммы\). - Контроль состояния платежей. - Поддержка различных вспомогательных процедур и дополнительных возможностей для повышения проходимости платежей, включая: - дополнение информации о платежах; - повторные попытки проведения платежей; - сбор данных о пользователях. - Поддержка различных дополнительных возможностей для улучшения пользовательского опыта, включая: - сохранение платёжных данных пользователей; - управление языком платёжного интерфейса; - отправку пользователям уведомлений с информацией о товарных позициях по проведённым платежам. - Возможности индивидуального оформления платёжного интерфейса, включая его стилизацию за счёт настройки цветовой палитры, а также более глубокую адаптацию к специфике приложения за счёт работы с открытым программным кодом SDK. ### Схема работы {#section_bvm_gqk_rbc .section} В общем случае одностадийные оплаты с использованием SDK Flutter проводятся в соответствии со следующей схемой. ![](images/sdk/flutter/ru_sdk_flutter_functional.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложенияс помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK Flutter этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервисамерчанта. 3. В серверной части веб-сервисамерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK Flutter. 4. С помощью SDK Flutter инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы выполняются подготовка платёжного интерфейсас учётом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса. 6. В мобильном приложении пользователю отображается форма оплаты. 7. Пользователь выбирает платёжный метод\(если он не был задан при открытии платёжной сессии\),указывает необходимую информацию и подтверждает готовность провести оплату. 8. От SDK Flutter к платёжной платформе отправляется запрос на проведение оплаты. 9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам. 10. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 11. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 12. От платёжной платформы к SDK Flutter направляется информация о результате оплаты. 13. Информация о результате отображается в пользовательском интерфейсе. ### Интерфейс {#section_swg_3qk_rbc .section} При проведении платежейс использованием платёжных карт и методов Google Pay и Apple Pay пользователю отображается интерфейс, разработанный специалистами Ecommpay. Со стороны мерчанта можно настраивать базовый цвет для основных элементов этого интерфейса. ![](images/sdk/android/all_sdk_ui_core_design_color.svg "Варианты индивидуального оформления") ![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Страница указания платёжных данных") ![](images/sdk/android/all_sdk_ui_core_design_result.png "Страница уведомления о результате платежа") ## Подготовка к использованию {#ru_sdk_flutter_setup} ### Порядок интеграции {#section_c53_kqk_rbc .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK Flutter со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK Flutter и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Подключить SDK Flutter. 2. Обеспечить сбор данных, необходимых для вызова платёжного интерфейса.Минимальный набор данных, который необходимо собрать для вызова платёжной интерфейса, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK Flutter, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием доступных платёжных методов\) и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK Flutter следует обращаться в службу технической поддержки Ecommpay\([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Установка {#section_rcm_lqk_rbc .section} Чтобы установить SDK Flutterс использованием инструментов этого „фреймворка“, необходимо выполнить следующее: 1. Добавить в файл `pubspec.yaml` используемого проекта указатель на плагин, выполнив следующую команду. ``` $ flutter pub add ecommpay\_flutter\_plugin ``` В результате этого в файле `pubspec.yaml` должна появиться строка с названием добавленного плагина и номером его версии. ``` dependencies: ecommpay\_flutter\_plugin: ^1.0.4 ``` 2. Открыть файл `lib/main.dart` и добавить в него команды импорта функциональных возможностей. ``` import 'package:ecommpay\_flutter\_plugin/ecmpplugin.dart'; import 'package:ecommpay\_flutter\_plugin/ecmpplugin_method_channel.dart'; import 'package:ecommpay\_flutter\_plugin/ecmpplugin_platform_interface.dart'; import 'package:ecommpay\_flutter\_plugin/ecmp_additional_field.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_additional_field.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_info.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_info.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_options.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment_options.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_plugin_result.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_plugin_result.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_recipient_info.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_recipient_info.g.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_recurrent_data.dart'; import 'package:ecommpay\_flutter\_plugin/models/ecmp_recurrent_data.g.dart'; ``` Также могут использоваться другие способы установки, в соответствии с документацией Flutter \([подробнее](https://docs.flutter.dev/packages-and-plugins/using-packages)\). ### Обеспечение работы с подписью {#section_flm_mqk_rbc .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта.Порядок работы с подписью представлен в статье [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_flutter_testing} При необходимости платёжный интерфейс можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок — протестировать проведение оплат с определённым результатом. Для этого в запросе на открытие платёжного интерфейса в объекте `EcmpPaymentOptions` можно передать следующие значения для параметра `mockModeType`: - `EcmpMockModeType.success`— если необходим результат «платёж проведён»; - `EcmpMockModeType.decline`— если необходим результат «платёж отклонён». **Прим.:** При работе в тестовом режиме стоит учесть, что на платёжной форме отображаются ключи, а не их текстовые формулировки. Чтобы ознакомиться с ними до приёма платежей у пользователей, можно провести тестовые платежи в рабочем режиме либо обратиться в службу технической поддержки Ecommpay за примерами таких формулировок. Также проведение платежей можно протестировать через тестовую среду платёжной платформы Ecommpay. В этом случае необходимо подключиться к тестовой среде Ecommpay\(для этого можно использовать форму на [заявку](https://ecommpay.com/sign-up/) и полученные после заполнения этой формы идентификатор и ключ тестового проекта\). Чтобы перейти в рабочий режим, необходимо передавать в параметре `mockModeType` значение `EcmpMockModeType.disabled` и использовать идентификатор и ключ рабочего проекта. **Внимание:** Для тестирования проведения платежей с помощью SDK Flutter с использованием Apple Pay не следует применять эмуляторы устройств. Для такого тестирования требуется соответствующее физическое устройство — при использовании эмулятора невозможно получить корректный токен от сервиса Apple Pay и, как следствие, провести платёж. Ошибки, полученные при использовании эмулятора, ожидаемы и не отображают фактическую ситуацию при проведении реальных платежей. ## Использование {#ru_sdk_flutter_use} ### Вызов платёжного интерфейса {#ru_sdk_flutter_openingpf} SDK Flutter поддерживает выполнение таких целевых действий как проведение одностадийных разовых оплат, блокировка средств пользователей в рамках проведения двухстадийных оплат, регистрация повторяемых оплат и проверка действительности платёжных карт. Для инициирования таких действий требуется определённый набор параметров: обязательный минимум параметров передаётся в объекте `EcmpPaymentInfo`, в то время как остальные параметры могут быть переданы в объекте `EcmpPaymentOptions`. Для вызова платёжного интерфейса необходимо выполнить следующие действия: 1. Создать объект `EcmpPaymentInfo` со следующими обязательными параметрами: - `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay; - `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта; - `paymentCurrency` \(string\) — код валюты платежав формате ISO-4217 alpha-3; - `paymentAmount` \(integer\) — сумма платежав дробных единицах валюты; - `customerId` \(string\) — идентификатор пользователяв рамках проекта; - `signature` \(string\) — подпись запроса, составленная после указания всех целевых параметров. ```language-json final paymentInfo = EcmpPaymentInfo( projectId: 77655, paymentId: "payment_322", paymentAmount: 100, paymentCurrency: "USD", customerId: "customer007" ); ``` Дополнительно могут использоваться и другие параметры, представленные [в отдельной таблице](ru_sdk_flutter.md#section_ssf_vth_sbc). 2. Получить строку для подписывания указанных параметров. ``` final paramsForSignature = await ecmpPlugin.getParamsForSignature(paymentInfo); debugPrint(paramsForSignature); ``` 3. Передать полученную строку в серверную часть приложения. 4. Сформировать подпись на стороне серверной части приложения и передать её в клиентскую часть. 5. Добавить подпись в объект `EcmpPaymentInfo`. ```language-json paymentInfo.signature = "CALCULATED_SIGNATURE_FROM_BACKEND"; ``` 6. Создать объект `EcmpPaymentOptions`, который должен содержать обязательный параметр `actionType` \(string\) и, в случае проведения оплат с прямым использованием платёжных карт, список `additionalFields` с по крайней мере одним из полей: `email` или `phone`. В параметре `actionType` необходимо указать целевое действие: тип операции `sale`, `auth` или `verify`. Если это актуально, указать дополнительные сведения о платеже или перечень полей, которые необходимо отобразить пользователю для сбора таких сведений \(в списке `additionalFields`\), в том числе с предварительно заданными значениями. Например, для аутентификации 3‑D Secure рекомендуется указать сведения о платёжном адресе пользователя \(код страны, индекс, названия города и улицы\). Перечень сведений, которые можно указывать в объекте `EcmpPaymentOptions`, представлен [в отдельной таблице](ru_sdk_flutter.md#section_f3d_yth_sbc). **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование сведений о пользователе, в том числе о его платёжном адресе, может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. Следующий пример помимо обязательного для всех платежей параметра `actionType` содержит поле `email`, обязательное для оплат с прямым использованием платёжных карт, и ряд дополнительных параметров, передаваемых в списке `additionalFields` для сбора дополнительных сведений, в том числе для аутентификации 3‑D Secure. ```language-json final paymentOptions = EcmpPaymentOptions( actionType: EcmpActionType.sale, paymentInfo: paymentInfo, isDarkTheme: false, //if need use real service- set EcmpMockModeType.disabled mockModeType: EcmpMockModeType.success, //set display mode if need screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalScreen], //set additional fields if need additionalFields: [ EcmpAdditionalField(type: "email", value: "mail@mail.com"), EcmpAdditionalField(type: "first_name", value: "firstName"), ], //set recipient info if need recipientInfo: EcmpRecipientInfo(), //set recurrent info if need recurrentData: EcmpRecurrentData(), ); ``` 7. Создать объект `EcmpPlugin`. ```language-json final ecmpPlugin = EcmpPlugin(); ``` 8. Открыть платёжный интерфейс и получить информацию о результате. ```language-json final response = await ecmpPlugin.sdkRun(paymentOptions); ``` Итоговый код для вызова платёжного интерфейса может выглядеть следующим образом. ``` final ecmpPlugin = EcmpPlugin(); //create payment info final paymentInfo = EcmpPaymentInfo( projectId: 12312, paymentId: "paymentId", paymentAmount: 100, paymentCurrency: "USD", customerId: "customer007" ); //get params for signature final paramsForSignature = await ecmpPlugin.getParamsForSignature(paymentInfo); debugPrint(paramsForSignature); //calculate and set signature and set it into payment info paymentInfo.signature = "signature"; final paymentOptions = EcmpPaymentOptions( actionType: EcmpActionType.sale, paymentInfo: paymentInfo, isDarkTheme: false, //if need use real service- set EcmpMockModeType.disabled mockModeType: EcmpMockModeType.success, //set display mode if need screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalScreen], //set additional fields if need additionalFields: [ EcmpAdditionalField(type: "email", value: "mail@mail.com"), EcmpAdditionalField(type: "first_name", value: "firstName"), ], //set recipient info if need recipientInfo: EcmpRecipientInfo(), //set recurrent info if need recurrentData: EcmpRecurrentData(), ); try { final response = await ecmpPlugin.sdkRun(paymentOptions); debugPrint(response.toString()); } on PlatformException { debugPrint("PlatformException"); } ``` ### Проведение платежей {#ru_sdk_flutter_payments} При работе с SDK Flutter можно проводить одностадийные и двухстадийные\(с блокировкой средств через SDK и последующим списанием\) оплаты. Для проведения одностадийной оплаты при вызове платёжного интерфейса следует передавать значение `sale` в параметре `actionType`, а для проведения двухстадийной оплаты: 1. Вызвать платёжный интерфейс, указав значение `auth` параметра `actionType`в объекте `EcmpPaymentOptions`: ```language-java actionType: EcmpActionType.auth ``` 2. Когда потребуется, подтвердить списание средств через Dashboard \([подробнее](ru_dbl_payments.md)\) или через Gate\(с помощью запроса к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture)\). ### Проверка действительности платёжных карт {#ru_sdk_flutter_verify} Проверка действительности платёжного инструмента может использоваться, когда необходимо проверить действительность карты без списания средств\(например, перед выплатой на эту карту\) или сохранить данные карты для их дальнейшего использования. Для такой проверки при вызове платёжного интерфейса следует передавать значение `verify` параметра `actionType`в объекте `EcmpPaymentOptions`: ```language-java actionType: EcmpActionType.verify ``` ### Получение информации о платеже {#ru_sdk_flutter_status} Для получения уведомлений о результатах проведения платежей используются объекты класса `EcmpPluginResult`. ```language-json import 'package:ecommpay\_flutter\_plugin/models/ecmp_payment.dart'; import 'package:json_annotation/json_annotation.dart'; part 'ecmp_plugin_result.g.dart'; @JsonSerializable() class EcmpPluginResult { final int resultCode; final EcmpPayment? payment; final String? errorCode; final String? errorMessage; EcmpPluginResult( this.resultCode, this.payment, this.errorCode, this.errorMessage); Map toJson() => _$EcmpPluginResultToJson(this); factory EcmpPluginResult.fromJson(Map data) => _$EcmpPluginResultFromJson(data); } ``` ### Применение дополнительных возможностей {#ru_sdk_flutter_additional_capabilities} #### Дополнение информации о платеже {#section_uvv_srk_rbc .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа.Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список данных, актуальных для конкретного платежа, отображается пользователю в платёжном интерфейсе.Пользователь указывает запрашиваемые данные, подтверждает проведение платежа и получает информацию о результате. Более подробная информация об этой возможности представлена [в отдельной статье](ru_pp_clarification.md). #### Сбор данных о пользователях {#section_lnr_5rk_rbc .section} В некоторых случаях вместе с обязательными данными актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Более подробная информация о сборе дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). #### Управление языком платёжного интерфейса {#section_r5h_vrk_rbc .section} По умолчанию при работе с SDK Flutter в платёжном интерфейсе используется язык устройства пользователя, если он поддерживается для используемого проекта, или язык, определённый по умолчанию для остальных случаев\(в общем случае — английский\). Вместе с тем, если это актуально, можно задавать определённые языки для конкретных сеансов. Для этого в каждом таком случае при вызове платёжного интерфейса необходимо передавать соответствующий код языка в параметре `languageCode` объекта `EcmpPaymentInfo`. **Внимание:** При указании языка, не поддерживаемого для используемого проекта, платёжный интерфейс не открывается и пользователю отображается информация об ошибке. К числу поддерживаемых в платформе для интерфейса SDK и доступных для оперативного подключения в проектах относятся следующие языки. |Язык|Код| |----|---| |Английский|`en`| |Испанский|`es`| |Итальянский|`it`| |Латышский|`lv`| |Литовский|`lt`| |Немецкий|`de`| |Португальский|`pt`| |Русский|`ru`| |Украинский|`uk`| |Французский|`fr`| |Эстонский|`et`| #### Сохранение платёжных данных {#section_ytb_wrk_rbc .section} При работе с SDK Flutter поддерживается сохранение платёжных данных для последующего проведения платежей без повторного указания пользователями реквизитов. Такая возможность подключается в рамках проекта; при этом со стороны мерчанта необходимо сообщить специалистам технической поддержки подходящий вариант сохранения: *всегда* или *по выбору пользователя*. В результате сохранения платёжных данных для каждого платёжного инструмента формируется идентификатор, ассоциированный с идентификатором конкретного пользователя \(`customerId`\). Для отображения пользователю сохранённых данных его платёжных инструментов в объекте `EcmpPaymentInfo` необходимо передавать параметр `hideSavedWallets` со значением `false`. Более подробная информация об этой возможности представлена [в отдельной статье](ru_PP_saved_data.md). ## Дополнительные параметры вызова {#ru_sdk_flutter_parameters} ### Параметры объекта EcmpPaymentInfo {#section_ssf_vth_sbc .section} Для работы с SDK Flutter в объекте `EcmpPaymentInfo` можно использовать следующие дополнительные параметры. |Параметр|Описание| |:-------|:-------| |`paymentDescription` string |Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase` | |`receiptData` string |Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg` | |`token` string |Токен платёжных данных. Представляет собой строку длиной не более 255 символов. Пример: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c` | |`hideSavedWallets` boolean |Параметр, позволяющий управлять отображением информации о сохранённых ранее платёжных инструментах. Возможные значения: - `true` — не отображать - `false` — отображать | |`forcePaymentMethod` string |Код предварительно выбранного платёжного методав соответствии [с таблицей](ru_pm_codes.md). Пример: `card` | |`languageCode` string |Код языка отображения платёжного интерфейса в формате ISO 639-1 alpha-2.Должен соответствовать одному из языков, поддерживаемых для используемого проекта. Пример: `IT` | |`regionCode ` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `GB` | ### Параметры объекта EcmpPaymentOptions {#section_f3d_yth_sbc .section} В объекте `EcmpPaymentOptions` можно использовать следующие дополнительные параметры. |Параметр|Описание| | |--------|--------|--| |`googleMerchantId` string |Идентификатор мерчанта в сервисе Google Pay|1| |`googleMerchantName` string |Наименование мерчанта в сервисе Google Pay|2| |`googleIsTestEnvironment` boolean |Признак тестового платежа. Передаётся при проведении платежей с использованием метода Google Pay. Возможные значения: - `true` — тестовый платёж - `false` — платёж в рабочем режиме |3| |`applePayMerchantId` string |Идентификатор мерчанта в сервисе Apple Pay|4| |`applePayDescription` string |Сведения о мерчанте в сервисе Apple Pay|5| |`applePayCountryCode` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Передаётся при проведении платежей с использованием метода Apple Pay. Пример: `SE` |6| |`isDarkTheme` boolean |Признак использования тёмной темы платёжного интерфейса. Возможные значения: - `true` — использовать - `false` — не использовать |7| |`brandColor` string |Базовый цвет для основных элементов платёжного интерфейса в шестнадцатеричном формате HEX. Пример: `#800080` |8| |`screenDisplayModes` list |Указание на отсутствие необходимости отображать информацию о результате платежа в платёжном интерфейсе:- `hideSuccessFinalScreen` — не отображать информацию о проведении платежа - `hideDeclineFinalScreen` — не отображать информацию об отклонении платежа |10| |`additionalFields` list |Дополнительные поля с информацией о пользователе. Содержит список параметров и может включать их значения. Пример: ``` additionalFields: [ EcmpAdditionalField(type: "email", value: "mail@mail.com"), EcmpAdditionalField(type: "first_name", value: "firstName"), ], ``` |11| |`storedCardType` integer |Указатель типа повторяемой оплаты: - `3` — автооплата - `5` — регулярная оплата |12| |`recipientInfo` object |Объект, содержащий сведения о получателе платежа|13| |`pan` string |Номер карты. Пример: `5443011850290191` |13-113| |`cardHolder` string |Имя и фамилия \(в соответствии с указанными на карте\). Пример: `Sonya Kovalevsky` |13-213| |`walletId` string |Номер электронного кошелька. Пример: `WID301185029011891` |13-313| |`walletOwner` string |Имя и фамилия получателя. Пример: `Sonya Kovalevsky` |13-413| |`country` string |Код страны проживания в формате ISO 3166-1 alpha-2. Пример: `SE` |13-513| |`address` string |Адрес проживания. Пример: `Albanovaegen 28` |13-613| |`city` string |Город проживания. Пример: `Stockholm` |13-713| |`stateCode` string |Штат проживания. Пример: `MN` |13-813| |`recurrentData` object |Объект, содержащий сведения о регистрируемой повторяемой оплате|14| |`register` boolean |Указатель необходимости зарегистрировать повторяемую оплату. Возможные значения: - `true` — платёж с регистрацией повторяемой оплаты - `false` — платёж без регистрации повторяемой оплаты |14-114| |`type` string |Категория регистрируемой повторяемой оплаты. Возможные значения: - `C` — экспресс-оплата \(OneClick\) - `U` — автооплата - `R` — регулярная оплата |14-214| |`expiryDay` string |Номер календарного дня, в который должна быть завершена повторяемая оплата\(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\)|14-314| |`expiryMonth` string |Порядковый номер месяца, в котором должна быть завершена повторяемая оплата\(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\)|14-414| |`expiryYear` string |Порядковый номер года, в котором должна быть завершена повторяемая оплата\(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\)|14-514| |`period` string |Указатель базового периода списаний \(для регулярной оплаты\). Возможные значения: - `D` — ежедневно - `W` — еженедельно - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\) - `Q` — ежеквартально - `Y` — ежегодно |14-614| |`interval` integer |Множитель для кратного увеличения периода списаний\(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`; например чтобы списания выполнялись раз в три недели, в параметре `period` надо задать значение `W`, а в параметре `interval` значение `3`|14-714| |`time` string |Время выполнения последующих списаний\(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`|14-814| |`startDate` string |Дата первого списания\(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`|14-914| |`scheduledPaymentID` string |Идентификатор, который необходимо присвоить повторяемой оплате \(для автоматического инициирования списаний\). Параметр следует передавать вместе с параметром `startDate` |14-1014| |`amount` integer |Сумма последующих списаний в дробных единицах валюты|14-1114| **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. --- # SDK React Native для Android и iOS {#ru_sdk_react_native} статья о порядке применения SDK React Native для интеграции платёжной формы в мобильные приложения на платформах Android и iOS **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_react_native_overview} ### Введение {#section_gtz_fqk_rbc .section} Mobile SDK React Native для Android и iOS\(далее по тексту SDK React Native\) — это набор средств разработки с открытым программным кодом, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, разработанных с использованием „фреймворка“ React Nativeдля работы на платформах Android и iOS. SDK React Nativeреализован как „плагин“ в терминологии этого „фреймворка“ и позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой Ecommpayдля отправки и приёма необходимой информации при проведении платежей, а такжеобеспечивает интерфейсное взаимодействие с пользователем. SDK React Native можно встраивать в мобильные приложения, разработанные с использованием „фреймворка“ React Native \(версии 0.75.3 и выше\) и работающие на платформе Android \(версии 5.0 и выше\) или iOS \(версии 15.6 и выше\). Библиотеки SDK React Native и примеры кода для работы с ним расположенына порталах GitHub и NPM. - [https://github.com/ITECOMMPAY/msdk-react-native](https://github.com/ITECOMMPAY/msdk-react-native) - [https://www.npmjs.com/package/msdk-react-native](https://www.npmjs.com/package/msdk-react-native) ### Возможности {#section_a5h_gqk_rbc .section} При работе с SDK React Native доступны следующие возможности: - Проведение платежей различных типов с прямым использованием платёжных карти с применением методов Google Pay и Apple Pay\(в зависимости от используемой платформы\), а также других платёжных методов, доступных в рамках проекта мерчанта. К поддерживаемым типам платежей относятся: - одностадийные разовые оплаты; - двухстадийные разовые оплаты\(с блокировкой средств через SDK и последующим списанием через Gate или Dashboard\); - повторяемые оплаты\(с регистрацией через SDK и последующим управлением списаниями через Gate или Dashboard\). **Прим.:** При проведении платежей с использованием карт и методов Google Pay и Apple Pay задействуется платёжный интерфейс, описанный в этой статье, а при проведении платежей с использованием других платёжных методов — платёжная форма Payment Page. - Проверка действительности платёжных карт\(с проведением условных платежей на нулевые суммы\). - Контроль состояния платежей. - Поддержка различных вспомогательных процедур и дополнительных возможностей для повышения проходимости платежей, включая: - дополнение информации о платежах; - повторные попытки проведения платежей; - сбор данных о пользователях. - Поддержка различных дополнительных возможностей для улучшения пользовательского опыта, включая: - сохранение платёжных данных пользователей; - управление языком платёжного интерфейса; - отправку пользователям уведомлений с информацией о товарных позициях по проведённым платежам. - Возможности индивидуального оформления платёжного интерфейса, включая его стилизацию за счёт настройки цветовой палитры, а также более глубокую адаптацию к специфике приложения за счёт работы с открытым программным кодом SDK. ### Схема работы {#section_bvm_gqk_rbc .section} В общем случае одностадийные оплаты с использованием SDK React Native проводятся в соответствии со следующей схемой. ![](images/sdk/reactnative/ru_sdk_reactnative_functional.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложенияс помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK React Native этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервисамерчанта. 3. В серверной части веб-сервисамерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK React Native. 4. С помощью SDK React Native инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы выполняются подготовка платёжного интерфейсас учётом параметров вызова и передача к пользовательскому устройству данных для отображения этого интерфейса. 6. В мобильном приложении пользователю отображается форма оплаты. 7. Пользователь выбирает платёжный метод\(если он не был задан при открытии платёжной сессии\),указывает необходимую информацию и подтверждает готовность провести оплату. 8. От SDK React Native к платёжной платформе отправляется запрос на проведение оплаты. 9. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам. 10. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 11. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 12. От платёжной платформы к SDK React Native направляется информация о результате оплаты. 13. Информация о результате отображается в пользовательском интерфейсе. ### Интерфейс {#section_swg_3qk_rbc .section} При проведении платежейс использованием платёжных карт и методов Google Pay и Apple Pay пользователю отображается интерфейс, разработанный специалистами Ecommpay. Со стороны мерчанта можно настраивать базовый цвет для основных элементов этого интерфейса. ![](images/sdk/android/all_sdk_ui_core_design_color.svg "Варианты индивидуального оформления") ![](images/sdk/android/all_sdk_ui_core_design_card_details.svg "Страница указания платёжных данных") ![](images/sdk/android/all_sdk_ui_core_design_result.png "Страница уведомления о результате платежа") ## Подготовка к использованию {#ru_sdk_react_native_setup} ### Порядок интеграции {#section_c53_kqk_rbc .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK React Native со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK React Native и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Подключить SDK React Native. 2. Обеспечить сбор данных, необходимых для вызова платёжного интерфейса.Минимальный набор данных, который необходимо собрать для вызова платёжной интерфейса, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK React Native, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием доступных платёжных методов\) и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK React Native следует обращаться в службу технической поддержки Ecommpay\([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Установка {#section_rcm_lqk_rbc .section} Чтобы установить SDK React Nativeс использованием инструментов этого „фреймворка“, необходимо выполнить следующее: 1. В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить одну из команд. ``` npm install msdk-react-native // или yarn install msdk-react-native ``` 2. В исходный код веб-сервиса добавить команды импорта функциональных возможностей. ```language-javascript import {initializePayment, getParamsForSignature} from 'msdk-react-native'; ``` Также могут использоваться другие способы установки, в соответствии с документацией React Native \([подробнее](https://reactnative.dev/docs/integration-with-existing-apps)\). ### Обеспечение работы с подписью {#section_flm_mqk_rbc .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта.Порядок работы с подписью представлен в статье [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_react_native_testing} При необходимости платёжный интерфейс можно открыть в тестовом режиме, чтобы получить информацию об ошибках, допущенных при указании параметров платежа, а при отсутствии ошибок — протестировать проведение оплат с определённым результатом. Для этого в запросе на открытие платёжного интерфейса в объекте `EcmpPaymentOptions` можно передать следующие значения для параметра `mockModeType`: - `EcmpMockModeType.success`— если необходим результат «платёж проведён»; - `EcmpMockModeType.decline`— если необходим результат «платёж отклонён». Также проведение платежей можно протестировать через тестовую среду платёжной платформы Ecommpay. В этом случае необходимо подключиться к тестовой среде Ecommpay\(для этого можно использовать форму на [заявку](https://ecommpay.com/sign-up/) и полученные после заполнения этой формы идентификатор и ключ тестового проекта\). Чтобы перейти в рабочий режим, необходимо передавать в параметре `mockModeType` значение `EcmpMockModeType.disabled` и использовать идентификатор и ключ рабочего проекта. **Внимание:** Для тестирования проведения платежей с помощью SDK React Native с использованием Apple Pay не следует применять эмуляторы устройств. Для такого тестирования требуется соответствующее физическое устройство — при использовании эмулятора невозможно получить корректный токен от сервиса Apple Pay и, как следствие, провести платёж. Ошибки, полученные при использовании эмулятора, ожидаемы и не отображают фактическую ситуацию при проведении реальных платежей. ## Использование {#ru_sdk_react_native_use} ### Вызов платёжного интерфейса {#ru_sdk_react_native_openingpf} SDK React Native поддерживает выполнение таких целевых действий как проведение одностадийных разовых оплат, блокировка средств пользователей в рамках проведения двухстадийных оплат, регистрация повторяемых оплат и проверка действительности платёжных карт. Для инициирования таких действий требуется определённый набор параметров: обязательный минимум параметров передаётся в объекте `EcmpPaymentInfo`, в то время как остальные параметры могут быть переданы в объекте `EcmpPaymentOptions`. Для вызова платёжного интерфейса необходимо выполнить следующие действия: 1. Создать объект `EcmpPaymentInfo` со следующими обязательными параметрами: - `projectId` \(integer\) — идентификатор проекта, полученный от Ecommpay; - `paymentId` \(string\) — идентификатор платежа, уникальный в рамках проекта; - `paymentCurrency` \(string\) — код валюты платежав формате ISO-4217 alpha-3; - `paymentAmount` \(integer\) — сумма платежав дробных единицах валюты; - `customerId` \(string\) — идентификатор пользователяв рамках проекта; - `signature` \(string\) — подпись запроса, составленная после указания всех целевых параметров. ```language-javascript let paymentInfo: EcmpPaymentInfo = { projectID: 12123123, paymentID: "paymentId11", paymentCurrency: "USD", paymentAmount: 22200, customerId: "customer34" }; ``` Дополнительно могут использоваться и другие параметры, представленные [в отдельной таблице](ru_sdk_react_native.md#section_ssf_vth_sbc). 2. Получить строку для подписывания указанных параметров. ```language-javascript let paramsForSignature = getParamsForSignature(paymentInfo); console.log(paramsForSignature); ``` 3. Передать полученную строку в серверную часть приложения. 4. Сформировать подпись на стороне серверной части приложения и передать её в клиентскую часть. 5. Добавить подпись в объект `EcmpPaymentInfo`. ```language-javascript paymentInfo.signature = "CALCULATED_SIGNATURE_FROM_YOUR_BACKEND"; ``` 6. Создать объект `EcmpPaymentOptions`, который должен содержать обязательный параметр `actionType` \(string\) и, в случае проведения оплат с прямым использованием платёжных карт, список `additionalFields` с по крайней мере одним из полей: `email` или `phone`. В параметре `actionType` необходимо указать целевое действие: тип операции `sale`, `auth` или `verify` или `tokenize`. Если это актуально, указать дополнительные сведения о платеже или перечень полей, которые необходимо отобразить пользователю для сбора таких сведений \(в списке `additionalFields`\), в том числе с предварительно заданными значениями. Например, для аутентификации 3‑D Secure рекомендуется указать сведения о платёжном адресе пользователя \(код страны, индекс, названия города и улицы\). Перечень сведений, которые можно указывать в объекте `EcmpPaymentOptions`, представлен [в отдельной таблице](ru_sdk_react_native.md#section_f3d_yth_sbc). **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование сведений о пользователе, в том числе о его платёжном адресе, может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. Следующий пример помимо обязательного для всех платежей параметра `actionType` содержит поле `email`, обязательное для оплат с прямым использованием платёжных карт, и ряд дополнительных параметров, передаваемых в списке `additionalFields` для сбора дополнительных сведений, в том числе для аутентификации 3‑D Secure. ```language-javascript let paymentOptions: EcmpPaymentOptions = { actionType: EcmpActionType.sale, paymentInfo: paymentInfo, isDarkTheme: true, //для использования рабочего режима необходимо передавать в параметре mockModeType значение disabled mockModeType: EcmpMockModeType.success, //при необходимости задать отображение информации о результате платежа в платёжном интерфейсе screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalPage], //при необходимости задать другие дополнительные параметры additionalFields: [ { type: 'email', value: 'mail@mail.com' }] }; ``` 7. Открыть платёжный интерфейс и получить информацию о результате. ```language-javascript initializePayment(paymentOptions); ``` Итоговый код для вызова платёжного интерфейса может выглядеть следующим образом. ```language-javascript let paymentInfo: EcmpPaymentInfo = { projectID: 12123123, paymentID: "paymentId11", paymentCurrency: "USD", paymentAmount: 22200, customerId: "customer34" }; //получение строки для подписывания указанных параметров let paramsForSignature = getParamsForSignature(paymentInfo); console.log(paramsForSignature); //формирование подписи и её добавление в объект paymentInfo paymentInfo.signature = "signature"; let paymentOptions: EcmpPaymentOptions = { actionType: EcmpActionType.sale, paymentInfo: paymentInfo, isDarkTheme: true, //открытие платёжной формы в тестовом режиме mockModeType: EcmpMockModeType.success, //запрет на отображение информации об отклонении платежа screenDisplayModes: [EcmpScreenDisplayMode.hideDeclineFinalPage], //указание параметра из числа необязательных additionalFields: [ { type: 'email', value: 'mail@mail.com' }] }; initializePayment(paymentOptions); ``` ### Проведение платежей {#ru_sdk_react_native_payments} При работе с SDK React Native можно проводить одностадийные и двухстадийные\(с блокировкой средств через SDK и последующим списанием\) оплаты. Для проведения одностадийной оплаты при вызове платёжного интерфейса следует передавать значение `sale` в параметре `actionType`, а для проведения двухстадийной оплаты: 1. Вызвать платёжный интерфейс, указав значение `auth` параметра `actionType`в объекте `EcmpPaymentOptions`: ```language-javascript actionType: EcmpActionType.auth ``` 2. Когда потребуется, подтвердить списание средств через Dashboard \([подробнее](ru_dbl_payments.md)\) или через Gate\(с помощью запроса к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture)\). ### Проверка действительности платёжных карт {#ru_sdk_react_native_verify} Проверка действительности платёжного инструмента может использоваться, когда необходимо проверить действительность карты без списания средств\(например, перед выплатой на эту карту\) или сохранить данные карты для их дальнейшего использования. Для такой проверки при вызове платёжного интерфейса следует передавать значение `verify` параметра `actionType`в объекте `EcmpPaymentOptions`: ```language-javascript actionType: EcmpActionType.verify ``` ### Получение информации о платеже {#ru_sdk_react_native_status} При проведении платежей через платформу Ecommpay к веб-сервису мерчанта отправляются оповещения, например с информацией для перенаправления пользователей или с информацией о результатах выполнения операций. Структура этих оповещений и работа с ними описаны в статье [Работа с оповещениями](ru_platform_callbacks.md). ### Применение дополнительных возможностей {#ru_sdk_react_native_additional_capabilities} #### Дополнение информации о платеже {#section_uvv_srk_rbc .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа.Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список данных, актуальных для конкретного платежа, отображается пользователю в платёжном интерфейсе.Пользователь указывает запрашиваемые данные, подтверждает проведение платежа и получает информацию о результате. Более подробная информация об этой возможности представлена [в отдельной статье](ru_pp_clarification.md). #### Сбор данных о пользователях {#section_lnr_5rk_rbc .section} В некоторых случаях вместе с обязательными данными актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Более подробная информация о сборе дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). #### Управление языком платёжного интерфейса {#section_r5h_vrk_rbc .section} По умолчанию при работе с SDK React Native в платёжном интерфейсе используется язык устройства пользователя, если он поддерживается для используемого проекта, или язык, определённый по умолчанию для остальных случаев\(в общем случае — английский\). Вместе с тем, если это актуально, можно задавать определённые языки для конкретных сеансов. Для этого в каждом таком случае при вызове платёжного интерфейса необходимо передавать соответствующий код языка в параметре `languageCode` объекта `EcmpPaymentInfo`. **Внимание:** При указании языка, не поддерживаемого для используемого проекта, платёжный интерфейс не открывается и пользователю отображается информация об ошибке. К числу поддерживаемых в платформе для интерфейса SDK и доступных для оперативного подключения в проектах относятся следующие языки. |Язык|Код| |----|---| |Английский|`en`| |Испанский|`es`| |Итальянский|`it`| |Латышский|`lv`| |Литовский|`lt`| |Немецкий|`de`| |Португальский|`pt`| |Русский|`ru`| |Украинский|`uk`| |Французский|`fr`| |Эстонский|`et`| #### Сохранение платёжных данных {#section_ytb_wrk_rbc .section} При работе с SDK react Native поддерживается сохранение платёжных данных для последующего проведения платежей без повторного указания пользователями реквизитов. Такая возможность подключается в рамках проекта; при этом со стороны мерчанта необходимо сообщить специалистам технической поддержки подходящий вариант сохранения: *всегда* или *по выбору пользователя*. В результате сохранения платёжных данных для каждого платёжного инструмента формируется идентификатор, ассоциированный с идентификатором конкретного пользователя \(`customerId`\). Для отображения пользователю сохранённых данных его платёжных инструментов в объекте `EcmpPaymentInfo` необходимо передавать параметр `hideSavedWallets` со значением `false`. Более подробная информация об этой возможности представлена [в отдельной статье](ru_PP_saved_data.md). ## Дополнительные параметры вызова {#ru_sdk_react_native_parameters} ### Параметры объекта EcmpPaymentInfo {#section_ssf_vth_sbc .section} Для работы с SDK React Native в объекте `EcmpPaymentInfo` можно использовать следующие дополнительные параметры. |Параметр|Описание| |:-------|:-------| |`paymentDescription` string |Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Cosmoshop purchase` | |`receiptData` string |Данные уведомления с информацией о товарных позициях. Представляет собой JSON-объект, закодированный с использованием алгоритма Base 64. Пример: `eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgI CAgICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMC wKICAgICAgICAgICAgInRheCI6MTgsCiAgICAg` | |`token` string |Токен платёжных данных. Представляет собой строку длиной не более 255 символов. Пример: `6bbd9255e484f00cc778246c5b7489aa4c498b8bb5231e85942437c` | |`hideSavedWallets` boolean |Параметр, позволяющий управлять отображением информации о сохранённых ранее платёжных инструментах. Возможные значения: - `true` — не отображать - `false` — отображать | |`languageCode` string |Код языка отображения платёжного интерфейса в формате ISO 639-1 alpha-2.Должен соответствовать одному из языков, поддерживаемых для используемого проекта. Пример: `IT` | |`regionCode` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `GB` | ### Параметры объекта EcmpPaymentOptions {#section_f3d_yth_sbc .section} В объекте `EcmpPaymentOptions` можно использовать следующие дополнительные параметры. |Параметр|Описание| | |--------|--------|--| |`googleMerchantId` string |Идентификатор мерчанта в сервисе Google Pay|1| |`googleMerchantName` string |Наименование мерчанта в сервисе Google Pay|2| |`googleIsTestEnvironment` boolean |Признак тестового платежа. Передаётся при проведении платежей с использованием метода Google Pay. Возможные значения: - `true` — тестовый платёж - `false` — платёж в рабочем режиме |3| |`applePayMerchantId` string |Идентификатор мерчанта в сервисе Apple Pay|4| |`applePayDescription` string |Сведения о мерчанте в сервисе Apple Pay|5| |`applePayCountryCode` string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Передаётся при проведении платежей с использованием метода Apple Pay. Пример: `SE` |6| |`isDarkTheme` boolean |Признак использования тёмной темы платёжного интерфейса. Возможные значения: - `true` — использовать - `false` — не использовать |7| |`brandColor` string |Базовый цвет для основных элементов платёжного интерфейса в шестнадцатеричном формате HEX. Пример: `#800080` |8| |`screenDisplayModes` list |Указание на отсутствие необходимости отображать информацию о результате платежа в платёжном интерфейсе:- `hideSuccessFinalPage` — не отображать информацию о проведении платежа - `hideDeclineFinalPage` — не отображать информацию об отклонении платежа |10| |`additionalFields` list |Дополнительные поля с информацией о пользователе. Содержит список параметров и может включать их значения. Пример: ``` additionalFields: [ EcmpAdditionalField(type: "email", value: "mail@mail.com"), EcmpAdditionalField(type: "first_name", value: "firstName"), ], ``` |11| |`storedCardType` integer |Указатель типа повторяемой оплаты: - `3` — автооплата - `5` — регулярная оплата |12| |`recipientInfo` object |Объект, содержащий сведения о получателе платежа|13| |`pan` string |Номер карты. Пример: `5443011850290191` |13-113| |`cardHolder` string |Имя и фамилия \(в соответствии с указанными на карте\). Пример: `Sonya Kovalevsky` |13-213| |`walletId` string |Номер электронного кошелька. Пример: `WID301185029011891` |13-313| |`walletOwner` string |Имя и фамилия получателя. Пример: `Sonya Kovalevsky` |13-413| |`country` string |Код страны проживания в формате ISO 3166-1 alpha-2. Пример: `SE` |13-513| |`address` string |Адрес проживания. Пример: `Albanovaegen 28` |13-613| |`city` string |Город проживания. Пример: `Stockholm` |13-713| |`stateCode` string |Штат проживания. Пример: `MN` |13-813| |`recurrentData` object |Объект, содержащий сведения о регистрируемой повторяемой оплате|14| |`register` boolean |Указатель необходимости зарегистрировать повторяемую оплату. Возможные значения: - `true` — платёж с регистрацией повторяемой оплаты - `false` — платёж без регистрации повторяемой оплаты |14-114| |`type` string |Категория регистрируемой повторяемой оплаты. Возможные значения: - `C` — экспресс-оплата \(OneClick\) - `U` — автооплата - `R` — регулярная оплата |14-214| |`expiryDay` string |Номер календарного дня, в который должна быть завершена повторяемая оплата\(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\)|14-314| |`expiryMonth` string |Порядковый номер месяца, в котором должна быть завершена повторяемая оплата\(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\)|14-414| |`expiryYear` string |Порядковый номер года, в котором должна быть завершена повторяемая оплата\(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\)|14-514| |`period` string |Указатель базового периода списаний \(для регулярной оплаты\). Возможные значения: - `D` — ежедневно - `W` — еженедельно - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\) - `Q` — ежеквартально - `Y` — ежегодно |14-614| |`interval` integer |Множитель для кратного увеличения периода списаний\(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`; например чтобы списания выполнялись раз в три недели, в параметре `period` надо задать значение `W`, а в параметре `interval` значение `3`|14-714| |`time` string |Время выполнения последующих списаний\(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`|14-814| |`startDate` string |Дата первого списания\(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`|14-914| |`scheduledPaymentID` string |Идентификатор, который необходимо присвоить повторяемой оплате \(для автоматического инициирования списаний\). Параметр следует передавать вместе с параметром `startDate` |14-1014| |`amount` integer |Сумма последующих списаний в дробных единицах валюты|14-1114| **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. --- # SDK Core для Android {#ru_sdk_core_android} статья о порядке применения SDK Core для интеграции платёжной формы с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе Android **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_core_android_overview} ### Введение {#section_uxy_q4v_35b .section} Mobile SDK Core для Android — это набор средств разработки, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, работающих на платформе Android. SDK Core для Android позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой для отправки и приёма необходимой информации при проведении платежей. При этом SDK Core для Android не обеспечивает интерфейсное взаимодействие с пользователем и при работе с ним можно использовать собственный платёжный интерфейс. В этой статье представлена информация о работе с SDK Core для Android с описанием схемы взаимодействия, сценариев проведения платежей, а также дополнительных возможностей с примерами кода на языке Kotlin. SDK Core для Android можно встраивать в мобильные приложения, работающие на платформе Android версии 5.0 и выше. Библиотеки SDK Core для Android и примеры кода расположены на GitHub по следующим ссылкам: - Библиотеки для Android: [https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/releases](https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/releases) - Примеры кода: [https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/](https://github.com/ITECOMMPAY/paymentpage-sdk-android-core/) ### Возможности {#section_x3b_xpv_35b .section} SDK Core для Android поддерживает работу с платёжными картами, а также альтернативным методом Google Pay.Функционально SDK Core для Android позволяет: - Проводить оплаты с незамедлительным списанием средств. - Осуществлять блокировку средств для последующего списания по истечении заданного периода, либо на основании подтверждающего запроса \(через интерфейсы [Gate](ru_Gate__cof_merchant_side.md) или [Dashboard](ru_dbl_payments.md)\). - Выполнять проверку платёжных карт для их дальнейшего использования. - Регистрировать проведение повторяемых оплат. - Сохранять платёжные данные для проведения последующих оплат. При проведении платежей от пользователей могут требоваться дополнительные действия, например прохождение аутентификации 3‑D Secure и указание сведений о владельце платёжного инструмента. Необходимость выполнения этих действий, как правило, зависит от протоколов и правилпровайдеров и платёжных систем, но в отдельных случаях может зависеть и от предпочтений мерчанта. SDK Core для Android поддерживает работу со следующими процедурами и дополнительными возможностями: - Аутентификация 3‑D Secure — процедура аутентификации пользователей по протоколам 3‑D Secure. - Каскадное проведение платежей — дополнительные попытки проведения платежей \(когда это актуально\) без изменения способа оплаты. - Дополнение информации о платежах — процедура указания дополнительных данных, которые могут запрашиваться платёжными системами в некоторых случаях. - Сбор данных о пользователях — получение и предоставление дополнительной информации о пользователях, которая может быть актуальна при проведении последующих платежей. Подключение возможностей каскадного проведения платежей и сбора данных о пользователях следует согласовывать со специалистами Ecommpay. ### Схема работы {#section_o25_pqv_35b .section} В общем случае проведение оплат с использованием SDK Core для Android выполняется согласно следующей схеме. ![](images/ecommpay/sdk/android/ru_msdk_core_android_functional.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK Core для Android этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта. 3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK Core для Android. 4. С помощью SDK Core для Android инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы на основе идентификаторов проекта и пользователя формируются и отправляются к SDK Core для Android списки с доступными платёжными методами исохранёнными платёжными данными. 6. В мобильном приложении выполняется обработка полученной от SDK Core для Android информации и её подготовка для отображения пользователю. 7. Пользователь выбирает платёжный метод \(если он не был задан при открытии платёжной сессии\),указывает необходимую информацию и подтверждает готовность провести оплату. 8. В мобильном приложении выполняется вызов конкретного сценария работы с SDK Core для Android — с учётом всех действий, выполненных пользователем. 9. От SDK Core для Android к платёжной платформе отправляется запрос на проведение оплаты по заданному сценарию. 10. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам иплатёжным системам. 11. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 12. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 13. От платёжной платформы к SDK Core для Android направляется информация о результате оплаты. 14. Уведомление с информацией о результате передаётся от SDK Core для Android к мобильному приложению и далее отображается пользователю. ## Подготовка к использованию {#ru_sdk_core_android_setup} ### Порядок интеграции {#section_emd_trv_35b .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK Core для Android со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK Core для Android и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Скачать и подключить SDK Core для Android. 2. Подготовить пользовательский интерфейс и обеспечить сбор данных, необходимых для инициирования платёжной сессии. Минимальный набор данных, который необходимо собрать для создания платёжной сессии, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK Core для Android, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием доступных платёжных методов\) и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK Core для Android следует обращаться в службу технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Установка библиотек {#section_dk4_jsv_35b .section} Для приложений, работающих на платформе Android версии 5.0 и выше поддерживается подключение библиотек SDK Core для Android через MavenCentral. Чтобы подключить библиотеки, необходимо выполнить следующее: 1. Открыть в приложении модуль `build.gradle.kts`. 2. Указать в секции `repositories` репозиторий `mavenCentral`: ```language-json allprojects { repositories { google() mavenCentral() } } ``` 3. Добавить в секцию `dependencies` следующее: ```language-json implementation "com.ecommpay:msdk-core-android:LATEST\_VERSION" ``` ### Обеспечение работы с подписью {#section_cnv_ttv_35b .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта. Порядок работы с подписью представлен в разделе [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_core_android_testing} Перед проведением реальных платежей через SDK UI & Core для Android рекомендуется протестировать проведение платежей с использованием тестового проекта. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде Ecommpay\(сделать это можно [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\). Также по согласованию со специалистами Ecommpay можно протестировать использование метода Google Pay и дополнительных возможностей, таких как каскадное проведение платежей и сбор данных о пользователях. Для перехода в тестовый режим проведения платежей необходимо: 1. Открыть в приложении модуль `build.gradle.kts`. 2. Указать идентификатор тестового проекта \(`projectId`\) и секретный ключ от него \(`projectSecretKey`\). 3. Запустить процесс синхронизации `gradle`. Чтобы перейти в рабочий режим, необходимо заменить тестовые значения \(идентификатор рабочего проекта и секретный ключ от него\) на рабочие. ## Использование {#ru_sdk_core_android_usage} SDK Core для Android поддерживает выполнение различных целевых действий и для каждого из них требуется определённый набор параметров. Обязательный минимум параметров передаётся в исходном запросе на создание платёжной сессии, остальные параметры могут быть запрошены у пользователя, а также получены со стороны платёжной платформы. На основании полученных параметров формируется запрос на создание платежа по одному из доступных сценариев. Сценарии, порядок выполнения целевых действий, а также набор параметров, доступных при работе с SDK Core для Android, представлены в следующих разделах этой статьи. ### Порядок выполнения целевых действий {#ru_sdk_core_android_payment_processing} SDK Core для Android поддерживает выполнение целевых действий с прямым использованием карт, а также использованием альтернативного метода Google Pay \([подробнее](pm_googlepay.md)\). Для работы с платёжным методом Google Pay предварительно необходимо связаться со специалистами службы технической поддержки Ecommpay и согласовать подключение метода. В общем случае для проведения оплат через SDK Core для Android со стороны мерчанта необходимо выполнить следующее: 1. Создать объект `MSDKCoreSession`. ```language-json val config = MSDKCoreSessionConfig.debug("API HOST", "WS API HOST") val msdkSession = MSDKCoreSession(config) ``` 2. Создать объект `PaymentInfo` с параметрами проведения платежа. В объекте должен содержаться обязательный минимум параметров \(идентификатор проекта, платежа и пользователя, а также сумма и валюта платежа\), дополнительно также могут быть переданы и другие параметры \([подробнее](ru_sdk_core_android.md#section_fpd_5bt_j5b)\). ```language-json val paymentInfo = PaymentInfo( // информация о платеже projectId = 553, // идентификатор проекта paymentId = "payment_21", // идентификатор платежа paymentAmount = 400, // сумма платежа paymentCurrency = "EUR", // код валюты платежа customerId = "12" // идентификатор пользователя ) ``` 3. Получить строку для подписывания параметров и передать её в серверную часть приложения. ```language-json paymentInfo.getParamsForSignature(), ``` 4. На стороне серверной части приложения подписать итоговый набор параметров и передать его в клиентскую часть. 5. Добавить подпись в объект `PaymentInfo`. 6. Отправить запрос на создание платёжной сессии. Для этого необходимо запустить выполнение метода `getInitInteractor`. В случае проведения оплат с прямым использованием платёжных карт при этомнеобходимо указать по крайней мере один из следующих параметров: `customerEmail` или `customerPhone`. Также для аутентификации 3‑D Secure на этом шаге рекомендуется указывать параметры со сведениями о платёжном адресе пользователя: - `billingCountry` — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\); - `billingPostal` — индекс платёжного адреса пользователя; - `billingCity` — город платёжного адреса пользователя; - `billingAddress` — название улицы платёжного адреса пользователя. **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование таких параметров может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. ```language-json val request = InitRequest( paymentInfo = paymentInfo, recurrentInfo = null, additionalFields = ( //список полей для запрашивания дополнительной информации customerEmail = customerEmail, customerPhone = customerPhone ) ) msdkSession.getInitInteractor().execute(request, this) ``` 7. Принять уведомление с информацией о создании платёжной сессии, а также списками доступных платёжных методов исохранённых платежных данных, актуальных для используемого проекта и конкретного пользователя. ```language-json fun onInitReceived( paymentMethods: List,, savedAccounts: List ) { val stringResourceManager = msdkSession.getStringResourceManager() val title = stringResourceManager.payment.methodsTitle val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager() val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa") val paymentMethods = msdkSession.getPaymentMethods() // получение списка платёжных методов val savedAccounts = msdkSession.getSavedAccounts() // получение списка сохранённых платёжных данных } ``` 8. Обработать полученные данные и отобразить пользователю форму оплаты. 9. Для проведения оплаты через Google Pay необходимо выполнить следующее: - Получить токен от Google Pay, для этого можно использовать класс `GooglePayHelper`. Подробная информация о настройке приложения для работы с Google Pay представлена [в документации](https://developers.google.com/pay/api/android/guides/tutorial#kotlin). ```language-json val googlePayHelper = GooglePayHelper("merchant Id") val googleJson = googlePayHelper.createPaymentDataRequest(BigDecimal.valueOf(12.34), "USD").toString() val gpayRequest = PaymentDataRequest.fromJson(googleJson) val client = Wallet.getPaymentsClient( this, Wallet.WalletOptions.Builder() .setEnvironment(WalletConstants.ENVIRONMENT_TEST)// тестовая среда .setTheme(WalletConstants.THEME_LIGHT) .build() ) AutoResolveHelper.resolveTask( client.loadPaymentData(gpayRequest), this, 991 ) ``` - Получить токен от Google Pay в уведомлении `onActivityResult`. ```language-json override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) { super.onActivityResult(requestCode, resultCode, data) if (data == null) return val paymentData = PaymentData.getFromIntent(data) val paymentInformation = paymentData?.toJson() ?: return val paymentMethodData: JSONObject = JSONObject(paymentInformation).getJSONObject("paymentMethodData") val token = paymentMethodData.getJSONObject("tokenizationData").getString("token") } ``` 10. Отправить запрос на создание платежа с учётом полученных от пользователя данных. Для этого необходимо запустить выполнение метода `getPayInteractor`. ```language-json // оплата с использованием карты interactor.execute( NewCardSaleRequest( // сценарий cvv = "123", // код проверки подлинности карты pan = "5413330000000019", // номер карты expiryDate = CardDate(month = 1, year = 2025), // месяц и год окончания срока действия карты cardHolder = "John Doe" // фамилия и имя держателя карты ), this ) // оплата с использованием метода Google Pay interactor.execute\( GooglePaySaleRequest\( // сценарий merchantId = merchant\_321, // идентификатор мерчанта token = token, // токен, полученный от Google Pay environment = GooglePayEnvironment.TEST // тестовая среда \), this \) ``` 11. Принять ряд уведомлений от SDK Core для Android: о создании платежа и об изменении статуса платежа. Если актуально, также принять уведомления о необходимости дополнения информации о платеже и прохождения аутентификации с использованием протокола 3‑D Secure и выполнить требуемые действия. 12. Принять уведомление с информацией о результате платежа и отобразить эту информацию пользователю. При проведении некоторых платежей со стороны мерчанта и пользователя требуется выполнить ряд действий, обязательных для тех или иных процедур. Описание работы с такими процедурами представлено в следующих разделах этой статьи. ### Параметры работы с SDK Core для Android {#ru_sdk_core_android_scenarios} #### Действия с платёжными картами {#section_afh_x5v_35b .section} Для выполнения таких целевых действий с прямым использованием карт, как проведение оплат \(`NewCardSaleRequest`\), выполнение блокировок средств \(`CardAuthRequest`\) и проверок действительности карт \(`CardVerifyRequest`\), используются следующие наборы данных. |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты \(для проверки действительности необходимо указывать `0`\) - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта - `register` \(boolean\) — признак регистрации повторяемых оплат, для которого необходимо использовать значение `true`. Информация о параметрах, доступных для регистрации повторяемых оплат представлена [в отдельной статье](ru_pp_recurring.md#section_fjz_4yy_1mb) |- `cvv` \(string\) — код проверки подлинности карты - `pan` \(string\) — номер карты \(без указания пробелов\) - `year` \(integer\) — год окончания срока действия карты - `month` \(integer\) — месяц окончания срока действия карты - `cardHolder` \(string\) — имя держателя, указанное на карте - `saveCard` \(boolean\) — признак сохранения данных платёжной карты | #### Формирование токенов {#section_qkb_kzr_j5b .section} SDK Core для Android поддерживает формирование токенов платёжных данных. При выполнении сценария формирования токенов \(`CardTokenizeRequest`\) не выполняется никаких финансовых операций, но создаётся безопасный идентификатор, ассоциированный с данными определённой платёжной карты. Информация о создании и использовании токенов представлена в соответствующих статьях: [Формирование токенов](ru_pp_token.md) и [Проведение оплат по токенам](ru_PP_Payment_by_token.md). Для формирования токенов через SDK Core для Android необходимы следующие наборы данных. |Создание платёжной сессии|Формирование токена| |-------------------------|-------------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта |- `pan` \(string\) — номер карты \(без указания пробелов\) - `year` \(integer\) — год окончания срока действия карты - `month` \(integer\) — месяц окончания срока действия карты - `cardHolder` \(string\) — имя держателя, указанное на карте | #### Использование сохранённых платёжных данных {#section_mxw_xwr_j5b .section} SDK Core для Android поддерживает возможности сохранения платёжных данных по инициативе пользователей и через формирование токенов, а также использования этих данных для проведения платежей. С использованием сохранённых платёжных данных и токенов можно проводить оплаты и выполнять блокировку средств через определённые сценарии. В случае с сохранёнными платёжными данными используются сценарии `SavedCardSaleRequest` \(для оплат\) и `SavedCardAuthRequest` \(для блокировок\), а в случае с токенами — `CardSaleTokenizeRequest` \(для оплат\) и `CardAuthTokenizeRequest` \(для блокировок\). |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта - `account_token` \(string\) — токен платёжных данных \(используется для сценариев с участием токена\) |- `cvv` \(string\) — код проверки подлинности карты - `accountId` \(integer\) — идентификатор сохранённых платёжных данных, полученный в уведомлении о создании платёжной сессии | #### Оплаты с использованием альтернативных методов {#section_lwv_3ks_j5b .section} SDK Core для Android поддерживает проведение оплат \(`GooglePaySaleRequest`\) и блокировку средств \(`GooglePayAuthRequest`\) с использованием метода Google Pay. Чтобы проводить оплаты с использованием метода Google Pay, со стороны мерчанта предварительно необходимо: 1. Зарегистрироваться в сервисе [Google Pay Business Console](https://pay.google.com/business/console) и получить идентификатор мерчанта в сервисе Google Pay \(Google merchant ID\). 2. Принять и соблюдать [Правила допустимого использования](https://payments.developers.google.com/terms/aup) Google Pay API, а также принять условия, приведённые [в Пользовательском соглашении](https://payments.developers.google.com/terms/sellertos) Google Pay API. 3. Встроить в пользовательский интерфейс кнопку Google Pay, соблюдая [рекомендации](https://developers.google.com/pay/api/web/guides/brand-guidelines) по правильному использованию бренда, и реализовать процесс получения токена с карточными данными пользователя от сервиса Google Pay. 4. Добавить в файл `AndroidManifest.xml` следующую информацию: ```language-json ``` |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта |- `merchantId` \(string\) — идентификатор мерчанта в сервисе Google Pay \(Google merchant ID\) - `token` — токен, полученный от Google Pay - `environment` — тестовый или реальный платёж \(доступные значения: `test` и `prod`; при указании значения `test`, в запросе также должен использоваться идентификатор тестового проекта мерчанта, при указании `prod` — идентификатор рабочего проекта\) - `recepientInfo` \(используется для сценария `GooglePayAuthRequest`\) — объект, содержащий сведения о пользователе; используется для оплат с целью погашения задолженностей | #### Использование дополнительных параметров {#section_fpd_5bt_j5b .section} Кроме обязательного минимума параметров в запросах могут использоваться и дополнительные. - `recurrentInfo` — объект с информацией о повторяемой оплате \([подробнее](ru_pp_recurring.md#section_fjz_4yy_1mb)\). - `paymentDescription` \(string\) — описание платежа. - `regionCode` \(string\) — код страны в формате ISO 3166 alpha-2. - `token` \(string\) — токен платёжных данных. - `forcePaymentMethod` \(string\) — код предварительно выбранного платежного метода. Коды платёжных методов доступны [в справочнике](ru_pm_codes.md). - `hideSavedWallets` \(boolean\) — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости не отображать пользователю сохранённые платёжные инструменты. Возможные значения: - `true` — сохранённые платёжные данные не отображаются пользователю. - `false` — сохранённые платёжные данные отображаются пользователю. ### Дополнительные возможности {#ru_sdk_core_android_additional_capabilities} #### Сохранение платёжных данных {#section_pry_ryv_35b .section} При работе с SDK Core для Android поддерживается сохранение платёжных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Сохранение платёжных данных может выполняться по инициативе пользователя при проведении оплат, либо через выполнение сценария формирования токена \(`CardTokenizeRequest`\). Возможность формирования токенов доступна в рамках проекта по умолчанию, а возможность сохранения платёжных данных по инициативе пользователя подключается отдельно. Для подключения возможности необходимо обратиться к специалистам технической поддержки Ecommpay, а также обеспечить отображение в пользовательском интерфейсе переключателя для сохранения данных. В результате сохранения платёжных данных по инициативе пользователя для каждого платёжного инструмента формируется идентификатор \(`account_id`\), ассоциированный с идентификатором конкретного пользователя \(`customer_id`\). В дальнейшем идентификаторы платёжных инструментов можно получить в уведомлении от SDK Core для Android о создании платёжной сессии и использовать в запросе на создание платежа. Если сохранение платёжных данных выполнялось в результате выполнения сценария `CardTokenizeRequest`, для конкретной платёжной карты пользователя формируется токен, который можно получить в уведомлении о формировании токена в объекте `Payment` и в дальнейшем указывать этот токен в запросах на проведение платежей. Для выполнения сценария формирования токена в запросе на создание сессии в SDK Core для Android со стороны мерчанта необходимо указать идентификаторы проекта и пользователя, остальные данные для формирования токена \(номер и срок действия платёжной карты, а также имя держателя карты\) — запросить у пользователя. ```language-json "SavedAccounts": { "number": "541333******0019", "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // токен платёжных данных "id": 12353661, // идентификатор сохранённых платёжных данных (`accountId`) "last_deposit_date": "2022-04-22 06:22:33", "last_tokenize_date": null, "type": "card", "additional": { "email": "john@example.com", "phone": "79012345678", "country": "RU", "recurring_enable": false, "card": { "holder": "Jonh Doe", "country": "RU", "bank_name": "CIAGROUP", "type": "mastercard", "product_name": "PREPAID", "expiry": "02/24" } }, ``` #### Аутентификация 3‑D Secure {#section_vvt_l2s_j5b .section} В случаях, когда для проведения платежей требуется выполнить аутентификацию пользователей по протоколам 3‑D Secure, со стороны мерчанта необходимо: 1. Принять от SDK Core для Android уведомление `onThreeDSecure` о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект `acsPage` с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации. 2. Отобразить пользователю страницу аутентификации. 3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод `threeDSecureHandled`. ```language-json func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment) { interactor.threeDSecureHandled() // вызов метода } ``` #### Каскадное проведение платежей {#section_rv3_ntz_l5b .section} В случаях, когда по каким-либо причинам попытка проведения платежа не завершилась успешно, можно использовать каскадное проведение платежей \([подробнее](ru_pp_cascading.md)\), которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеровбез изменения платёжного метода. Подключение этой возможности необходимо согласовывать со специалистами Ecommpay. Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK Core для Android поступает уведомление, в котором содержится объект `isCascading` со значением `true`, что означает, что в рамках каскадного проведения платежей доступно выполнение дополнительной попытки. Если для проведения платежа необходима аутентификация пользователя, со стороны мерчанта требуется отобразить пользователю информацию об ошибке, получить от него подтверждение о выполнении очередной попытки и повторить проведение платежа. Если аутентификация не требуется, дополнительные действия со стороны мерчанта не выполняются. ```language-json func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment) { interactor.threeDSecureHandled() } ``` #### Дополнение информации о платежах {#section_ihz_42s_j5b .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системыили провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Информация о процедуре дополнения информации о платеже представлена [в отдельной статье](ru_pp_clarification.md). Итоговый набор запрашиваемых данных зависит от требованийконкретного провайдера или платёжной системы и может варьироваться. Список параметров, актуальных для конкретного платежа поступает в уведомлении от SDK Core для Android после отправки запроса на создание платежа \(`GetPayInteractor`\). Со стороны мерчанта необходимо обеспечить отображение пользователю полей для заполнения запрашиваемых данных, а затем передать полученные значения к SDK Core для Android. ```language-json override fun onClarificationFields(clarificationFields: List, payment: Payment) { // получение списка запрашиваемых данных interactor.sendClarificationFields(clarificationFields) // передача полученных от пользователя данных } ``` #### Сбор данных о пользователях {#section_wvb_q2s_j5b .section} В некоторых случаях вместе с обязательными данными в некоторых случаях актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями, и сообщить эту информацию специалистам технической поддержки. Подробная информация об использовании возможности сбора дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). После получения от SDK Core для Android уведомления со списком запрашиваемых параметров со стороны мерчанта необходимо отобразить пользователю в форме оплаты поля для заполнения. Далее полученные значения необходимо передать к SDK Core для Android и продолжить проведение платежа. ```language-json override fun onCustomerFields(customerFields: List) { // получение списка запрашиваемых данных interactor.sendCustomerFields(customFields) // передача полученных от пользователя данных } ``` ### Приём уведомлений {#ru_sdk_core_android_callback} #### Информирование о платёжной сессии {#section_pwl_brs_j5b .section} SDK Core для Android поддерживает отправку уведомлений с информацией о платёжной сессии. Промежуточные уведомления, которые отправляются в рамках выполнения запроса на создание платёжной сессии, относятся к группе `InitDelegate` и информируют о различных событиях и возможных ошибках, актуальных до отправки запроса на создание платежа. К таким уведомлениям относятся: - `onInitReceived` — создание платёжной сессии в платёжной платформе Ecommpay. ```language-json override fun onInitReceived() { val stringResourceManager = msdkSession.getStringResourceManager() val title = stringResourceManager.payment.methodsTitle val setSecureLogoResourceManager = msdkSession.getSecureLogoResourceManager() val visaIconUrl = setSecureLogoResourceManager.getLogoUrl("visa") val paymentMethods = msdkSession.getPaymentMethods() val savedAccounts = msdkSession.getSavedAccounts() } ``` - `onPaymentRestored` — создание платёжной сессии с идентификатором платежа, который использовался ранее. Если платежу ещё не присвоен итоговый статус, можно использовать метод `PaymentRestoreRequest` и продолжить проведение инициированного ранее платежа. ```language-json override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_payment_restore) progressDialog = ProgressDialog(this@PaymentRestoreActivity) progressDialog.setMessage("Payment restoring") progressDialog.setCancelable(false) progressDialog.show() interactor.execute(PaymentRestoreRequest(), this) } ``` - `onError` — возникла ошибка. ```language-json override fun onError(code: "Network & Server API", message: "{"status":"validation","code":"501", "errors":{"sid":"Make payment before check status"}}") ``` #### Информирование о платеже {#section_wmr_mrs_j5b .section} Промежуточные и итоговые уведомления, которые отправляются в рамках создания платежа, относятся к группе `PayDelegate`. Такие уведомления могут содержать информацию о состоянии платежа, о необходимости выполнения дополнительных действий, а также возникающих ошибках. - `onPaymentCreated` — создание платежа. - `onStatusChanged` — изменение статуса платежа. - `onCustomerFields` — необходимость в указании дополнительных данных о пользователе. - `onThreeDSecure` — необходимость в выполнении аутентификации по протоколу 3‑D Secure. - `onClarificationFields` — необходимость в дополнении информации о платеже. - `onCompleteWithSuccess` — платёж проведён. - `onCompleteWithFail` — получен отказ в проведении платежа. - `onCompleteWithDecline` — платёж отклонён. - `onError` — возникла ошибка. ```language-json override fun onError(code: "Network & Server API", message: "{"status":"validation","code":"501", "errors":{"sid":"Make payment before check status"}}") ``` ### Реагирование на ошибки {#ru_sdk_core_android_error_codes} В случае, если при обработке запросов возникают ошибки, от SDK Core для Android поступают соответствующие уведомления. Возможные ошибки, причины их появления и предусмотренные для них дальнейшие действия со стороны мерчанта приведены в таблице. |Ошибка|Возможная причина|Рекомендуемые действия| |------|-----------------|----------------------| |`CLARIFICATION_FIELDS_ERROR`|В рамках выполнения процедуры дополнения информации о платеже переданы некорректные данные|Повторить заполнение дополнительных данных| |`CUSTOMER_ID_NOT_EXIST`|В запросе на формирование токена или проверку действительности платёжной карты не передан обязательный параметр `customerId`|Скорректировать запрос| |`ILLEGAL_ARGUMENTS`|В запросе переданы некорректные значения|Скорректировать запрос| |`INTERACTOR_NOT_RUNNING`|Выполнение действия, доступного в рамках проведения платежа, до его инициирования \(например, передача дополнительных данных о пользователе до отправки запроса на создание платежа\)|Отправить запрос на создание платежа| |`NETWORK_ERROR`|Ошибка соединения|Следует связаться со специалистами технической поддержки| |`NETWORK_IS_NOT_AVAILABLE`|Сеть недоступна|Повторить запрос позже| |`NETWORK_TIMEOUT`|Выполнение запроса отклонено из-за превышения допустимого времени ожидания|Повторить запрос позже| |`PAYMENT_ALREADY_EXIST`|Выполнение запроса отклонено из-за указания идентификатора платежа, который уже использовался ранее|Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса| |`PAYMENT_HAS_FINAL_STATUS`|Выполнение запроса отклонено из-за указания в запросе идентификатора платежа, которому уже присвоен итоговый статус|Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса| |`PAYMENT_METHOD_NOT_AVAILABLE`|Выполнение запроса отклонено из-за указания в запросе платёжного метода, недоступного в рамках используемого проекта|Указать доступный в рамках проекта платёжный метод и повторить отправку запроса| |`PAYMENT_NOT_FOUND`|Не найден объект `Payment`|Повторить выполнение запроса. В случае возникновения ошибки обратиться к специалистам технической поддержки.| |`PAYMENT_TOKEN_NOT_EXIST`|В запросе на проведение оплаты или проверки действительности платёжной карты с использованием токена не передан токен платёжных данных|Указать токен платёжных данных и повторить отправку запроса| |`SERVER_API_ERROR`|Ошибка на стороне SDK Core для Android|Следует связаться со службой технической поддержки| |`SESSION_NOT_INITIALIZED`|Выполнение запроса отклонено из-за попытки выполнить какой-либо сценарий до создания платёжной сессии|Инициировать создание платёжной сессии \(`InitInteractor`\)| |`SERVER_CONTENT_PARSING_ERROR`|Не удалось преобразовать ответ от сервера|Скорректировать запрос| |`SERVER_METHOD_NOT_FOUND`|Вызов метода, который не предусмотрен для работы с SDK Core для Android|Скорректировать запрос| |`SERVER_UNAUTHORIZED`|Возникла ошибка соединения|Повторить запрос позже| --- # SDK Core для iOS {#ru_sdk_core_ios} статья о порядке применения SDK Core для интеграции платёжной формы с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе iOS **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) ## Общая информация {#ru_sdk_core_ios_overview} ### Введение {#section_ylm_np1_k5b .section} Mobile SDK Core для iOS — это набор средств разработки, который может использоваться для подключения к платёжной платформе Ecommpay мобильных приложений, работающих на платформе iOS. SDK Core для iOS позволяет обеспечивать взаимодействие мобильного приложения с платёжной платформой для отправки и приёма необходимой информации при проведении платежей. При этом SDK Core для iOS не обеспечивает интерфейсное взаимодействие с пользователем и при работе с ним можно использовать собственный платёжный интерфейс. В этой статье представлена информация о работе с SDK Core для iOS с описанием схемы взаимодействия, сценариев проведения платежей, а также дополнительных возможностей с примерами кода на языке Swift. SDK Core для iOS можно встраивать в мобильные приложения, работающие на платформе iOS версии 11 и выше. Библиотеки SDK Core для iOS и примеры кода расположены на GitHub по следующим ссылкам: - Библиотеки для iOS: [https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core/releases](https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core/releases) - Примеры кода: [https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core](https://github.com/ITECOMMPAY/paymentpage-sdk-ios-core) ### Возможности {#section_ecf_4p1_k5b .section} SDK Core для iOS поддерживает работу с платёжными картами, а также альтернативным методом Apple Pay.Функционально SDK Core для iOS позволяет: - Проводить оплаты с незамедлительным списанием средств. - Осуществлять блокировку средств для последующего списания по истечении заданного периода, либо на основании подтверждающего запроса \(через интерфейсы [Gate](ru_Gate__cof_merchant_side.md) или [Dashboard](ru_dbl_payments.md)\). - Выполнять проверку платёжных карт для их дальнейшего использования. - Регистрировать проведение повторяемых оплат. - Сохранять платёжные данные для проведения последующих оплат. При проведении платежей от пользователей могут требоваться дополнительные действия, например прохождение аутентификации 3‑D Secure и указание сведений о владельце платёжного инструмента. Необходимость выполнения этих действий, как правило, зависит от протоколов и правил провайдеров и платёжных систем, но в отдельных случаях может зависеть и от предпочтений мерчанта. SDK Core для iOS поддерживает работу со следующими процедурами и дополнительными возможностями: - Аутентификация 3‑D Secure — процедура аутентификации пользователей по протоколам 3‑D Secure. - Каскадное проведение платежей — дополнительные попытки проведения платежей \(когда это актуально\) без изменения способа оплаты. - Дополнение информации о платежах — процедура указания дополнительных данных, которые могут запрашиваться платёжными системами в некоторых случаях. - Сбор данных о пользователях — получение и предоставление дополнительной информации о пользователях, которая может быть актуальна при проведении последующих платежей. Подключение возможностей каскадного проведения платежей и сбора данных о пользователях следует согласовывать со специалистами Ecommpay. ### Схема работы {#section_ttm_4p1_k5b .section} В общем случае проведение оплат с использованием SDK Core для iOS выполняется согласно следующей схеме. ![](images/ecommpay/sdk/ios/ru_msdk_core_ios_functional.svg) 1. Пользователь инициирует оплату в пользовательском интерфейсе мобильного приложения с помощью кнопки оплаты или иным заданным способом. 2. В приложении формируется набор параметров для создания платёжной сессии, с помощью SDK Core для iOS этот набор преобразуется в строку для подписывания, после чего строка передаётся к серверной части веб-сервиса мерчанта. 3. В серверной части веб-сервиса мерчанта при необходимости могут выполняться проверка и дополнение параметров и обязательно формируется подпись к итоговому набору, после чего подготовленные данные передаются назад к SDK Core для iOS. 4. С помощью SDK Core для iOS инициируется создание платёжной сессии в платёжной платформе. 5. На стороне платёжной платформы на основе идентификаторов проекта и пользователя формируются и отправляются к SDK Core для iOS списки с доступными платёжными методами исохранёнными платёжными данными. 6. В мобильном приложении выполняется обработка полученной от SDK Core для iOS информации и её подготовка для отображения пользователю. 7. Пользователь выбирает платёжный метод \(если он не был задан при открытии платёжной сессии\),указывает необходимую информацию и подтверждает готовность провести оплату. 8. В мобильном приложении выполняется вызов конкретного сценария работы с SDK Core для iOS — с учётом всех действий, выполненных пользователем. 9. От SDK Core для iOS к платёжной платформе отправляется запрос на проведение оплаты по заданному сценарию. 10. На стороне платёжной платформы выполняются регистрация платежа и все необходимые технические действия, в том числе передача требуемых данных в платёжную среду: к провайдерам и платёжным системам. 11. В платёжной среде выполняется обработка платежа, по итогам которой в платёжную платформу поступает информация о результате. 12. В платёжной платформе обрабатывается итоговая информация, после чего к серверной части веб-сервиса отправляется программное оповещение о результате оплаты. 13. От платёжной платформы к SDK Core для iOS направляется информация о результате оплаты. 14. Уведомление с информацией о результате передаётся от SDK Core для iOS к мобильному приложению и далее отображается пользователю. ## Подготовка к использованию {#ru_sdk_core_ios_setup} ### Порядок интеграции {#section_q1w_4lf_k5b .section} Для подключения веб-сервиса к платёжной платформе Ecommpay с использованием SDK Core для iOS со стороны мерчанта необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора и ключа для взаимодействия с Ecommpay — отправить заявку на подключение. 2. Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK Core для iOS и согласовать порядок тестирования и запуска. 2. Выполнить подготовительные технические работы: 1. Скачать и подключить SDK Core для iOS. 2. Подготовить пользовательский интерфейс и обеспечить сбор данных, необходимых для инициирования платёжной сессии. Минимальный набор данных, который необходимо собрать для создания платёжной сессии, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа. 3. Обеспечить подписывание данных на стороне серверной части мобильного приложения. 4. Обеспечить на стороне веб-сервиса приём и корректное реагирование на уведомления от SDK Core для iOS, а также оповещения от платёжной платформы. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования\(в том числе с использованием доступных платёжных методов\) и запуска решения в работу. 1. Для тестирования следует использовать идентификатор тестового проекта и данные [тестовых карт](ru_test_cards.md). 2. Для перехода в рабочий режим следует изменить значение идентификатора тестового проекта на рабочее значение, полученное от Ecommpay. При возникновении вопросов о работе с SDK Core для iOS следует обращаться в службу технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ### Установка библиотек {#section_qdy_tlf_k5b .section} Для приложений, работающих на платформе iOS 11 и выше поддерживается подключение библиотек SDK Core для iOS через CocoaPods. Чтобы подключить библиотеки, необходимо выполнить следующее: 1. Открыть файл `Podfile` и добавить в него следующие строки: ```language-json target 'App' do pod 'MsdkCore' end ``` 2. Выполнить команду `pod install`. 3. Импортировать библиотеку с помощью команды `import MsdkCore`. ### Обеспечение работы с подписью {#section_csb_tpf_k5b .section} Подписывание данных должно выполняться в серверной части веб-сервиса с использованием секретного ключа, полученного от Ecommpay. Для работы с подписью могут использоваться готовые компоненты, такие как SDK для веб-сервисов на разных языках программирования \([подробнее](ru_sdk_overview.md)\), либо собственные решения, реализованные на стороне мерчанта. Порядок работы с подписью представлен в разделе [Работа с подписью к данным](ru_platform_signature.md). ## Тестирование {#ru_sdk_core_ios_testing} Перед проведением реальных платежей через SDK Core для iOS рекомендуется протестировать проведение платежей с использованием тестового проекта. Идентификатор тестового проекта и секретный ключ для него можно получить при подключении к тестовой среде Ecommpay\(сделать это можно [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\). Также по согласованию со специалистами Ecommpay можно протестировать использование метода Apple Pay и дополнительных возможностей, таких как каскадное проведение платежей и сбор данных о пользователях. Для перехода в тестовый режим проведения платежей необходимо: 1. Перейти в папку проекта и выполнить команду `pod install`. 2. Открыть проект через `iosApp.xcworkspace`. 3. В файле `Info.plist` указать идентификатор тестового проекта \(`PROJECTID`\) и секретный ключ от него \(`PROJECT_SECRET_KEY`\). Чтобы перейти в рабочий режим, необходимо заменить тестовые значения \(идентификатор рабочего проекта и секретный ключ от него\) на рабочие. **Внимание:** Для тестирования проведения платежей с помощью SDK Core для iOS с использованием Apple Pay не следует применять эмуляторы устройств. Для такого тестирования требуется соответствующее физическое устройство — при использовании эмулятора невозможно получить корректный токен от сервиса Apple Pay и, как следствие, провести платёж. Ошибки, полученные при использовании эмулятора, ожидаемы и не отображают фактическую ситуацию при проведении реальных платежей. ## Использование {#ru_sdk_core_ios_usage} SDK Core для iOS поддерживает выполнение различных целевых действий и для каждого из них требуется определённый набор параметров. Обязательный минимум параметров передаётся в исходном запросе на создание платёжной сессии, остальные параметры могут быть запрошены у пользователя, а также получены со стороны платёжной платформы. На основании полученных параметров формируется запрос на создание платежа по одному из доступных сценариев. Сценарии, порядок выполнения целевых действий, а также набор параметров, доступных при работе с SDK Core для iOS, представлены в следующих разделах этой статьи. ### Порядок выполнения целевых действий {#ru_sdk_core_ios_payment_processing} SDK Core для iOS поддерживает выполнение целевых действий с прямым использованием карт, а также использованием альтернативного метода Apple Pay \([подробнее](pm_applepay.md)\). Для работы с платёжным методом Apple Pay предварительно необходимо связаться со специалистами службы технической поддержки Ecommpay и согласовать его подключение. В общем случае для проведения оплат через SDK Core для iOS со стороны мерчанта необходимо выполнить следующее: 1. Создать объект `MSDKCoreSession`. ```language-json let msdkConfig = MSDKCoreSessionConfig.companion.debug(apiHost: "API HOST", wsApiHost: "WS API HOST") let msdkSession = MSDKCoreSession(config: msdkConfig) ``` 2. Создать объект `PaymentInfo` с параметрами проведения платежа. В объекте должен содержаться обязательный минимум параметров \(идентификатор проекта, платежа и пользователя, а также сумма и валюта платежа\), дополнительно также могут быть переданы и другие параметры \([подробнее](ru_sdk_core_ios.md#section_vyl_dyf_k5b)\). ```language-json let paymentInfo = PaymentInfo.companion.create // информация о платеже ( projectId: 553, // идентификатор проекта paymentId: "payment_21", // идентификатор платежа customerId: "12", // идентификатор пользователя paymentAmount: 400, // сумма платежа paymentCurrency: "EUR" // код валюты платежа ) ``` 3. Получить строку для подписывания параметров и передать её в серверную часть приложения. ```language-json paymentInfo.getParamsForSignature(), ``` 4. На стороне серверной части приложения подписать итоговый набор параметров и передать его в клиентскую часть. 5. Добавить подпись в объект `PaymentInfo`. 6. Отправить запрос на создание платёжной сессии. Для этого необходимо запустить выполнение метода `getInitInteractor`. В случае проведения оплат с прямым использованием платёжных карт при этомнеобходимо указать по крайней мере один из следующих параметров: `customerEmail` или `customerPhone`. Также для аутентификации 3‑D Secure на этом шаге рекомендуется указывать параметры со сведениями о платёжном адресе пользователя: - `billingCountry` — код страны платёжного адреса пользователя в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\); - `billingPostal` — индекс платёжного адреса пользователя; - `billingCity` — название города платёжного адреса пользователя; - `billingAddress` — название улицы платёжного адреса пользователя. **Прим.:** [По данным платёжной системы Visa](files_for_downloads/cc0a9603-8fcc-4ef3-9738-3ffa823d06bd.pdf) полноценное использование таких параметров может существенно \(вплоть до 6 %\) повышать проходимость платежей и кардинально \(вплоть до 65 %\) снижать число операций, признаваемых мошенническими после их выполнения. ```language-json let request = InitRequest( paymentInfo: paymentInfo, recurrentInfo: nil, additionalFields: [ //список полей для запрашивания дополнительной информации "customerEmail": customerEmail, "customerPhone": customerPhone ] as [String: Any] ) msdkSession.getInitInteractor().execute( request: request, callback: self ) ``` 7. Принять уведомление с информацией о создании платёжной сессии, а также списками доступных платёжных методов исохранённых платежных данных, актуальных для используемого проекта и конкретного пользователя. ```language-json func onInitReceived(paymentMethods: \[PaymentMethod\], savedAccounts: [SavedAccount]) { let stringResourceManager = msdkSession.getStringResourceManager() let title = stringResourceManager?.payment.methodsTitle let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager() let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa") let paymentMethods = msdkSession.getPaymentMethods() // получение списка платёжных методов let savedAccounts = msdkSession.getSavedAccounts() // получение списка сохранённых платёжных данных } ``` 8. Обработать полученные данные и отобразить пользователю форму оплаты. 9. Для проведения оплат через Apple Pay необходимо выполнить следующее: - Получить токен от Apple Pay. Для этого можно использовать класс `PKPaymentRequest`, который позволяет взаимодействовать с PassKit. ```language-json let supportedPaymentNetworks = [PKPaymentNetwork.visa, PKPaymentNetwork.masterCard] let paymentItem = PKPaymentSummaryItem(label: "MSDK Pay", amount: NSDecimalNumber(value: 1.23)) if PKPaymentAuthorizationViewController.canMakePayments(usingNetworks: supportedPaymentNetworks) { let request = PKPaymentRequest() request.currencyCode = "EUR" request.countryCode = "GB" request.merchantIdentifier = "merchant_id" request.merchantCapabilities = PKMerchantCapability.capability3DS request.supportedNetworks = supportedPaymentNetworks request.paymentSummaryItems = [paymentItem] guard let paymentVC = PKPaymentAuthorizationViewController(paymentRequest: request) else { return } paymentVC.delegate = self self.present(paymentVC, animated: true, completion: nil) } ``` - Получить в уведомлении `PKPaymentAuthorizationViewControllerDelegate` токен. ```language-json var completion: ((PKPaymentAuthorizationResult) -> Void)? func paymentAuthorizationViewController(_ controller: PKPaymentAuthorizationViewController, didAuthorizePayment payment: PKPayment, handler completion: @escaping (PKPaymentAuthorizationResult) -> Void) { self.completion = completion let token = String(decoding: payment.token.paymentData, as: UTF8.self) } ``` 10. Отправить запрос на создание платежа с учётом полученных от пользователя данных. Для этого необходимо запустить выполнение метода `getPayInteractor`. ```language-json // оплата с использованием карты override func viewDidLoad() { super.viewDidLoad() // сценарий проведения оплаты с использованием карты AppDelegate.msdkSession?.getPayInteractor().execute (request: NewCardSaleRequest ( cvv: "123", pan: "5413330000000019", expiryDate = CardDate(month = 1, year = 2025), cardHolder: "John Doe", saveCard: false ), callback: self) } // оплата с использованием метода Apple Pay AppDelegate.msdkSession?.getPayInteractor\(\).execute \(request: ApplePaySaleRequest.init \( token: token // токен, полученный от Apple Pay \), callback: self ``` 11. Принять ряд уведомлений от SDK Core для iOS: о создании платежа и об изменении статуса платежа. Если актуально, также принять уведомления о необходимости дополнения информации о платеже и прохождения аутентификации с использованием протокола 3‑D Secure и выполнить требуемые действия. 12. Принять уведомление с информацией о результате платежа и отобразить эту информацию пользователю. При проведении некоторых платежей со стороны мерчанта и пользователя требуется выполнить ряд действий, обязательных для тех или иных процедур. Описание работы с такими процедурами представлено в следующих разделах этой статьи. ### Параметры работы с SDK Core для iOS {#ru_sdk_core_ios_scenarios} #### Действия с платёжными картами {#section_ixd_3wf_k5b .section} Для выполнения таких целевых действий с прямым использованием карт, как проведение оплат \(`NewCardSaleRequest`\), выполнение блокировок средств \(`CardAuthRequest`\) и проверок действительности карт \(`CardVerifyRequest`\), используются следующие наборы данных. |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты \(для проверки действительности необходимо указывать `0`\) - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта - `register` \(boolean\) — признак регистрации повторяемых оплат, для которого необходимо использовать значение `true`. Информация о параметрах, доступных для регистрации повторяемых оплат представлена [в отдельной статье](ru_pp_recurring.md#section_fjz_4yy_1mb) |- `cvv` \(string\) — код проверки подлинности карты - `pan` \(string\) — номер карты \(без указания пробелов\) - `year` \(integer\) — год окончания срока действия карты - `month` \(integer\) — месяц окончания срока действия карты - `cardHolder` \(string\) — имя держателя, указанное на карте - `saveCard` \(boolean\) — признак сохранения данных платёжной карты | #### Формирование токенов {#section_t2k_swf_k5b .section} SDK Core для iOS поддерживает формирование токенов платёжных данных. При выполнении сценария формирования токенов \(`CardTokenizeRequest`\) не выполняется никаких финансовых операций, но создаётся безопасный идентификатор, ассоциированный с данными определённой платёжной карты. Информация о создании и использовании токенов представлена в соответствующих статьях: [Формирование токенов](ru_pp_token.md) и [Проведение оплат по токенам](ru_PP_Payment_by_token.md). Для формирования токенов через SDK Core для iOS необходимы следующие наборы данных. |Создание платёжной сессии|Формирование токена| |-------------------------|-------------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта |- `pan` \(string\) — номер карты \(без указания пробелов\) - `year` \(integer\) — год окончания срока действия карты - `month` \(integer\) — месяц окончания срока действия карты - `cardHolder` \(string\) — имя держателя, указанное на карте | #### Использование сохранённых платёжных данных {#section_tmn_vwf_k5b .section} SDK Core для iOS поддерживает возможности сохранения платёжных данных по инициативе пользователей и через формирование токенов, а также использования этих данных для проведения платежей. С использованием сохранённых платёжных данных и токенов можно проводить оплаты и выполнять блокировку средств через определённые сценарии. В случае с сохранёнными платёжными данными используются сценарии `SavedCardSaleRequest` \(для оплат\) и `SavedCardAuthRequest` \(для блокировок\), а в случае с токенами — `CardSaleTokenizeRequest` \(для оплат\) и `CardAuthTokenizeRequest` \(для блокировок\). |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта - `account_token` \(string\) — токен платёжных данных \(используется для сценариев с участием токена\) |- `cvv` \(string\) — код проверки подлинности карты - `accountId` \(integer\) — идентификатор сохранённых платёжных данных, полученный в уведомлении о создании платёжной сессии | #### Оплаты с использованием альтернативных методов {#section_imf_1xf_k5b .section} SDK Core для iOS поддерживает проведение оплат \(`ApplePaySaleRequest`\) и блокировку средств \(`ApplePayAuthRequest`\) с использованием метода Apple Pay. Чтобы проводить оплаты с использованием метода Apple Pay, со стороны мерчанта предварительно необходимо: 1. Зарегистрировать в Apple идентификатор мерчанта \(Merchant ID\), позволяющий принимать платежи с использованием метода Apple Pay. Этот идентификатор действует бессрочно и может использоваться для разных сайтов и приложений iOS. Информация о регистрации этого идентификатора представлена в документации Apple: [Create a merchant identifier](https://help.apple.com/developer-account/#/devb2e62b839?sub=dev103e030bb). 2. Выпустить сертификат обработки платежей \(Payment Processing Certificate\). Этот сертификат используется в связке с идентификатором мерчанта и позволяет обеспечивать безопасность платёжных данных при проведении платежей с использованием метода Apple Pay. Информация о выпуске этого сертификата представлена в документации Apple: [Create a payment processing certificate](https://help.apple.com/developer-account/#/devb2e62b839?sub=devf31990e3f). 3. Передать специалистам технической поддержки Ecommpay сертификат обработки платежей, используя при этом оговорённые методы защиты. 4. Включить поддержку Apple Pay для проекта мобильного приложения в используемой среде разработки. |Создание платёжной сессии|Создание платежа| |-------------------------|----------------| |- `project_id` \(integer\) — идентификатор проекта, полученный от Ecommpay - `payment_id` \(string\) — идентификатор платежа, уникальный в рамках проекта - `payment_amount` \(integer\) — сумма платежа в дробных единицах валюты - `payment_currency` \(string\) — код валюты платежа в формате ISO 4217 alpha-3 - `customer_id` \(string\) — идентификатор пользователя, уникальный в рамках проекта |- `token` — токен, полученный от Apple Pay - `recepientInfo` — объект, содержащий сведения о пользователе; используется для оплат с целью погашения задолженностей \(`ApplePayAuthRequest`\) | #### Использование дополнительных параметров {#section_vyl_dyf_k5b .section} Кроме обязательного минимума параметров в запросах могут использоваться и дополнительные. - `recurrentInfo` — объект с информацией о повторяемой оплате \([подробнее](ru_pp_recurring.md#section_fjz_4yy_1mb)\). - `paymentDescription` \(string\) — описание платежа. - `regionCode` \(string\) — код страны в формате ISO 3166 alpha-2. - `token` \(string\) — токен платёжных данных. - `forcePaymentMethod` \(string\) — код предварительно выбранного платежного метода. Коды платёжных методов доступны [в справочнике](ru_pm_codes.md). - `hideSavedWallets` \(boolean\) — параметр, позволяющий управлять отображением сохранённых ранее платёжных инструментов и при необходимости не отображать пользователю сохранённые платёжные инструменты. Возможные значения: - `true` — сохранённые платёжные данные не отображаются пользователю. - `false` — сохранённые платёжные данные отображаются пользователю. ### Дополнительные возможности {#ru_sdk_core_ios_additional_capabilities} #### Сохранение платёжных данных {#section_xdh_szf_k5b .section} При работе с SDK Core для iOS поддерживается сохранение платёжных данных пользователей для последующего проведения платежей без повторного указания пользователями реквизитов. Сохранение платёжных данных может выполняться по инициативе пользователя при проведении оплат, либо через выполнение сценария формирования токена \(`CardTokenizeRequest`\). Возможность формирования токенов доступна в рамках проекта по умолчанию, а возможность сохранения платёжных данных по инициативе пользователя подключается отдельно. Для подключения возможности необходимо обратиться к специалистам технической поддержки Ecommpay, а также обеспечить отображение в пользовательском интерфейсе переключателя для сохранения данных. В результате сохранения платёжных данных по инициативе пользователя для каждого платёжного инструмента формируется идентификатор \(`account_id`\), ассоциированный с идентификатором конкретного пользователя \(`customer_id`\). В дальнейшем идентификаторы платёжных инструментов можно получить в уведомлении от SDK Core для iOS о создании платёжной сессии и использовать в запросе на создание платежа. Если сохранение платёжных данных выполнялось в результате выполнения сценария `CardTokenizeRequest`, для конкретной платёжной карты пользователя формируется токен, который можно получить в уведомлении о формировании токена в объекте `Payment` и в дальнейшем указывать этот токен в запросах на проведение платежей. Для выполнения сценария формирования токена в запросе на создание сессии в SDK Core для iOS со стороны мерчанта необходимо указать идентификаторы проекта и пользователя, остальные данные для формирования токена \(номер и срок действия платёжной карты, а также имя держателя карты\) — запросить у пользователя. ```language-json "SavedAccounts": { "number": "541333******0019", "token": "0bd983f99878381dce27d20478829458d19df7c88f287ad8753092d...", // токен платёжных данных "id": 12353661, // идентификатор сохранённых платёжных данных (`accountId`) "last_deposit_date": "2022-04-22 06:22:33", "last_tokenize_date": null, "type": "card", "additional": { "email": "john@example.com", "phone": "79012345678", "country": "RU", "recurring_enable": false, "card": { "holder": "Jonh Doe", "country": "RU", "bank_name": "CIAGROUP", "type": "mastercard", "product_name": "PREPAID", "expiry": "02/24" } }, ``` #### Аутентификация 3‑D Secure {#section_tp1_n1g_k5b .section} В случаях, когда для проведения платежей требуется выполнить аутентификацию пользователей по протоколам 3‑D Secure, со стороны мерчанта необходимо: 1. Принять от SDK Core для iOS уведомление `onThreeDSecure` о необходимости отображения пользователю страницы аутентификации. В уведомлении содержится объект `acsPage` с параметрами отображения страницы аутентификации и ссылкой для перенаправления пользователя после прохождения аутентификации. 2. Отобразить пользователю страницу аутентификации. 3. Дождаться перенаправления пользователя со страницы аутентификации и вызвать метод `threeDSecureHandled`. ```language-json func onThreeDSecure(acsPage: AcsPage, isCascading: Bool, payment: Payment) { interactor.threeDSecureHandled() // вызов метода } ``` #### Каскадное проведение платежей {#section_rv3_ntz_l5b .section} В случаях, когда по каким-либо причинам попытка проведения платежа не завершилась успешно, можно использовать каскадное проведение платежей \([подробнее](ru_pp_cascading.md)\), которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеровбез изменения платёжного метода. Подключение этой возможности необходимо согласовывать со специалистами Ecommpay. Если для используемого проекта подключена возможность каскадного проведения платежей, то после выполнения первой неуспешной попытки со стороны SDK Core для iOS поступает уведомление, в котором содержится объект `isCascading` со значением `true`, что означает, что в рамках каскадного проведения платежей доступно выполнение дополнительной попытки. Если для проведения платежа необходима аутентификация пользователя, со стороны мерчанта требуется отобразить пользователю информацию об ошибке, получить от него подтверждение о выполнении очередной попытки и повторить проведение платежа. Если аутентификация не требуется, дополнительные действия со стороны мерчанта не выполняются. ```language-json func onThreeDSecure(acsPage: AcsPage, isCascading: true, payment: Payment) { interactor.threeDSecureHandled() } ``` #### Дополнение информации о платежах {#section_m5l_2bg_k5b .section} В общем случае для проведения платежа в запросе достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. Информация о процедуре дополнения информации о платеже представлена [в отдельной статье](ru_pp_clarification.md). Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Список параметров, актуальных для конкретного платежа поступает в уведомлении от SDK Core для iOS после отправки запроса на создание платежа \(`GetPayInteractor`\). Со стороны мерчанта необходимо обеспечить отображение пользователю полей для заполнения запрашиваемых данные, а затем передать полученные значения к SDK Core для iOS. ```language-json func onClarificationFields(clarificationFields: [ClarificationField], payment: Payment) { // получение списка запрашиваемых данных interactor.sendClarificationFields(clarificationFields) // передача полученных от пользователя данных } ``` #### Сбор данных о пользователях {#section_uk3_kbg_k5b .section} В некоторых случаях вместе с обязательными данными в некоторых случаях актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Для подключения такой возможности со стороны мерчанта необходимо определить список запрашиваемых данных, а также обязательность их заполнения пользователями и сообщить эту информацию специалистам технической поддержки. Подробная информация об использовании возможности сбора дополнительных данных представлена [в отдельной статье](ru_PP_Gathering_customer_data.md). После получения от SDK Core для iOS уведомления со списком запрашиваемых параметров со стороны мерчанта необходимо отобразить пользователю в форме оплаты поля для заполнения. Далее полученные значения необходимо передать к SDK Core для iOS и продолжить проведение платежа. ```language-json func onCustomerFields(customerFields: [CustomerField]) { // получение списка запрашиваемых данных interactor.sendCustomerFields(customerFields) // передача полученных от пользователя данных } ``` ### Приём уведомлений {#ru_sdk_core_ios_callback} #### Информирование о платёжной сессии {#section_sms_vbg_k5b .section} SDK Core для iOS поддерживает отправку уведомлений с информацией о платёжной сессии. Промежуточные уведомления, которые отправляются в рамках выполнения запроса на создание платёжной сессии, относятся к группе `InitDelegate` и информируют о различных событиях и возможных ошибках, актуальных до отправки запроса на создание платежа. К таким уведомлениям относятся: - `onInitReceived` — создание платёжной сессии в платёжной платформе Ecommpay. ```language-json func onInitReceived(paymentMethods: \[PaymentMethod\], savedAccounts: [SavedAccount]) { let stringResourceManager = msdkSession.getStringResourceManager() let title = stringResourceManager?.payment.methodsTitle let secureLogoResourceManager = msdkSession.getSecureLogoResourceManager() let visaIconUrl = secureLogoResourceManager?.getLogoUrl(key: "visa") let paymentMethods = msdkSession.getPaymentMethods\(\) let savedAccounts = msdkSession.getSavedAccounts() ?? [] } ``` - `onPaymentRestored` — создание платёжной сессии с идентификатором платежа, который использовался ранее. Если платежу ещё не присвоен итоговый статус, можно использовать метод `PaymentRestoreRequest` и продолжить проведение инициированного ранее платежа. ```language-json override func viewDidLoad() { super.viewDidLoad() AppDelegate.msdkSession?.getPayInteractor().execute(request: PaymentRestoreRequest(), callback: self) } ``` - `onError` — возникла ошибка. ```language-json override fun onError(code: "Network & Server API", message: "{"status":"validation","code":"501", "errors":{"sid":"Make payment before check status"}}") ``` #### Информирование о платеже {#section_pp2_bhg_k5b .section} Промежуточные и итоговые уведомления, которые отправляются в рамках создания платежа, относятся к группе `PayDelegate`. Такие уведомления могут содержать информацию о состоянии платежа, о необходимости выполнения дополнительных действий, а также возникающих ошибках. - `onPaymentCreated` — создание платежа. - `onStatusChanged` — изменение статуса платежа. - `onCustomerFields` — необходимость в указании дополнительных данных о пользователе. - `onThreeDSecure` — необходимость в выполнении аутентификации по протоколу 3‑D Secure. - `onClarificationFields` — необходимость в дополнении информации о платеже. - `onCompleteWithSuccess` — платёж проведён. - `onCompleteWithFail` — получен отказ в проведении платежа. - `onCompleteWithDecline` — платёж отклонён. - `onError` — возникла ошибка. ```language-json override fun onError(code: "Network & Server API", message: "{"status":"validation","code":"501", "errors":{"sid":"Make payment before check status"}}") ``` ### Реагирование на ошибки {#ru_sdk_core_ios_error_codes} В случае, если при обработке запросов возникают ошибки, от SDK Core для iOS поступают соответствующие уведомления. Возможные ошибки, причины их появления и предусмотренные для них дальнейшие действия со стороны мерчанта приведены в таблице. |Ошибка|Возможная причина|Рекомендуемые действия| |------|-----------------|----------------------| |`CLARIFICATION_FIELDS_ERROR`|В рамках выполнения процедуры дополнения информации о платеже переданы некорректные данные|Повторить заполнение дополнительных данных| |`CUSTOMER_ID_NOT_EXIST`|В запросе на формирование токена или проверку действительности платёжной карты не передан обязательный параметр `customerId`|Скорректировать запрос| |`ILLEGAL_ARGUMENTS`|В запросе переданы некорректные значения|Скорректировать запрос| |`INTERACTOR_NOT_RUNNING`|Выполнение действия, доступного в рамках проведения платежа, до его инициирования \(например, передача дополнительных данных о пользователе до отправки запроса на создание платежа\)|Отправить запрос на создание платежа| |`NETWORK_ERROR`|Ошибка соединения|Следует связаться со специалистами технической поддержки| |`NETWORK_IS_NOT_AVAILABLE`|Сеть недоступна|Повторить запрос позже| |`NETWORK_TIMEOUT`|Выполнение запроса отклонено из-за превышения допустимого времени ожидания|Повторить запрос позже| |`PAYMENT_ALREADY_EXIST`|Выполнение запроса отклонено из-за указания идентификатора платежа, который уже использовался ранее|Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса| |`PAYMENT_HAS_FINAL_STATUS`|Выполнение запроса отклонено из-за указания в запросе идентификатора платежа, которому уже присвоен итоговый статус|Указать уникальный в рамках проекта идентификатор платежа и повторить отправку запроса| |`PAYMENT_METHOD_NOT_AVAILABLE`|Выполнение запроса отклонено из-за указания в запросе платёжного метода, недоступного в рамках используемого проекта|Указать доступный в рамках проекта платёжный метод и повторить отправку запроса| |`PAYMENT_NOT_FOUND`|Не найден объект `Payment`|Повторить выполнение запроса. В случае возникновения ошибки обратиться к специалистам технической поддержки.| |`PAYMENT_TOKEN_NOT_EXIST`|В запросе на проведение оплаты или проверки действительности платёжной карты с использованием токена не передан токен платёжных данных|Указать токен платёжных данных и повторить отправку запроса| |`SERVER_API_ERROR`|Ошибка на стороне SDK Core для iOS|Следует связаться со службой технической поддержки| |`SESSION_NOT_INITIALIZED`|Выполнение запроса отклонено из-за попытки выполнить какой-либо сценарий до создания платёжной сессии|Инициировать создание платёжной сессии \(`InitInteractor`\)| |`SERVER_CONTENT_PARSING_ERROR`|Не удалось преобразовать ответ от сервера|Скорректировать запрос| |`SERVER_METHOD_NOT_FOUND`|Вызов метода, который не предусмотрен для работы с SDK Core для iOS|Скорректировать запрос| |`SERVER_UNAUTHORIZED`|Возникла ошибка соединения|Повторить запрос позже| --- # SDK для C\# на платформе .NET {#ru_sdk_net} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке C\# на платформе .NET ## Общая информация {#section_ow3_yll_g5b .section} SDK для C\# на платформе .NET — это набор средств разработки для взаимодействия веб-сервисов, разработанных на C\#, с платёжной платформой Ecommpay при проведении оплат через Payment Page. SDK для C\# на платформе .NET позволяет подписывать набор параметров и формировать запрос на открытие Payment Page, а также проверять подлинность полученных от Ecommpay оповещений и получать из них информацию о платеже. В состав SDK для C\# на платформе .NET входят программный код библиотеки и служебные файлы. SDK для C\# на платформе .NET совместим с .NET версии 6.0 или выше и доступен для загрузки по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-net](https://github.com/ITECOMMPAY/paymentpage-sdk-net). ## Подготовка к работе {#section_iyq_yll_g5b .section} Для использования SDK для C\# на платформе .NET необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с платёжной платформой Ecommpay — отправить [заявку на подключение](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с платёжной платформой Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для C\# на платформе .NET и согласовать с ними порядок запуска. 2. Установить библиотеку, входящую в состав SDK для C\# на платформе .NET, и подключить её в коде. ```language-csharp using ECommPay.PaymentPage.SDK; ``` 3. Доработать код для использования необходимой функциональности. 4. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции и запуска решения в работу. При возникновении вопросов о работе с SDK для C\# на платформе .NET следует обращаться в службу технической поддержки Ecommpay. ## Открытие платёжной формы {#section_dmq_dml_g5b .section} Для открытия платёжной формы с помощью SDK для C\# на платформе .NET следует: 1. Убедиться, что библиотека, входящая в состав SDK для C\# на платформе .NET, подключена в исходном коде веб-сервиса. 2. Создать объект класса `Payment` и указать значения параметров платежа. ```language-csharp dynamic payment = new Payment(, ""); // Идентификаторы проекта и платежа, уникальные в рамках проекта payment.payment_amount = 1001; // Сумма платежа в дробных единицах валюты payment.payment_currency = "EUR"; // Код валюты в формате ISO-4217 alpha-3 payment.customer_id = "customer_112"; // Идентификатор пользователя payment.payment_description = "Тестовый платёж"; // Описание платежа (необязательный параметр) ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты. Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-csharp payment.customer_phone = "The customer's phone number. Must have from 4 to 24 digits"; payment.customer_email = "The customer's email"; ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-csharp payment.billing_postal = "The postal code of the customer's billing address"; payment.billing_country = "The country of the customer's billing address, in ISO 3166-1 alpha-2"; payment.billing_city = "The city of the customer's billing address"; payment.billing_address = "The street of the customer's billing address"; ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page \(подробнее — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md)\). 3. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Это необходимо для автоматического подписывания параметров. ```language-csharp var gate = new Gate(''); // Секретный ключ, полученный от Ecommpay ``` 4. Сформировать адрес для вызова платёжной формы. ```language-csharp var paymentUrl = gate.GetPurchasePaymentPageUrl(payment); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-xml https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM 36hokUzLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555 943554067... ``` 5. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). ```language-csharp namespace MyProject; using ECommPay.PaymentPage.SDK; public class Example { /// /// Идентификатор проекта, полученный от Ecommpay /// private const int ProjectId = 0; /// /// Секретный ключ, полученный от Ecommpay /// private const string SecretKey = "secret"; /// /// Возврат URL для открытия платёжной формы /// /// public static string GetUrl() { var paymentId = "test_payment"; // Идентификатор платежа, уникальный в рамках проекта dynamic payment = new Payment(ProjectId, paymentId); // Создание объекта Payment payment.payment_amount = 1001; // Сумма платежа в дробных единицах валюты payment.payment_currency = "EUR"; // Код валюты платежа в формате ISO-4217 alpha-3 payment.customer_id = "customer_112"; // Идентификатор пользователя payment.payment_description = "Тестовый платёж"; // Описание платежа var gate = new Gate(SecretKey); // Создание объекта Gate return gate.GetPurchasePaymentPageUrl(payment); // Возврат ссылки для открытия платёжной формы } } ``` ## Обработка оповещений {#section_vcn_3ml_g5b .section} Оповещение представляет собой HTTP-POST-запрос, содержащий информацию о платеже в формате JSON-строки. При работе с SDK для C\# на платформе .NET получать информацию из оповещений можно с использованием следующих методов: - `getPaymentId()` — возвращает идентификатор платежа; - `getPaymentStatus()` — возвращает текущий статус платежа; - `getPayment()` — возвращает всю информацию о платеже, полученную в оповещении. Чтобы получить информацию о платеже с использованием этих методов, необходимо: 1. Убедиться, что библиотека, входящая в состав SDK для C\# на платформе .NET, подключена в исходном коде веб-сервиса. 2. Если объект класса `Gate` не был создан при формировании запроса для вызова Payment Page — создать этот объект и указать значение секретного ключа, полученное от Ecommpay. ```language-csharp var gate = new Gate(''); ``` 3. Создать объект класса `Сallback`, используя JSON-строку с информацией о платеже, полученную в оповещении от платёжной платформы Ecommpay. ```language-csharp try { var callback = gate.HandleCallback(data); // Получение результата проверки данных } catch (ValidationException e) // Обработка возможных исключений { Console.WriteLine(e); // Вывод сообщения об ошибке } ``` 4. Использовать требуемый метод. ```language-csharp callback.get_payment_id() // Получение идентификатора платежа callback.get_payment_status() // Получение текущего статуса платежа callback.get_payment() // Получение всей информации о платеже ``` При использовании SDK для C\# на платформе .NET проверка подписи в оповещении выполняется автоматически. ```language-csharp namespace MyProject; using ECommPay.PaymentPage.SDK; public class Example { /// /// Секретный ключ, полученный от Ecommpay /// private const string SecretKey = "secret"; /// /// Обработка оповещения /// /// JSON-строка, полученная из оповещения. /// true при успешной обработке оповещения и false в других случаях public bool Handler(string data) { var gate = new Gate(SecretKey); // Создание объекта Gate ICallback callback; // Попытка получения обработанных данных try { // Получение результата проверки в виде объекта Callback callback = gate.HandleCallback(data); } // Обработка возможных исключений catch (SdkException e) { Console.WriteLine(e); // Вывод сообщения об ошибке return false; } // Получение объекта Payment по его идентификатору // var order = OrderRepository.Get(callback.GetPaymentId()); // Изменение статуса платежа в соответствии с полученным в оповещении // order.SetStatus(callback.GetPaymentStatus()); // Сохранение изменений // order.Save(); return true; } } ``` ## Дополнительные материалы {#section_kyl_ymw_g5b .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # SDK для Go {#ru_sdk_go} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Go SDK для Go — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Go, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для Go с примерами кода на языке программирования Go. SDK для Go совместим с Go версии 1.8 или выше и доступен для загрузки на GitHub по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-go](https://github.com/ITECOMMPAY/paymentpage-sdk-go). ## Возможности {#section_mdv_1pf_nhb .section} SDK для Go позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платежах. ## Состав {#section_rlb_55f_nhb .section} SDK для Go содержит библиотеку для разработки и автоматизированного тестирования, а также служебные файлы. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для Go необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с платёжной платформой Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Go и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для Go, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для Go следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для Go, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью компилятора. Чтобы установить библиотеки с помощью компилятора и подключить их в исходном коде веб-сервиса, необходимо: 1. Если не настроена переменная окружения $GOPATH — настроить. Поиск внешних библиотек и их зависимостей выполняется в каталогах, прописанных в переменную $GOPATH. 2. В командной строке компилятора выполнить следующую команду: ```language-php go get github.com/ITECOMMPAY/paymentpage-sdk-go ``` Эта команда служит для размещения загруженных библиотек в каталоге, указанном в переменной $GOPATH. 3. Подключить SDK для Go в исходном коде веб-сервиса в секции `import`, выполнив команду: ```language-php import "github.com/ITECOMMPAY/paymentpage-sdk-go" ``` ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для Go позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для Go следует: 1. Создать объект класса `payment` и указать значения параметров платежа. ```language-php payment := paymentpage.NewPayment(186, "1555943554067") // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR") // Код валюты в формате ISO-4217 alpha-3 payment.SetParam(paymentpage.ParamPaymentAmount, 1000) // Сумма в дробных единицах валюты payment.SetParam(paymentpage.ParamCustomerId, "customer_122") // Идентификатор пользователя payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж") // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-php payment.SetParam(paymentpage.ParamCustomerPhone, "The customer's phone number. Must have from 4 to 24 digits") payment.SetParam(paymentpage.ParamCustomerEmail, "The customer's email") ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-php payment.SetParam(paymentpage.ParamBillingPostal, "The postal code of the customer's billing address") payment.SetParam(paymentpage.ParamBillingCountry, "The country of the customer's billing address, in ISO 3166-1 alpha-2") payment.SetParam(paymentpage.ParamBillingCity, "The city of the customer's billing address") payment.SetParam(paymentpage.ParamBillingAddress, "The street of the customer's billing address") ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `gate` и указать значение секретного ключа, полученное от платёжной платформы Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-php gate := paymentpage.NewGate("<*secret\_key*>") // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-php paymentPageUrl := gate.GetPaymentPageUrl(*payment) ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-php https://paymentpage.ecommpay.com/payment?signature=OEKRtJiKStyoH%M36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0lXDE390M%3D%3D&payment_id=1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. ```language-php payment := paymentpage.NewPayment(186, "payment_id") // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.SetParam(paymentpage.ParamPaymentCurrency, "EUR") // Код валюты в формате ISO-4217 alpha-3 payment.SetParam(paymentpage.ParamPaymentAmount, 1000) // Сумма в дробных единицах валюты payment.SetParam(paymentpage.ParamCustomerID, "customer_112") // Идентификатор пользователя payment.SetParam(paymentpage.ParamPaymentDescription, "Тестовый платёж") // Описание платежа. Необязательный параметр payment.SetParam(paymentpage.ParamLanguageCode, "en") // Код языка, на котором платёжная форма открывается пользователю. Необязательный параметр gate := paymentpage.NewGate("<*secret\_key*>") // Секретный ключ проекта, полученный при интеграции от Ecommpay paymentPageUrl := gate.GetPaymentPageUrl(*payment) // Готовый запрос с подписью ``` ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой HTTP POST запрос с данными в формате JSON-строки. Чтобы извлечь информацию о результате проведения платежа из JSON-строки, необходимо: 1. Создать объект класса `gate` и указать значение секретного ключа, полученного от Ecommpay. ```language-php gate := paymentpage.NewGate("<*secret\_key*>") ``` 2. Создать объект класса `callback`, используя JSON-строку с информацией о платеже из оповещения от Ecommpay: ```language-php callback, err := gate.HandleCallback(data) ``` Если подпись некорректная или не удаётся извлечь данные из оповещения, возвращается интерфейс error. 3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа: ```language-php callback.GetPaymentId() // Получение идентификатора платежа callback.GetPaymentStatus() // Получение текущего статуса платежа callback.GetPayment() // Получение всей информации о платеже ``` Далее приведён пример оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для Go проверка подписи в оповещении выполняется автоматически. ``` { "project_id": 186, // Идентификатор проекта "payment": { // Информация о платеже "id": "1555943554067", // Идентификатор платежа "type": "purchase", // Тип платежа "status": "success", // Статус платежа "date": "2021-08-28T09:11:28+0000", // Дата и время проведения платежа "method": "card", // Платёжный метод "sum": { // Сумма и валюта платежа "amount": 1000, "currency": "EUR" }, "description": "Тестовый платёж" // Описание платежа }, "account": { // Информация о платёжном средстве "number": "431422******0056", "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2", "type": "visa", "card_holder": "ADA LOVELACE", "id": 778804, "expiry_month": "11", "expiry_year": "2024" }, "operation": { // Информация о последней операции в рамках платежа "id": 17839000001150, // Идентификатор операции "type": "sale", // Тип операции "status": "success", // Статус операции "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции "created_date": "2021-08-28T09:10:50+0000", "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса "sum_initial": { // Сумма и валюта операции, указанные в запросе "amount": 1000, "currency": "EUR" }, "sum_converted": { // Сумма и валюта операции с учётом настроенных для проекта правил конвертации "amount": 1000, "currency": "EUR" }, "provider": { // Информация о проведении платежа в платёжной системе "id": 6, "payment_id": "15354474886323", "date": "2021-02-07T08:34:24+0000", "auth_code": "563253", "endpoint_id": 6 }, "code": "0", // Унифицированный код ответа "message": "Success", // Расшифровка кода ответа "eci": "05" // Код индикатора ECI, отображающий результат аутентификации }, "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_sxr_qh2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # SDK для Java {#ru_sdk_java} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Java SDK для Java — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Java, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для Java с примерами кода на языке программирования Java. SDK для Java совместим с Java SE Development Kit версии 8 или выше и доступен для загрузки на GitHub по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-java](https://github.com/ITECOMMPAY/paymentpage-sdk-java). ## Возможности {#section_mdv_1pf_nhb .section} SDK для JavaSDK для Java позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платежах. ## Состав {#section_rlb_55f_nhb .section} SDK для Java содержит библиотеки для разработки и автоматизированного тестирования, а также служебные файлы. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для Java необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Java и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для Java, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки **test/java**. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для Java следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для Java, в проект с исходным кодом веб-сервиса можно вручную или автоматически. Способы установки и подключения библиотек могут отличаться в зависимости от среды разработки. Чтобы установить библиотеки вручную и подключить их в исходном коде веб-сервиса, необходимо: 1. Загрузить SDK для Java и сформировать JAR-архив из файлов, входящих в SDK. 2. Если в каталоге проекта с исходных кодом веб-сервиса не создан каталог **libs**, необходимо создать его. Поместить в каталог **libs** JAR-архив. 3. Подключить файл в проекте с исходным кодом веб-сервиса. ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для Java позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для Java следует: 1. Создать объект класса `Payment` и указать значения параметров платежа. ```language-java Payment payment = new Payment('186', "1555943554067"); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Сумма в дробных единицах валюты .setParam(Payment.PAYMENT_CURRENCY, "EUR") // Код валюты в формате ISO-4217 alpha-3 .setParam(Payment.CUSTOMER_ID, "customer_112") // Идентификатор пользователя .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж"); // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-java .setParam(Payment.CUSTOMER_PHONE, "The customer's phone number. Must have from 4 to 24 digits") .setParam(Payment.CUSTOMER_EMAIL, "The customer's email") ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-java .setParam(Payment.BILLING_POSTAL, "The postal code of the customer's billing address") .setParam(Payment.BILLING_COUNTRY, "The country of the customer's billing address, in ISO 3166-1 alpha-2t") .setParam(Payment.BILLING_CITY, "The city of the customer's billing address") .setParam(Payment.BILLING_ADDRESS, "The street of the customer's billing address") ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-java Gate gate = new Gate("<*secret\_key*>"); // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-java String paymentUrl = gate.getPurchasePaymentPageUrl(payment); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-java https://paymentpage.ecommpay.com/payment?signature=OEKRlLoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elb390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. ```language-java Payment payment = new Payment('186', "1555943554067"); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment .setParam(Payment.PAYMENT_AMOUNT, 1001) // Сумма в дробных единицах валюты .setParam(Payment.PAYMENT_CURRENCY, "EUR") // Код валюты в формате ISO-4217 alpha-3 .setParam(Payment.CUSTOMER_ID, "customer_112") // Идентификатор пользователя .setParam(Payment.PAYMENT_DESCRIPTION, "Тестовый платёж") // Описание платежа. Необязательный параметр .setParam(Payment.LANGUAGE_CODE, ("en") // Код языка, на котором Payment Page открывается пользователю Gate gate = new Gate("<*secret\_key*>"); // Секретный ключ проекта, полученный при интеграции от Ecommpay String paymentUrl = gate.getPurchasePaymentPageUrl(payment); // Готовый запрос с подписью ``` ## Использование режима отладки {#section_xv4_3k1_g5b .section} При работе с SDK для Java поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках. Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу `sdk.ecommpay.com`. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы \(как тестовые, так и реальные\) и анализировать информацию об ошибках. Для этого используется код следующего вида: ```language-java Payment payment = new Payment(, ""); payment.payment_amount = 1001; payment.payment_currency = "EUR"; payment.customer_id = "customer_112"; payment.payment_description = "Тестовый платёж"; Gate gate = new Gate(''); try { return gate.getPurchasePaymentPageUrl(payment); // Получение ссылки на открытие платёжной формы } catch (ValidationException e) { // Обработка возможных исключений System.out.println(e); // Вывод сообщения об ошибках } return null; ``` Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом: ```language-java One or more parameters is not valid: Customer_id: Must be not null // Не указан идентификатор пользователя, обязательный для запроса Account_token: Invalid account token // Указан некорректный токен ``` При отсутствии ошибок можно считать полученную ссылку на открытие Payment Page корректной. ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой **HTTP** **POST** запрос с данными в формате **JSON**-строки. Чтобы извлечь информацию о результате проведения платежа из **JSON**-строки, необходимо: 1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса `Gate`, создать его и указать значение секретного ключа, полученного от Ecommpay. ```language-java Gate gate = new Gate("<*secret\_key*>"); ``` 2. Создать объект класса `Callback`, используя **JSON**-строку с информацией о платеже из оповещения от Ecommpay: ```language-java Callback callback = gate.handleCallback(data); ``` 3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа: ```language-java callback.getPaymentId(); // Получение идентификатора платежа callback.getPaymentStatus(); // Получение текущего статуса платежа callback.getPayment(); // Получение всей информации о платеже ``` Далее приведён пример данных из оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для Java проверка подписи в оповещении выполняется автоматически. ``` { "project_id": 186, // Идентификатор проекта "payment": { // Информация о платеже "id": "1555943554067", // Идентификатор платежа "type": "purchase", // Тип платежа "status": "success", // Статус платежа "date": "2021-08-28T09:11:28+0000", // Дата и время проведения платежа "method": "card", // Платёжный метод "sum": { // Сумма и валюта платежа "amount": 1000, "currency": "EUR" }, "description": "Тестовый платёж" // Описание платежа }, "account": { // Информация о платёжном средстве "number": "431422******0056", "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2", "type": "visa", "card_holder": "ADA LOVELACE", "id": 778804, "expiry_month": "11", "expiry_year": "2024" }, "operation": { // Информация о последней операции в рамках платежа "id": 17839000001150, // Идентификатор операции "type": "sale", // Тип операции "status": "success", // Статус операции "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции "created_date": "2021-08-28T09:10:50+0000", "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса "sum_initial": { // Сумма и валюта операции, указанные в запросе "amount": 1000, "currency": "EUR" }, "sum_converted": { // Сумма и валюта операции с учётом настроенных для проекта правил конвертации "amount": 1000, "currency": "EUR" }, "provider": { // Информация о проведении платежа в платёжной системе "id": 6, "payment_id": "15354474886323", "date": "2021-02-07T08:34:24+0000", "auth_code": "563253", "endpoint_id": 6 }, "code": "0", // Унифицированный код ответа "message": "Success", // Расшифровка кода ответа "eci": "05" // Код индикатора ECI, отображающий результат 3D-Secure проверки }, "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_e3f_qh2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # SDK для JavaScript {#ru_sdk_javascript} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке JavaScript SDK для JavaScript — это набор средств разработки для взаимодействия веб-сервисов, разработанных на JavaScript, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для JavaScript с примерами кода на языке программирования JavaScript. SDK для JavaScript совместим с Java​Script на платформе Node.js 4.x и доступен для загрузки на GitHub по следующей ссылке: [https://github.com/ITECOMMPAY/paymentpage-sdk-js](https://github.com/ITECOMMPAY/paymentpage-sdk-js). ## Возможности {#section_mdv_1pf_nhb .section} SDK для JavaScript позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платежах. ## Состав {#section_rlb_55f_nhb .section} SDK для JavaScript содержит библиотеки и служебные файлы. Для работы могут использоваться: - **src** — библиотека для разработки, - **\_tests\_** — библиотека для автоматизированного тестирования. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для JavaScript необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для JavaScript и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для JavaScript, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки **\_tests\_**. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для JavaScript следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для JavaScript, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью систем управления пакетами Yarn или npm, которые обеспечивают загрузку необходимых библиотек из репозитория. Чтобы установить библиотеки с помощью Yarn или npm и подключить их в исходном коде веб-сервиса, необходимо: 1. Если система управления пакетами не установлена — загрузить, установить и настроить. Подробнее: - Yarn: [https://yarnpkg.com/en/docs/getting-started](https://yarnpkg.com/en/docs/getting-started) - npm: [https://www.npmjs.com/package/ecommpay](https://www.npmjs.com/package/ecommpay) 2. В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить одну из команд: ```language-javascript npm install ecommpay // для npm yarn add ecommpay // для Yarn ``` Эта команда служит для загрузки и размещения библиотек и их зависимостей в каталоге с модулями для подключения необходимых модулей в коде веб-сервиса. 3. Подключить модули в исходном коде веб-сервиса: ```language-javascript const { Payment } = require('ecommpay'); const { Callback } = require('ecommpay'); ``` ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для JavaScript позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для JavaScript следует: 1. Создать объект класса `Payment` и указать значения параметров платежа и значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-javascript const e = new Payment('186', '<*secret\_key*>'); // Идентификатор проекта и секретный ключ e.paymentId = '1555943554067'; // Идентификатор платежа, уникальный в рамках проекта e.paymentAmount = 1000; // Сумма в дробных единицах валюты e.paymentCurrency = 'EUR'; // Код валюты в формате ISO-4217 alpha-3 e.customerId = 'customer_122'; // Идентифкатор пользователя e.paymentDescription = 'Описание платежа'; // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-javascript e.paymentCustomerPhone = 'The customer phone number. Must have from 4 to 24 digits'; e.paymentCustomerEmail = 'The customer email'; ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-javascript e.paymentBillingPostal = 'The postal code of the customer billing address'; e.paymentBillingCountry = 'The country of the customer billing address, in ISO 3166-1 alpha-2'; e.paymentBillingCity = 'The city of the customer billing address'; e.paymentBillingAddress = 'The street of the customer billing address'; ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Сформировать адрес для вызова платёжной формы. ```language-javascript const url = e.getUrl(); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-javascript https://paymentpage.ecommpay.com/payment?signature=OEKRlLKStyoH%2BM36hokU zLZsuB2gO8JALVnyev9elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 3. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке в отдельной вкладке браузера.На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. ```language-javascript const e = new Payment('186', '<*secret\_key*>'); // Идентификатор проекта и секретный ключ e.paymentId = '1555943554067'; // Идентификатор платежа, уникальный в рамках проекта e.paymentAmount = 1000; // Сумма в дробных единицах валюты e.paymentCurrency = 'EUR'; // Код валюты в формате ISO-4217 alpha-3 e.customerId = 'customer_112'; // Идентификатор пользователя e.paymentDescription = 'Описание платежа'; // Описание платежа. Необязательный параметр e.language_code: 'EN'; // Код языка, на котором Payment Page открывается пользователю e.redirect = true; // Параметр, который отвечает за открытие сгенерированной платежной страницы в отдельной вкладке браузера const url = e.getUrl(); // Готовый запрос с подписью ``` ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой **HTTP** **POST** запрос с данными в формате **JSON**-строки. Чтобы извлечь информацию о результате проведения платежа из **JSON**-строки, необходимо: 1. Создать объект класса `Callback`, используя значение секретного ключа, полученного от Ecommpay, и данные из оповещения от Ecommpay: ```language-javascript const callback = new Callback(<*secret\_key*>, req.body); ``` 2. Использовать методы и свойства, доступные для работы с оповещениями. В следующем примере используются метод и свойство в исходном коде веб-сервиса, разработанном с использованием Express: ```language-javascript app.post('/payment/callback', function(req, res) { const callback = new Callback(<*secret\_key*>, req.body); if (callback.isPaymentSuccess()) { const paymentCont = callback.payment(); // Получение всей информации о платеже const paymentId = callback.getPaymentId(); // Получение идентификатора платежа // Здесь размещается исходный код для обработки оповещения проведённого платежа } }); ``` Далее приведён пример оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для JavaScript проверка подписи в оповещении выполняется автоматически. ``` { "project_id": 186, // Идентификатор проекта "payment": { // Информация о платеже "id": "1555943554067", // Идентификатор платежа "type": "purchase", // Тип платежа "status": "success", // Статус платежа "date": "2021-08-28T09:11:28+0000", // Дата и время проведения платежа "method": "card", // Платёжный метод "sum": { // Сумма и валюта платежа "amount": 1000, "currency": "EUR" }, "description": "Тестовый платёж" // Описание платежа }, "account": { // Информация о платёжном средстве "number": "431422******0056", "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2", "type": "visa", "card_holder": "ADA LOVELACE", "id": 778804, "expiry_month": "11", "expiry_year": "2024" }, "operation": { // Информация о последней операции в рамках платежа "id": 17839000001150, // Идентификатор операции "type": "sale", // Тип операции "status": "success", // Статус операции "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции "created_date": "2021-08-28T09:10:50+0000", "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса "sum_initial": { // Сумма и валюта операции, указанные в запросе "amount": 1000, "currency": "EUR" }, "sum_converted": { // Сумма и валюта операции с учётом настроенных для проекта правил конвертации "amount": 1000, "currency": "EUR" }, "provider": { // Информация о проведении платежа в платёжной системе "id": 6, "payment_id": "15354474886323", "date": "2021-02-07T08:34:24+0000", "auth_code": "563253", "endpoint_id": 6 }, "code": "0", // Унифицированный код ответа "message": "Success", // Расшифровка кода ответа "eci": "05" // Код индикатора ECI, отображающий результат 3D-Secure проверки }, "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_a1x_ph2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # SDK для PHP {#ru_sdk_php} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке PHP SDK для PHP — это набор средств разработки для взаимодействия веб-сервисов, разработанных на PHP, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для PHP с примерами кода на языке программирования PHP. SDK для PHP совместим с PHP версии 7.0 или выше и доступен для загрузкипо следующим ссылкам: - GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-php](https://github.com/ITECOMMPAY/paymentpage-sdk-php) - Packagist: [https://packagist.org/packages/ecommpay/paymentpage-sdk](https://packagist.org/packages/ecommpay/paymentpage-sdk) ## Возможности {#section_mdv_1pf_nhb .section} SDK для PHP позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платеже. ## Состав {#section_rlb_55f_nhb .section} SDK для PHP содержит библиотеки и служебные файлы. Для работы могут использоваться: - **src** — библиотеки для разработки, - **tests** — библиотеки для автоматизированного тестирования, - **composer.json** — файл, в котором описаны библиотеки. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для PHP необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для PHP и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для PHP, в каталог с исходным кодом веб-сервиса и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа и пример оповещения из библиотеки **tests**. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для PHP следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для PHP, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью менеджера зависимостей. Менеджер зависимостей Composer обеспечивает загрузку необходимых библиотек из репозитория [Packagist](https://packagist.org/packages/ecommpay/paymentpage-sdk) и формирование скрипта для подключения загруженных библиотек. Чтобы установить библиотеки с помощью Composer и подключить их в исходном коде веб-сервиса, необходимо: 1. Если не установлен Composer — загрузить, установить и настроить \(подробнее [https://getcomposer.org/](https://getcomposer.org/)\). 2. В командной строке операционной системы перейти в каталог с исходным кодом веб-сервиса и выполнить следующую команду: ```language-php composer require ecommpay/paymentpage-sdk ``` Эта команда служит для размещения загруженных библиотек в каталоге **vendor** и создания скрипта **autoload.php** для одновременного подключения всех библиотек в исходном коде веб-сервиса. 3. Подключить скрипт **autoload.php** в исходном коде веб-сервиса: ```php require` __DIR__.'../../vendor.autoload.php'; ``` ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для PHP позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для PHP следует: 1. Создать объект класса `Payment` и указать значения параметров платежа. ```language-php $payment = new ecommpay\Payment('186', '1555943554067'); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта $payment->setPaymentAmount(1000)->setPaymentCurrency('EUR'); // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3) $payment->setCustomerId('customer007'); // Идентификатор пользователя $payment->setPaymentDescription('Тестовый платёж'); // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-php $payment->setCustomerPhone('The customer phone number. Must have from 4 to 24 digits'); $payment->setCustomerEmail('The customer email'); ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-php $payment->setBillingPostal('The postal code of the customer billing address'); $payment->setBillingCountry('The country of the customer billing address, in ISO 3166-1 alpha-2'); $payment->setBillingCity('The city of the customer billing address'); $payment->setBillingAddress('The street of the customer billing address'); ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-php $gate = new ecommpay\Gate('<*secret\_key*>'); // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-php $url = $gate->getPurchasePaymentPageUrl($payment); ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-php https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платёжных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. На странице с вводом реквизитов, необходимых для проведения платежа, обеспечивается отображение таймера с обратным отсчётом времени. ```language-php $gate = new ecommpay\Gate('<*secret\_key*>'); // Секретный ключ проекта, полученный при интеграции $payment = new ecommpay\Payment('186', '1555943554067'); // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта $payment->setPaymentAmount(1000)->setPaymentCurrency('EUR'); // Сумма (в дробных единицах валюты) и код валюты (в формате ISO-4217 alpha-3) $payment->setPaymentDescription('Test payment'); // Описание платежа $payment->setCustomerId('customer007'); // Идентификатор пользователя $payment->setBestBefore(new \DateTime('2050-01-01 00:00:00 +0000')); // Дата и время, до которых платёж должен быть завершён $payment->setLanguageCode('en'); // Код языка, на котором Payment Page открывается пользователю $url = $gate->getPurchasePaymentPageUrl($payment); // Готовый запрос с подписью ``` ## Использование режима отладки {#section_l2r_2l1_g5b .section} При работе с SDK для PHP поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках. Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу `sdk.ecommpay.com` и убедиться в том, что используемый PHP-интерпретатор соответствует хотя бы одному из следующих условий: - поддерживается библиотека `curl` \([подробнее](https://www.php.net/manual/ru/book.curl.php)\); - поддерживается библиотека `sockets` c доступом к URL по протоколу HTTP \([подробнее](https://www.php.net/manual/ru/book.sockets.php)\); - для директивы `allow_fopen_url` указано значение `true` и поддержан доступ к URL по протоколу HTTP \([подробнее](https://www.php.net/manual/ru/function.fopen)\). После этого в рамках отладки можно задавать различные параметры вызова платёжной формы \(как тестовые, так и реальные\) и анализировать информацию об ошибках. Для этого используется код следующего вида: ```language-php $payment = new Payment(, ''); $payment->setPaymentAmount(1001) ->setPaymentCurrency('EUR') ->setPaymentDescription('Тестовый платёж') $gate = new Gate(''); try { return $gate->getPaymentPageUrl($payment); // Получение ссылки на открытие платёжной формы } catch (ValidationException $e) { // Обработка возможных исключений error_log($e->getFormattedMessage()); // Запись сообщения об ошибках в журнал } return null; ``` Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом: ```language-php One or more parameters is not valid: Customer_id: Must be not null // Не указан идентификатор пользователя, обязательный для запроса Account_token: Invalid account token // Указан некорректный токен ``` При отсутствии ошибок можно считать полученную ссылку на открытие Payment Page корректной. ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой **HTTP** **POST** запрос с данными в формате **JSON**-строки. Чтобы извлечь информацию о результате проведения платежа из **JSON**-строки, необходимо: 1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса `Gate`, создать его и указать значение секретного ключа, полученного от Ecommpay. ```language-php $gate = new ecommpay\Gate('<*secret\_key*>'); ``` 2. Создать объект класса `Callback`, используя **JSON**-строку с информацией о платеже из оповещения от Ecommpay: ```language-php $callback = $gate->handleCallback($data); ``` 3. Использовать методы, доступные для работы с оповещениями. Можно получить полную информацию о платеже или информацию только об отдельных параметрах платежа: ```language-php Callback::getPaymentId(); // Получение идентификатора платежа Callback::getPaymentStatus(); // Получение текущего статуса платежа Callback::getPayment(); // Получение всей информации о платеже ``` Далее приведён пример данных из оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для PHP проверка подписи в оповещении выполняется автоматически. ``` { "project_id": 186, // Идентификатор проекта "payment": { // Информация о платеже "id": "1555943554067", // Идентификатор платежа "type": "purchase", // Тип платежа "status": "success", // Статус платежа "date": "2021-08-28T09:11:28+0000", // Дата и время проведения платежа "method": "card", // Платёжный метод "sum": { // Сумма и валюта платежа "amount": 1000, "currency": "EUR" }, "description": "Тестовый платёж" // Описание платежа }, "account": { // Информация о платёжном средстве "number": "431422******0056", "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2", "type": "visa", "card_holder": "ADA LOVELACE", "id": 778804, "expiry_month": "11", "expiry_year": "2024" }, "operation": { // Информация о последней операции в рамках платежа "id": 17839000001150, // Идентификатор операции "type": "sale", // Тип операции "status": "success", // Статус операции "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции "created_date": "2021-08-28T09:10:50+0000", "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса "sum_initial": { // Сумма и валюта операции, указанные в запросе "amount": 1000, "currency": "EUR" }, "sum_converted": { // Сумма и валюта операции с учётом настроенных для проекта правил конвертации "amount": 1000, "currency": "EUR" }, "provider": { // Информация о проведении платежа в платёжной системе "id": 6, "payment_id": "15354474886323", "date": "2021-02-07T08:34:24+0000", "auth_code": "563253", "endpoint_id": 6 }, "code": "0", // Унифицированный код ответа "message": "Success", // Расшифровка кода ответа "eci": "05" // Код индикатора ECI, отображающий результат 3D-Secure проверки }, "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_jzk_ph2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # SDK для Python {#ru_sdk_python} статья о порядке применения SDK для создания и проверки подписи к данным в рамках веб-сервисов, разработанных на языке Python SDK для Python — это набор средств разработки для взаимодействия веб-сервисов, разработанных на Python, с платёжной платформой Ecommpay при проведении оплат через Payment Page. В этом разделе представлена информация о работе с SDK для Python с примерами кода на языке программирования Python. SDK для Python совместим с Python версии 3.5 или выше и доступен для загрузки по следующим ссылкам: - GitHub: [https://github.com/ITECOMMPAY/paymentpage-sdk-python](https://github.com/ITECOMMPAY/paymentpage-sdk-python), - PyPI: [https://pypi.org/project/ecommpay-sdk/](https://pypi.org/project/ecommpay-sdk/). ## Возможности {#section_mdv_1pf_nhb .section} SDK для Python позволяет: - подписывать набор параметров платежа и формировать адрес для вызова Payment Page, - проверять подлинность оповещений от Ecommpay и получать из них информацию о платежах. ## Состав {#section_rlb_55f_nhb .section} SDK для Python содержит библиотеку для разработки и автоматизированного тестирования, а также служебные файлы. ## Порядок работы {#section_ow5_sdb_mhb .section} Для использования SDK для Python необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: - Если у компании нет идентификатора проекта и ключа для взаимодействия с Ecommpay — отправить заявку на подключениепо ссылке [https://ecommpay.com/apply-now/](https://ecommpay.com/apply-now/). - Если у компании есть идентификатор и ключ для взаимодействия с Ecommpay — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Python и согласовать с ними порядок тестирования. 2. Установить библиотеки, входящие в состав SDK для Python, и подключить их в коде, а также доработать код для использования необходимой функциональности. 3. Протестировать и запустить в работу обновлённый исходный код веб-сервиса. - Для тестирования следует использовать тестовый идентификатор проекта, тестовые значения параметров платежа. - Для перевода в рабочий режим необходимо заменить тестовое значение project\_id на рабочее, полученное от Ecommpay. При возникновении вопросов о работе с SDK для Python следует обращаться в службу технической поддержки Ecommpay по адресу [support@ecommpay.com](mailto:support@ecommpay.com). ## Установка и подключение библиотек {#section_y13_j32_nhb .section} Устанавливать библиотеки, входящие в состав SDK для Python, в проект с исходным кодом веб-сервиса можно вручную или автоматически с помощью системы управления пакетами pip, которая обеспечивает загрузку необходимых библиотек из репозитория. Чтобы установить библиотеки с помощью pip и подключить их в исходном коде веб-сервиса, необходимо: 1. Если не установлена pip — загрузить, установить и настроить \(подробнее [https://pip.pypa.io/en/stable/](https://pip.pypa.io/en/stable/)\). 2. В командной строке операционной системы в каталоге с исходным кодом веб-сервиса выполнить следующую команду: ```language-python pip install ecommpay-sdk ``` 3. Подключить модули в исходном коде веб-сервиса: ```language-python from payment_page_sdk.gate import Gate from payment_page_sdk.payment import Payment ``` ## Вызов платёжной формы {#section_bty_ryn_lhb .section} Запрос для вызова Payment Page включает в себя набор параметров, подписываемых для обеспечения защиты данных при передаче запроса в платёжную платформу Ecommpay. SDK для Python позволяет автоматически подписывать используемые параметры. Для вызова Payment Page с применением SDK для Python следует: 1. Создать объект класса `Payment` и указать значения параметров платежа. ```language-python payment = Payment('186', '1555943554067') // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.payment_amount = 1001 // Сумма в дробных единицах валюты payment.payment_currency = 'EUR' // Код валюты в формате ISO-4217 alpha-3 payment.customer_id = 'customer_112' // Идентификатор пользователя payment.payment_description = 'Тестовый платёж' // Описание платежа. Необязательный параметр ``` Все параметры в данном примере, за исключением описания платежа, являются необходимыми для любой оплаты.Также могут потребоваться и другие параметры, например адрес электронной почты пользователя или его номер телефона для выполнения аутентификации 3‑D Secure. Их необходимо указывать следующим образом. ```language-python payment.customer_phone = 'The customer phone number. Must have from 4 to 24 digits' payment.customer_email = 'The customer email' ``` Кроме того, для оплат с использованием платёжных карт рекомендуется передавать сведения о платёжном адресе пользователя: код страны в формате ISO 3166-1 alpha-2 \([подробнее](ru_country_codes.md)\), индекс, названия города и улицы. Эти сведения указываются следующим образом. ```language-python payment.billing_postal = 'The postal code of the customer billing address' payment.billing_country = 'The country of the customer billing address, in ISO 3166-1 alpha-2' payment.billing_city = 'The city of the customer billing address' payment.billing_address = 'The street of the customer billing address' ``` Дополнительно можно использовать любые другие параметры из числа доступных для работы с Payment Page. Подробнее о доступных параметрах — в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 2. Создать объект класса `Gate` и указать значение секретного ключа, полученное от Ecommpay. Секретный ключ необходим для автоматического подписывания параметров. ```language-python gate = Gate('<*secret\_key*>') // Секретный ключ проекта, полученный при интеграции от Ecommpay ``` 3. Сформировать адрес для вызова платёжной формы. ```language-python payment_url = gate.get_purchase_payment_page_url(payment) ``` Корректный адрес для вызова платёжной формы содержит подпись и параметры платежа: ```language-python https://paymentpage.ecommpay.com/payment?signature=OEKRlLXKStyoH%2BM36hokU zLZsuB2gO8JALVnyevcV59akRi29elbheVscAEl0ljcoQVXDE390MwgWg%3D%3D&payment_id=TEST_1555943554067... ``` 4. Использовать сформированный адрес для вызова платёжной формы \([подробнее](ru_PP_Integration.md)\). Далее приведён пример формирования адреса для вызова платёжной формы Payment Page с открытием на английском языке.На странице с выбором платежных методов обеспечивается отображение информации о платеже: идентификатора, валюты, суммы и описания платежа. ```language-python payment = Payment('186', '1555943554067') // Идентификатор проекта и идентификатор платежа, уникальный в рамках проекта payment.payment_amount = 1001 // Сумма в дробных единицах валюты payment.payment_currency = 'RUB' // Код валюты в формате ISO-4217 alpha-3 payment.customer_id = 'customer_112' // Идентификатор пользователя payment.payment_description = 'Тестовый платёж' // Описание платежа. Необязательный параметр payment.language_code = 'en' // Код языка, на котором Payment Page открывается пользователю gate = Gate('<*secret\_key*>') // Секретный ключ проекта, полученный при интеграции от Ecommpay payment_url = gate.get_purchase_payment_page_url(payment) // Готовый запрос с подписью ``` ## Использование режима отладки {#section_s5f_rq1_g5b .section} При работе с SDK для Python поддерживается режим отладки, который позволяет проверять полноту и корректность указанных параметров и получать информацию о допущенных ошибках. Перед началом отладки следует обеспечить возможность отправки HTTP-запросов со стороны серверной части веб-сервиса к ресурсу `sdk.ecommpay.com`. После этого в рамках отладки можно задавать различные параметры вызова платёжной формы \(как тестовые, так и реальные\) и анализировать информацию об ошибках. Для этого используется код следующего вида: ```language-python payment = Payment(, "") payment.payment_amount = 1001 payment.payment_currency = 'EUR' payment.payment_description = 'Тестовый платёж' gate = Gate("") try: # Попытка выполнения кода return gate.get_purchase_payment_page_url(payment) # Получение ссылки на открытие платёжной формы except ValidationException as e: # Обработка возможных исключений print(e) # Вывод сообщения об ошибке в консоль return null ``` Информация о найденных ошибках, полученная в результате выполнения этих действий, в текстовом формате может выглядеть следующим образом: ```language-python One or more parameters is not valid: Customer_id: Must be not null // Не указан идентификатор пользователя, обязательный для запроса Account_token: Invalid account token // Указан некорректный токен ``` При отсутствии ошибок можно считать полученную ссылку на открытие Payment Page корректной. ## Обработка оповещений {#section_qxm_m24_lhb .section} Информацию о результатах проведения платежей можно получать в оповещениях, отправляемых со стороны Ecommpay на URL, который необходимо сообщить службе технической поддержки Ecommpay. Оповещение представляет собой **HTTP** **POST** запрос с данными в формате **JSON**-строки. Чтобы извлечь информацию о результате проведения платежа из **JSON**-строки, необходимо: 1. Если ранее, при формировании запроса для вызова Payment Page, не был создан объект класса `Gate`, создать объект и указать значение секретного ключа, полученного от Ecommpay. ```language-python gate = Gate('<*secret\_key*>') ``` 2. Создать объект класса `Сallback`, используя **JSON**-строку с информацией о платеже из оповещения от платёжной платформы Ecommpay: ```language-python callback = gate.handle_callback(data) ``` 3. Использовать методы, доступные для работы с оповещениями. Можно получить всю информацию о платеже или информацию только об отдельных параметрах платежа: ```language-python callback.get_payment_id() // Получение идентификатора платежа callback.get_payment_status() // Получение текущего статуса платежа callback.get_payment() // Получение всей информации о платеже ``` Далее приведён пример данных из оповещения, которое включает в себя подпись и информацию о результатах проведения платежа. При использовании SDK для Python проверка подписи в оповещении выполняется автоматически. ```language-json { "project_id": 186, // Идентификатор проекта "payment": { // Информация о платеже "id": "1555943554067", // Идентификатор платежа "type": "purchase", // Тип платежа "status": "success", // Статус платежа "date": "2021-08-28T09:11:28+0000", // Дата и время проведения платежа "method": "card", // Платёжный метод "sum": { // Сумма и валюта платежа "amount": 1000, "currency": "EUR" }, "description": "Тестовый платёж" // Описание платежа }, "account": { // Информация о платёжном средстве "number": "431422******0056", "token": "9cb38282187b7a5b5b91b5814c6b814162741b29c0c486fbbc500cd451abb8b2", "type": "visa", "card_holder": "ADA LOVELACE", "id": 778804, "expiry_month": "11", "expiry_year": "2024" }, "operation": { // Информация о последней операции в рамках платежа "id": 17839000001150, // Идентификатор операции "type": "sale", // Тип операции "status": "success", // Статус операции "date": "2021-08-28T09:11:28+0000", // Дата и время проведения операции "created_date": "2021-08-28T09:10:50+0000", "request_id": "2c8af331519833f2c96c4a1aaf60edfcffb...", // Идентификатор запроса "sum_initial": { // Сумма и валюта операции, указанные в запросе "amount": 1000, "currency": "EUR" }, "sum_converted": { // Сумма и валюта операции с учётом настроенных для проекта правил конвертации "amount": 1000, "currency": "EUR" }, "provider": { // Информация о проведении платежа в платёжной системе "id": 6, "payment_id": "15354474886323", "date": "2021-02-07T08:34:24+0000", "auth_code": "563253", "endpoint_id": 6 }, "code": "0", // Унифицированный код ответа "message": "Success", // Расшифровка кода ответа "eci": "05" // Код индикатора ECI, отображающий результат 3D-Secure проверки }, "signature": "22YlUIIgoppli/JX8w5F5+c2h12RXi81WLmgDx..." // Подпись оповещения } ``` ## Дополнительные материалы {#section_j2l_4h2_plb .section} Для организации работы с оповещениями также могут быть полезны следующие материалы: - [Работа с оповещениями](ru_platform_callbacks.md) - [Проведение платежей](ru_platform_payment_model.md) **На уровень выше:**[Интеграция с использованием SDK](ru_sdk_overview.md) --- # Интеграция с использованием плагинов {#ru_CMS} статьи о порядке применения плагинов для встраивания Payment Page в сайты на базе различных CMS и профильных платформ Современные системы управления содержимым\(CMS\)и профильные платформы позволяют оперативно запускать, поддерживать и развивать веб-сервисы для бизнеса. Чтобы обеспечивать максимально простое подключение таких веб-сервисов к платёжной платформе, Ecommpay предоставляет мерчантам специализированные интеграционные модули — плагины.Каждый из плагинов позволяет оперативно подключить веб-сервис, созданный в одной из популярных систем, к платформе Ecommpay и проводить платежи с использованием платёжной формы Payment Page и с обеспечением всех необходимых взаимодействий между веб-сервисом и платёжной платформой. С помощью плагинов Ecommpay можно подключать к платформе веб-сервисы, работа которых основана на использовании следующих систем: - [BigCommerce](ru_cms_bigcommerce.md) - [commercetools](ru_cms_commercetools.md)— с использованием решения Composable Commerce - [Magento](ru_CMS__magento.md) версии 2.2 или выше - [PrestaShop](ru_cms_prestashop.md) версии 8.1.5 или выше - [WordPress](ru_CMS__wordpress.md) версии6.2 или выше С вопросами об использовании плагинов Ecommpay, а также с предложениями о расширении их функциональности всегда можно обращаться к курирующему менеджеру; с вопросами о способах интеграции, тестирования и применения этих плагинов — к специалистам технической поддержки. - **[Использование плагина Ecommpay Payments для платформы BigCommerce](ru_cms_bigcommerce.md)** статья о порядке применения плагина для встраивания Payment Page в сайты на базе платформы BigCommerce - **[Использование плагина от Ecommpay для commercetools](ru_cms_commercetools.md)** статья о порядке применения плагина для встраивания Payment Page в сайты на базе платформы commercetools - **[Использование плагина от Ecommpay для CMS Magento](ru_CMS__magento.md)** статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS Magento - **[Использование плагина Ecommpay payments для CMS PrestaShop](ru_cms_prestashop.md)** статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS PrestaShop - **[Использование плагина Ecommpay Payments для CMS WordPress](ru_CMS__wordpress.md)** статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS WordPress с установленным плагином WooCommerce **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Использование плагина Ecommpay Payments для платформы BigCommerce {#ru_cms_bigcommerce} статья о порядке применения плагина для встраивания Payment Page в сайты на базе платформы BigCommerce **На уровень выше:**[Интеграция с использованием плагинов](ru_CMS.md) ## Введение {#ru_cms_bigcommerce_overview} В этой статье представлена информация о работе с платёжным плагином Ecommpay Payments в платформе BigCommerce. Этот плагин может использоваться в веб-сервисах, разработанных на базе платформы BigCommerce. Плагин Ecommpay Payments устанавливается через каталог плагинов [Apps&Integrations](https://www.bigcommerce.com/apps/) и административный интерфейс BigCommerce, позволяет открывать пользователям платёжную форму Payment Page от Ecommpay и обеспечивать все необходимые действия для проведения платежей, как в части взаимодействия с пользователями, так и в части взаимодействия с платёжной платформой Ecommpay, с передачей и приёмом всей необходимой информации. Технически плагин разворачивается в платёжной платформе Ecommpay и взаимодействие веб-сервиса с плагином строится через сетевое подключение к нему.Таким образом, на стороне веб-сервиса всегда используется актуальная версия плагина. ![](images/universal/cms/bigcommerce/cms_bigcommerce_orders_overview.png "Административный интерфейс BigCommerce") ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_pp_embedded1.png "Интерфейс платёжной формы Payment Page") ## Общая информация {#ru_cms_bigcommerce_general} ### Возможности {#section_ksx_npx_1bc .section} При использовании плагина Ecommpay Payments можно: - Встраивать в веб-сервис возможность вызова платёжной формы Payment Page от Ecommpay. Для этого достаточно установить плагин от Ecommpay и настроить его использование через интерфейс BigCommerce. - Настраивать использование различных платёжных методов, доступных для работы через плагин. Это можно делать через раскрывающиеся блоки на странице с параметрами работы плагина в интерфейсе BigCommerce. Технически для подключения отдельных платёжных методов может быть достаточно минимальных действий в интерфейсе BigCommerce, а все организационные вопросы можно решать через курирующего менеджера Ecommpay. - Конфигурировать работу плагина для разных веб-сервисов. При работе с группой веб-сервисов на базе платформы BigCommerce можно применять отдельные конфигурации плагина для каждого из таких сервисов. - Тестировать работу платёжной формы и возможности проведения платежей. Для этого следует оформить тестовый проект в платёжной платформе Ecommpay \(что можно сделать [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\) и включить тестовый режим работы плагина через интерфейс BigCommerce. - Проводить разовые оплаты в одну и две стадии. Для этого можно использовать те методы, в рамках которых поддерживаются соответствующие типы платежей.При этом списания в рамках двухстадийных оплат могут выполняться как на полную, так и на частичную сумму заблокированных средств. - Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина. Для этого можно использовать интерфейс BigCommerce и, если актуально, интерфейсы платёжной платформы Ecommpay \(пользовательский интерфейс Dashboard и Gate API\). Вместе с тем, при использовании интерфейсов платёжной платформы Ecommpay информация о платежах в интерфейсе BigCommerce обновляется, только если настроена отправка оповещений со стороны платёжной платформы \([подробнее](ru_dbl_projects.md)\). - Контролировать информацию о платежах, проводимых с помощью плагина. Для этого можно использовать интерфейс BigCommerce и, если актуально, — интерфейс Dashboard от Ecommpay. - Управлять заказами, оплаты по которым проводятся с помощью плагина, через интерфейс BigCommerce. При этом можно отменять и удалять такие заказы и корректировать их статусы вручную. Также следует учитывать, что автоматическое изменение статусов заказов при работе с плагином Ecommpay Payments не предусмотрено, но может быть настроено специалистами мерчанта с использованием возможностей платформы BigCommerce, а также собственных или сторонних решений. - Настраивать способ открытия платёжной формы Payment Page, адаптируя её под специфику веб-сервиса, и применять различные возможности, обеспечиваемые со стороны Ecommpay. При работе с плагином Ecommpay Payments для платёжной формы можно использовать большинство её дополнительных возможностей \([подробнее](ru_PP_Additional.md)\), за исключением отдельных, таких как проведение оплат по токенам. В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking,делать доступными для пользователей повторные попытки оплаты \([подробнее](ru_PP_Try_Again.md)\) и подключать отправку пользователям уведомлений о результатах оплат \([подробнее](ru_PP_receipt_data.md)\). Для подключения таких возможностей следует обращаться к специалистам технической поддержки Ecommpay. Такой спектр возможностей позволяет подстраиваться под различные особенности бизнеса, гибко настраивать пользовательские сценарии и обеспечивать высокий уровень конверсии платёжной формы и проходимости платежей. Для подключения и применения возможностей, предоставляемых Ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам Ecommpay. ### Схемы работы {#section_hdz_dlg_vyb .section} В схемах проведения оплат в одну и две стадии с использованием плагина Ecommpay Payments задействуются пользователь, веб-сервис со встроенным в него плагином, платёжная форма Payment Page, платёжная платформа и платёжная среда. При этом с помощью плагина на стороне веб-сервиса обеспечиваются автоматический вызов Payment Page и автоматическое взаимодействие с платёжной платформой в соответствии с заданными параметрами работы. При работе *с одностадийными оплатами*на основании одного исходного запроса выполняются разовый перевод средств от пользователя к мерчанту и отправка к веб-сервису оповещения о результате проведения платежа. ![](images/universal/cms/ru_cms_workflow.svg) 1. Пользователь на стороне веб-сервиса выбирает вариант оплатыс помощью одного из платёжных методов, доступных через плагин Ecommpay Payments. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Page для проведения платежавыбранным методом. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает итоговый запрос на оплату \(со всеми необходимыми сведениями\). 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе BigCommerce обновляется информация о состоянии платежа. 13. От платёжной платформы к Payment Page направляется информация о результате оплаты. 14. Информация о результате оплаты отображается пользователю в веб-сервисе мерчанта на странице с информацией об оплате заказа. При работе *с двухстадийными оплатами* на основании исходного запроса \(на первой стадии\) выполняется блокировка средств пользователя, а затем \(на второй стадии\) на основании подтверждающего запроса или автоматически по истечении заданного срока выполняется списание заблокированных средств или отмена блокировки. При этом на каждой стадии к веб-сервису отправляется оповещение с информацией о соответствующем результате. ![](images/universal/cms/ru_cms_workflow_auth.svg) 1. Пользователь на стороне веб-сервиса выбирает вариант оплатыс помощью одного из платёжных методов, доступных через плагин Ecommpay Payments. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Page для проведения платежавыбранным методом. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает запрос на выполнение блокировки средств. 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа и блокировка средств пользователя. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате блокировки средств. 12. От платёжной платформы к веб-сервису направляется оповещение о результате блокировки. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе BigCommerce обновляется информация о состоянии платежа. 13. От платёжной платформы к Payment Page направляется информация о результате блокировки. 14. Информация о результате блокировки отображается пользователю в веб-сервисе мерчанта на странице с информацией об оплате заказа. 15. После того как подтверждается необходимость списания средств, специалист мерчанта инициирует это списание, в результате чего \(с помощью плагина\) запрос на списание средств поступает в платёжную платформу и обрабатывается в ней. 16. Запрос передаётся в платёжную среду. 17. В платёжной среде выполняется обработка платежа. 18. Из платёжной среды к платёжной платформе направляется информация о результате списания. 19. От платёжной платформы к веб-сервису направляется оповещение о результате списания. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе BigCommerce обновляется информация о состоянии платежа. 20. Пользователь уведомляется о результате списания средствами веб-сервиса. Для взаимодействия с пользователями при проведении одностадийных оплат и блокировке средств в рамках двухстадийных оплат возможны два варианта работы: - со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса\(через элемент iframe\); - с открытием платёжной формы в отдельной вкладке. Первый из этих вариантов доступен только для оплат с прямым использованием платёжных карт и используется для них по умолчанию.В этомварианте пользователь указывает данные платёжной карты и подтверждает формирование заказа в платформе BigCommerce и платежа в платформе Ecommpay непосредственно на странице перехода к оплате в веб-сервисе\(с помощью кнопки **Place Order**\). Второй вариант используется для альтернативных платёжных методов и для оплат с прямым использованием платёжных карт, если для них был выбран способ открытия формы в отдельной вкладке.В этомварианте пользователь сначала подтверждает переход к оплате \(с помощью кнопки **Place Order** в веб-сервисе\) и уже после этого указывает необходимые данные в открывшейся платёжной форме и подтверждает формирование заказа в платформе BigCommerce и платежа в платформе Ecommpay\(с помощью кнопки **Оплатить**\). Вместе с тем, следует учитывать ряд особенностей: - Независимо от выбранного варианта открытия Payment Page, язык платёжной формы определяется в соответствии с заданным порядком работы \([подробнее](ru_PP_WigetLanguages.md#section_hhb_qgx_nqb)\). - Если для проекта подключена возможность [повторных попыток проведения платежей](ru_PP_Try_Again.md), следует использовать вариант работы с открытием платёжной формы Payment Page в отдельной вкладке.Для варианта работы со встраиванием формы в интерфейс веб-сервиса не поддерживается возможность перехода к повторной попытке непосредственно из формы. - Для заказов в веб-сервисе и платежей в платёжной платформе используются разные идентификаторы и статусы.Заказам на стороне веб-сервиса присваиваются порядковые номера \(например, `151`\) и статусы в соответствии с моделью выполнения заказов BigCommerce \([подробнее](https://support.bigcommerce.com/s/article/Order-Statuses?language=en_US)\), платежам на стороне платёжной платформы — идентификаторы в виде кодов из тридцати двух случайных символов \(например, `5876281a-4129-4fad-86ae-f1a24f637c7f`\), и статусы в соответствии с моделью проведения платежей Ecommpay \([подробнее](ru_platform_payment_model.md)\). С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру Ecommpay. ## Установка {#ru_cms_bigcommerce_installation} Чтобы начать работу с плагином Ecommpay Payments, его необходимо установить. Установка выполняется через каталог плагинов \([Apps&Integrations](https://www.bigcommerce.com/apps/)\) и административный интерфейс платформы BigCommerce. 1. Перейти [на страницу плагина](https://www.bigcommerce.com/apps/ecommpay-payments/) в каталоге **Apps&Integrations** и щёлкнуть кнопку **Get this app**. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_get_app.png "Страница плагина в каталоге Apps&Integrations") 2. Выбрать один из предлагаемых вариантов на открывшейся странице — зарегистрироваться в платформе BigCommerce\(если это не было сделано ранее\) или пройти аутентификацию. 3. Щёлкнуть кнопку **Download** на странице для загрузки плагина Ecommpay Payments в интерфейсе BigCommerce, в подразделе **Marketplace** раздела **Apps**. 4. Перейти в подраздел **My Apps** раздела **Apps** и щёлкнуть кнопку **Install** на панели плагина. В результате этих действий осуществляется сетевое подключение веб-сервиса к плагину Ecommpay Payments и на стороне веб-сервиса становится доступна актуальная версия плагина\(без необходимости её обновления\). **Прим.:** При поддержке со стороны мерчанта группы веб-сервисов на базе платформы BigCommerce и необходимости использования плагина Ecommpay Payments настраивать параметры его работы следует отдельно для каждого такого веб-сервиса. ## Тестирование {#ru_cms_bigcommerce_testing} ### Общая информация {#section_tp4_m4r_bbc .section} Тестировать работу плагина и проводить тестовые платежи по различным платёжным сценариямбез реального списания средств можно через тестовую среду платёжной платформы Ecommpay. Подключиться к платформе можно, заполнив соответствующую форму [на основном сайте компании](https://ecommpay.com/apply-now/) и получив идентификатор и ключ тестового проекта. Также необходимо сообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина Ecommpay Payments, и валюту проведения платежей, если актуально тестировать проведение платежей в конкретной валюте. Следует учитывать, что при использовании тестовой среды платёжной платформы Ecommpay плагин подключается к веб-сервису и становится доступен пользователям как вариант оплаты. Поэтому в тех случаях, когда плагин подключается к работающему веб-сервису, рекомендуется выполнять тестирование в период низкой нагрузки и предупреждать пользователей о проводимых работах. ### Настройка параметров {#section_s3d_x4r_bbc .section} Для подготовки к тестированию следует *активировать плагин* Ecommpay Payments как вариант оплаты в веб-сервисе и *настроить параметры* его работы.При поддержке группы веб-сервисов это следует делать для каждого веб-сервиса отдельно. Чтобы активировать плагин в веб-сервисе, следует: 1. Перейти к параметрам использования вариантов оплаты в интерфейсе BigCommerce. Для этого следует выбрать раздел **Settings** на панели навигации и щёлкнуть строку **Payments** в секции **Setup** на открывшейся странице. 2. Выбрать один из доступных вариантов оплаты для использования плагина. Для этого следует раскрыть блок **Offline Payment Methods** в секции **Additional providers** и щёлкнуть кнопку **Set up** в строке подходящего варианта оплаты \(**Bank Deposit** или иного\). ![](images/universal/cms/bigcommerce/cms_bigcommerce_offline_pm.png "Секция Additional providers в интерфейсе BigCommerce") 3. Указать значение `Ecommpay` в поле **Display Name** на открывшейся странице и сохранить изменение, щёлкнув кнопку **Save**. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings.png "Страница с параметрами работы варианта оплаты в интерфейсе BigCommerce ") Чтобы настроить параметры работы плагина, следует: 1. Перейти к параметрам работы плагина в интерфейсе BigCommerce. Для этого следует выбрать раздел **Apps**, а затем — пункт Ecommpay Payments на панели навигации. 2. Проверить корректность и при необходимости скорректировать основные параметры работы плагина: - **Plugin Enabled** — доступность в веб-сервисе\(должна быть включена\). Если этот переключатель включён, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если этот переключатель выключен, то все платёжные методы, подключённые для работы через плагин, становятся недоступными для проведения платежей. - **Store Channel** — название веб-сервиса мерчанта в платформе BigCommerce \(должен быть выбран веб-сервис, для которого задаются параметры работы плагина\). - **Mode** — режим работы плагина\(должен быть выбран вариант **test**\). - **Test Project ID** — идентификатор тестового проекта для взаимодействия с платформой\(должен соответствовать полученному от Ecommpay\). - **Test Secret Key** — ключ тестового проекта\(должен соответствовать полученному от Ecommpay\). - **Merchant Callback Url** — URL для приёма на стороне плагина оповещений от платёжной платформы\(формируется и подставляется автоматически при установке плагина Ecommpay Payments\). - **Host Url** — доменное имя веб-сервиса мерчанта, для которого задаются параметры работы плагина \(должно быть указано вручную\). - **Payment Mode** — вариант проведения оплат через платёжную платформу. Можно выбрать один из следующих вариантов: - **Sale** — в одну стадию \(с незамедлительным списанием средств\); - **Authorization Only** — в две стадии \(с предварительной блокировкой и последующим списанием средств\). Первый вариант доступен для всех платёжных методов, подключённых для работы через плагин, а второй вариант — только для тех методов, для которых поддерживаются оплаты в две стадии \(таких как карточные платежи и методы Apple Pay и Google Pay\). **Внимание:** Параметры **Test Project ID** и **Test Secret Key** обязательны для заполнения. Без их указания тестовый режим работы плагина не поддерживается. 3. Задать параметры использования платёжных методов \([подробнее](ru_cms_bigcommerce.md)\). ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_general.png "Секция с основными параметрами работы плагина в интерфейсе BigCommerce") ### Проведение тестовых оплат {#section_etj_4ts_q5b .section} В рамках работы с плагином можно проводить тестовые оплаты в веб-сервисе и получать информацию о них через интерфейс BigCommerce— в подразделе **View** раздела **Orders**. При этом можно использовать специальные платёжные реквизиты, позволяющие тестировать заданные сценарии работы. Для тестирования карточных платежей по заданным кратчайшим сценариям\(без эмулирования аутентификации 3‑D Secure\) можно использовать следующие номера карт: - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей\(в том числе с аутентификацией 3‑D Secure\), представленных в статье [Номера тестовых карт](ru_test_cards.md). Чтобы тестировать проведение платежей с использованием альтернативных методов\(при подключении соответствующих методов через курирующего менеджера или техническую поддержку\), можно использовать информацию, представленную в статье [Возможности тестирования](ru_pm_testing.md), а также в соответствующих разделах статей о работе с отдельными методами. При работе с двухстадийными оплатами первая стадия, блокировка средств, инициируется пользователем при подтверждении им платежа, а вторая, списание заблокированных средств или отмена блокировки, может инициироваться как автоматически, по истечении установленного срока блокировки, так и по запросу со стороны мерчанта, через интерфейс BigCommerce или интерфейсы платёжной платформы Ecommpay — Dashboard \([подробнее](ru_dbl_payments.md)\) и Gate API \([подробнее](ru_gate_payment_auth.md)\). При этом списывать можно как полную, так и частичную сумму заблокированных средств. Чтобы инициировать вторую стадию через интерфейс BigCommerce, следует: 1. Перейти к реестру заказов в интерфейсе BigCommerce. Для этого следует открыть подраздел **View** раздела **Orders**. 2. Открыть панель с данными о двухстадийной оплате в рамках конкретного заказа. Для этого следует щёлкнуть кнопку ![](images/universal/cms/bigcommerce/icon_dots.png) в столбце **Action** реестра заказов и выбрать пункт Ecommpay в выпадающем списке. 3. Инициировать необходимое действие на панели. Чтобы инициировать списание заблокированных средств, следует указать сумму для списания и щёлкнуть кнопку **Capture** в соответствующей секции. Чтобы отменить блокировку средств, следует щёлкнуть кнопку **Void** в соответствующей секции. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_auth.png "Панель с секциями Capture и Void в реестре заказов интерфейса BigCommerce") Чтобы настроить автоматическое инициирование второй стадии двухстадийных оплат, следует обращаться к специалистам технической поддержки Ecommpay. Вместе с тем, чтобы информация о платежах обновлялась автоматически в интерфейсе BigCommerce при инициировании второй стадии оплаты через интерфейсы платёжной платформы, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на заданный URL. При этом важно, чтобы для одного типа платежа не было настроено несколько правил отправки оповещений с одинаковыми значениями типа событияи кода платёжного метода. Информация о работе с правилами отправки оповещений представлена [в соответствующей статье документации](ru_dbl_projects.md). **Прим.:** В соответствии с требованиями международных платёжных систем на стороне платёжной платформы Ecommpay ограничивается время, на которое могут быть заблокированы средства пользователей \([подробнее](ru_pp_purchase_auth.md#section_cmc_b3s_1mb)\).Если по истечении предельного времени средства не были списаны или их блокировка не была отменена, платёж автоматически отклоняется на стороне платформы. ### Выполнение тестовых возвратов {#section_sfw_tj1_cbc .section} После проведения тестовых оплат можно тестировать выполнение возвратов через интерфейс BigCommerce, и если актуально, через интерфейсы Dashboard и Gate в платформе Ecommpay.При этом следует учитывать, что для выполнения возвратов платежи на стороне платёжной платформы Ecommpay должны быть в статусах `success`, `partially reversed` или `partially refunded`. Контролировать информацию о возвратах можно через интерфейсы платформы и интерфейс BigCommerce\(в реестре заказов\). Чтобы при выполнении тестовых возвратов через интерфейсы платёжной платформы информация о платежах обновлялась автоматически в интерфейсе BigCommerce, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на заданный URL. При этом важно, чтобы для одного типа платежа не было настроено несколько правил отправки оповещений с одинаковыми значениями типа событияи кода платёжного метода.\(URL веб-сервиса отображается на странице с параметрами работы плагина.\) Информация о работе с правилами отправки оповещений представлена [в соответствующей статье документации](ru_dbl_projects.md). Чтобы выполнить возврат через интерфейс BigCommerce, следует: 1. Перейти к реестру заказов в интерфейсе BigCommerce. Для этого следует открыть подраздел **View** раздела **Orders**. 2. Открыть панель с данными о платеже из платёжной платформы. Для этого следует щёлкнуть кнопку ![](images/universal/cms/bigcommerce/icon_dots.png) в столбце **Action** и выбрать пункт **Ecommpay**. 3. Инициировать возврат. Для этого следует указать сумму и причину возврата и щёлкнуть кнопку **Refund** в соответствующей секции. 4. Убедиться в выполнении возврата. Для этого можно проверить, что на панели с данными о платеже обновилась информация о выполненной операции. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_refund.png "Панель с секцией Refund в реестре заказов интерфейса BigCommerce") ## Использование {#ru_cms_bigcommerce_usage} ### Общая информация {#section_zh5_xv1_cbc .section} Для проведения платежей с реальным списанием средств, прежде всего, необходимо решить все организационные вопросы по взаимодействию с Ecommpay\(подать заявку на подключение, предоставить всю необходимую информацию и получить от Ecommpay уведомление о возможности проводить платежи, а также идентификатор и секретный ключ рабочего проекта\). Также необходимосообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина Ecommpay Payments,и валюту проведения платежей. После этого можно перевести плагин в рабочий режим, указать в параметрах его работы полученныеидентификатор и ключ и задать другие необходимые параметры\(или проверить их актуальность для рабочего применения\). Если после этого потребуется приостановить работу плагина, например для тестирования при подключении дополнительных функций, его можно перевести в тестовый режим или отключить от веб-сервиса. **Прим.:** Расширен набор сведений, необходимых для аутентификации 3‑D Secure при проведении карточных оплат. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты. ### Настройка параметров {#section_mkk_dw1_cbc .section} Для подготовки к работе следует *активировать плагин* Ecommpay Payments как вариант оплаты в веб-сервисе и *настроить параметры* его работы.При поддержке группы веб-сервисов это следует делать для каждого веб-сервиса отдельно. При этом следует учитывать, что если плагин был активирован для проведения тестовых оплат, то повторная активация не требуется, но необходимо скорректировать параметры работы плагина \(подробнее [далее](ru_cms_bigcommerce.md#ol_igh_2w1_cbc)\). Чтобы активировать плагин в веб-сервисе, следует: 1. Перейти к параметрам использования вариантов оплаты в интерфейсе BigCommerce. Для этого следует выбрать раздел **Settings** на панели навигации и щёлкнуть строку **Payments** в секции **Setup** на открывшейся странице. 2. Выбрать один из доступных вариантов оплаты для использования плагина. Для этого следует раскрыть блок **Offline Payment Methods** в секции **Additional providers** и щёлкнуть кнопку **Set up** в строке подходящего варианта оплаты \(**Bank Deposit** или иного\). ![](images/universal/cms/bigcommerce/cms_bigcommerce_offline_pm.png "Секция Additional providers в интерфейсе BigCommerce") 3. Указать значение `Ecommpay` в поле **Display Name** на открывшейся странице и сохранить изменение, щёлкнув кнопку **Save**. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings.png "Страница с параметрами работы варианта оплаты в интерфейсе BigCommerce ") Чтобы настроить параметры работы плагина, следует: 1. Перейти к параметрам работы плагина в интерфейсе BigCommerce. Для этого следует выбрать раздел **Apps**, а затем — пункт **Ecommpay Payments** на панели навигации. 2. Проверить корректность и при необходимости скорректировать основные параметры работы плагина: - **Plugin Enabled** — доступность в веб-сервисе\(должна быть включена\). Если этот переключатель включён, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если этот переключатель выключен, то все платёжные методы, подключённые для работы через плагин, становятся недоступными для проведения платежей. - **Store Channel** — название веб-сервиса мерчанта в платформе BigCommerce \(должен быть выбран веб-сервис, для которого задаются параметры работы плагина\). - **Mode** — режим работы плагина\(должен быть выбран вариант **live**\). - **Project ID** — идентификатор рабочего проекта для взаимодействия с платформой\(должен соответствовать полученному от Ecommpay\). - **Secret Key** — ключ рабочего проекта\(должен соответствовать полученному от Ecommpay\). - **Merchant Callback Url** — URL для приёма на стороне плагина оповещений от платёжной платформы\(формируется и подставляется автоматически при установке плагина Ecommpay Payments\). - **Host Url** — доменное имя веб-сервиса мерчанта, для которого задаются параметры работы плагина \(должно быть указано вручную\). - **Payment Mode** — вариант проведения оплат через платёжную платформу. Можно выбрать один из следующих вариантов: - **Sale** — в одну стадию \(с незамедлительным списанием средств\); - **Authorization Only** — в две стадии \(с предварительной блокировкой и последующим списанием средств\). Первый вариант доступен для всех платёжных методов, подключённых для работы через плагин, а второй вариант — только для тех методов, для которых поддерживаются оплаты в две стадии \(таких как карточные платежи и методы Apple Pay и Google Pay\). 3. Задать параметры использования платёжных методов \([подробнее](ru_cms_bigcommerce.md)\). ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_general_live.png "Секция с основными параметрами работы плагина в интерфейсе BigCommerce") ### Выполнение возвратов {#section_my1_5x1_cbc .section} По оплатам, проведённым с помощью плагина Ecommpay Payments, можно выполнять частичные и полные возвраты через интерфейс BigCommerce, и если актуально, через интерфейсы Dashboard\(с использованием инструментов единичной и пакетной отправки запросов; [подробнее](ru_dbl_payments.md)\) и Gate\([подробнее](ru_Gate_Refund.md)\) от Ecommpay. При этом платежи на стороне платформы Ecommpay должны быть в статусах `success`, `partially reversed` или `partially refunded`.После выполнения возвратов всю актуальную информацию о платежах можно контролировать через интерфейс BigCommerce и интерфейсы платёжной платформы. **Внимание:** Чтобы при выполнении возвратов через интерфейсы платёжной платформы информация о платежах обновлялась автоматически в интерфейсе BigCommerce, необходимо убедиться, что для используемого проекта была настроена отправка оповещений от платёжной платформы на заданный URL. При этом важно, чтобы для одного типа платежа не было настроено несколько правил отправки оповещений с одинаковыми значениями типа событияи кода платёжного метода. Информация о работе с правилами отправки оповещений представлена [в соответствующей статье документации](ru_dbl_projects.md). Чтобы выполнить возврат через интерфейс BigCommerce, следует: 1. Перейти к реестру заказов в интерфейсе BigCommerce. Для этого следует открыть подраздел **View** раздела **Orders**. 2. Открыть панель с данными о платеже из платёжной платформы. Для этого следует щёлкнуть кнопку ![](images/universal/cms/bigcommerce/icon_dots.png) в столбце **Action** и выбрать пункт **Ecommpay**. 3. Инициировать возврат. Для этого следует указать сумму и причину возврата и щёлкнуть кнопку **Refund** в соответствующей секции. 4. Убедиться в выполнении возврата. Для этого можно проверить, что на панели с данными о платеже обновилась информация о выполненной операции. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_refund.png "Панель с секцией Refund в реестре заказов интерфейса BigCommerce") ### Контроль платежей и заказов {#section_zhp_ty1_cbc .section} Контролировать информацию о платежах, проводимых с помощью плагина Ecommpay Payments, а также о соответствующих заказах можно через интерфейс BigCommerce, используя инструменты подраздела **View** в разделе **Orders**. Также для получения информации можно использовать интерфейс Dashboard от Ecommpay \([подробнее](ru_dbl_payments.md)\), в котором доступна информация о платежах и возвратах, проводимых через платформу Ecommpay, но не отображается информация о заказах. В подразделе **View** раздела **Orders** отображается реестр заказов с информацией о каждом из них. Наряду с этим в реестре доступны различные функции для работы с заказами, в том числе через него можно выполнять поиск и фильтрацию заказов, а также получать информацию о платежах в рамках отдельных заказов. ![](images/universal/cms/bigcommerce/cms_bigcommerce_orders.png "Реестр заказов в интерфейсе BigCommerce") Для получения развёрнутых сведений о конкретном заказе можно щёлкнуть кнопку ![](images/universal/cms/bigcommerce/icon_plus.png) в соответствующем столбце реестра. В раскрывающемся блоке отображается такая информация, как расчётный адрес пользователя, дата создания и сумма заказа и другие сведения. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_order_details.png "Раскрывающийся блок с информацией о заказе в интерфейсе BigCommerce") В секции **Billing** раскрывающегося блока отображается название организации, через которую проводится платёж, с названием платёжного метода \(в поле с иконкой ![](images/universal/cms/bigcommerce/icon_method.png)\) и идентификатор платежа \(в поле с иконкой ![](images/universal/cms/bigcommerce/icon_id.png)\). Для получения более детальной информации о платеже следует щёлкнуть кнопку ![](images/universal/cms/bigcommerce/icon_dots.png) в столбце **Action** и пункт Ecommpay в выпадающем списке. На открывшейся панели отображается секция **Order Details** с информацией о платеже и могут отображаться следующие секции \(если соответствующие функции доступны в рамках выбранного заказа\): - **Capture** — с возможностью инициировать списание заблокированных средств в рамках двухстадийной оплаты; - **Void** — с возможность отменить блокировку средств в рамках двухстадийной оплаты; - **Refund** — с возможностью инициировать возврат средств в рамках оплаты. ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_info_payment.png "Панель с секцией Order Details в интерфейсе BigCommerce") Более подробная информация о работе с заказами в интерфейсе BigCommerce представлена [в документации BigCommerce](https://support.bigcommerce.com/s/article/Orders?language=en_US). ## Параметры использования платёжных методов {#ru_cms_bigcommerce_methods} При работе с плагином Ecommpay Payments в интерфейсе BigCommerce можно настраивать использование различных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать через отдельные раскрывающиеся блоки на странице с параметрами работы плагина— такие как **Card Payments** \(с параметрами для карточных платежей\), **Alternative payment settings** \(со списком раскрывающихся блоков с параметрами для разных альтернативных методов\) или **More payment methods** \(с параметрами для полной группы методов, подключённых в проекте\). **Прим.:** Блоки с параметрами, отображаемые по умолчанию, исключить из параметров работы плагина нельзя, даже если соответствующие методы не используются в проекте. Если актуально работать с другими методами, их использование в плагине можно настраивать только через раскрывающийся блок **More payment methods** \(в блоке **Alternative payment settings**\), предварительно обратившись к специалистам технической поддержки Ecommpay для подключения методов в проекте. В раскрывающихся блоках можно задавать следующие параметры использования платёжных методов: - **Enabled** — возможность подключения платёжного метода для работы через плагин. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе. - **Display mode** — способ открытия платёжной формы Payment Page. Этот параметр отображается только в блоке для карточных платежей. В нём можно выбрать значение **Embedded** или **Redirected** для открытия формы в элементе iframe или в виде отдельной HTML-страницы соответственно. При выборе значения **Embedded** параметры **Description** и **Show Description** в блоке для карточных платежей не отображаются. - **Description** — текст, отображаемый пользователям при выборе платёжного метода. - **Show Description** — возможность отображения текста из параметра **Description**. - **Payment method code** — код платёжного метода, используемого как единственный дополнительный \(по отношению к методам, для настройки работы с которыми применяются отдельные раскрывающиеся блоки\). Этот параметр отображается только в блоке **More payment methods**. - Если не применять этот параметр, то при выборе метода оплаты в интерфейсе веб-сервиса пользователь может выбрать вариант **More payment methods** и перейти к платёжной форме с возможностью выбрать там один из методов, доступных для инициируемого платежа через платформу Ecommpay.При этом все методы от Ecommpay, доступные для выбора непосредственно в веб-сервисе \(наряду с вариантом **More payment methods**\), оказываются доступными и в платёжной форме. - Если указать в значении этого параметра код одного из доступных методов\(в соответствии [со справочником](ru_pm_codes.md)\), то при выборе методов оплаты в интерфейсе веб-сервиса наряду с другими доступными там для выбора методами пользователь может выбрать указанный и перейти к работе с ним, минуя выбор каких-либо других методов в платёжной форме.Чтобы не допускать коллизий с таким выбором, при указании кода какого-либо метода в этом разделе также следует указывать название этого метода для отображения в веб-сервисе \(в поле **Title**\). ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings_card.png "Раскрывающийся блок с параметрами для карточных платежей в интерфейсе BigCommerce") ![](images/ecommpay/cms/bigcommerce/cms_bigcommerce_settings_apay.png "Раскрывающийся блок с параметрами для метода Apple Pay в интерфейсе BigCommerce") --- # Использование плагина от Ecommpay для commercetools {#ru_cms_commercetools} статья о порядке применения плагина для встраивания Payment Page в сайты на базе платформы commercetools **На уровень выше:**[Интеграция с использованием плагинов](ru_CMS.md) ## Введение {#ru_cms_commercetools_overview} В этой статье представлена информация о работе с платёжным плагином от Ecommpay для платформы commercetools. Плагин описываемой версии 1.0 может использоваться в веб-сервисах, в работе которых применяется решение Composable Commerce от commercetools. Плагин от Ecommpay устанавливается на локальном сервере мерчанта или в стороннем облачном сервисе \(в таком как AWS Lambda, Azure Functions или Google Cloud Functions\). С помощью этого плагина выполняется автоматическое формирование URL для вызова со стороны веб-сервиса платёжной формы Payment Page и обеспечиваются необходимые действия для проведения платежей, как в части взаимодействия с пользователями, так и в части взаимодействия с платёжной платформой Ecommpay. Работа плагинаот Ecommpay основывается на использовании двух модулей, реализованных по модели FaaS \(Function-as-a-Service\): модуля расширения— для приёма запросов от платформы commercetools — и модуля уведомлений— для передачи информации об оплатах, проводимых в платёжной платформе, к платформе commercetools. ## Общая информация {#ru_cms_commercetools_general} ### Возможности {#section_fbw_hjv_szb .section} При использовании плагина от Ecommpay можно: - Встраивать в веб-сервис возможность вызова платёжной формы Payment Page от Ecommpay. Для этого следует установить плагин и настроить вызов платёжной формы Payment Page в клиентской части веб-сервиса. Также, если актуально, можно настроить применение дополнительных параметров вызова формы и проведения платежей \([подробнее](ru_PP_Parameters.md)\). - Тестировать работу платёжной формы и возможности проведения платежей. Для этого следует оформить тестовый проект в платёжной платформе Ecommpay \(что можно сделать [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\). - Проводить разовые одностадийные оплаты с применением различных платёжных методов. При этом для подключения отдельных платёжных методов следует обращаться к специалистам технической поддержки Ecommpay, а все организационные вопросы можно решать через курирующего менеджера Ecommpay. - Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина. Для этого можно использовать HTTP API платформы commercetools и, если актуально, интерфейсы платёжной платформы Ecommpay \(пользовательский интерфейс Dashboard и Gate API\). Вместе с тем, при использовании интерфейсов платёжной платформы Ecommpay информация о платежах в платформе commercetools обновляется, только если настроена отправка оповещений со стороны платёжной платформы \([подробнее](ru_dbl_projects.md)\). - Контролировать информацию о платежах, проводимых с помощью плагина. Это можно делать через HTTP API и пользовательский интерфейс Merchant Center от commercetools и, если актуально, — через Data API и пользовательский интерфейс Dashboard от Ecommpay. - Управлять заказами, оплаты по которым проводятся с помощью плагина, через интерфейс Merchant Center и HTTP API от commercetools. При этом можно отменять такие заказы и корректировать их статусы вручную. Также следует учитывать, что автоматическое изменение статусов заказов при работе с плагином от Ecommpay не предусмотрено, но может быть настроено специалистами мерчанта с использованием возможностей, предоставляемых в рамках решения Composable Commerce платформы commercetools. - Применять различные возможности, обеспечиваемые со стороны Ecommpay. В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking, делать доступными для пользователей повторные попытки оплаты \([подробнее](ru_PP_Try_Again.md)\) и подключать отправку пользователям уведомлений о результатах оплат \([подробнее](ru_PP_receipt_data.md)\). Для подключения этих возможностей следует обращаться к специалистам технической поддержки Ecommpay. Такой спектр возможностей позволяет подстраиваться под различные особенности бизнеса, гибко настраивать пользовательские сценарии и обеспечивать высокий уровень конверсии платёжной формы и проходимости платежей. Для подключения и применения возможностей, предоставляемых Ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам Ecommpay. ### Схема работы {#section_wqc_ssv_szb .section} В схеме проведения оплат с использованием плагина от Ecommpay для платформы commercetools задействуются пользователь, веб-сервис со встроенным в него плагином, взаимодействующий с платформой commercetools, платёжная форма Payment Page, платёжная платформа Ecommpay и платёжная среда. При этом с помощью плагина на стороне веб-сервиса обеспечиваются автоматическое формирование URL для открытия Payment Page и автоматическое обновление информации в рамках платежей в платформе commercetools. ![](images/universal/cms/ru_cms_workflow.svg) 1. Пользователь на стороне веб-сервиса переходит к проведению оплаты с использованием плагина от Ecommpay. При этом в платформу commercetools направляется запрос на создание платежа и с помощью расширения API осуществляется обращение к модулю расширения от Ecommpay. С помощью этого модуля формируется URL для открытия Payment Page, после чего из платформы commercetools к веб-сервису направляется ответ с указанием URL и информации о платеже, созданном на стороне платформы commercetools. 2. На стороне веб-сервиса формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Page. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платёжной платформе выполняется обработка запроса, с проверкой его корректности. 5. В платёжной платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает итоговый запрос на оплату \(со всеми необходимыми сведениями\). 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью модуля уведомлений, благодаря чему в платформе commercetools обновляется информация о состоянии платежа и появляется информации об оплате, инициированной в платёжной платформе. 13. От платёжной платформы к Payment Page направляется информация о результате оплаты. 14. Информация о результате оплаты отображается пользователю в веб-сервисе мерчанта \(если настроено автоматическое [итоговое возвращение пользователя к веб-сервису](ru_PP_redirect_modes.md)\) или в платёжной форме Payment Page \(если настроено итоговое возвращение к веб-сервису по решению пользователя или итоговое возвращение не используется\). В рамках представленной общей схемы пользователь сначала подтверждает формирование заказа и платежа в платформе commercetools на странице перехода к оплате в веб-сервисе, а затем указывает необходимые данные в открывшейся платёжной форме и подтверждает формирование оплаты в платформе Ecommpay\(с помощью кнопки **Оплатить**\). При этом сначала в рамках платежа на стороне платформы commercetools создаётся транзакция типа `Charge`, а затем для этой транзакции в рамках оплаты на стороне платформы Ecommpay инициируется операция типа `sale`.Исключением являются случаи, когда пользователь подтверждает формирование заказа и платежа в веб-сервисе, но не подтверждает формирование оплаты в платёжной форме Payment Page, — в такой ситуации в платформе commercetools создаётся транзакция типа `Charge` в статусе `Initial`, но оплата на стороне Ecommpay не инициируется. Статусы транзакций в платформе commercetools изменяются автоматически в соответствии с документацией commercetools \([подробнее](https://docs.commercetools.com/api/projects/payments#transactionstate)\) и в зависимости от изменений статусов операций в платформе Ecommpay. Однако статусы заказов и платежей, формируемых в платформе commercetools при работе с плагином от Ecommpay, по умолчанию не изменяются.При создании заказа ему присваивается статус `Open`, а платежу в рамках этого заказа статус не присваивается, но в обоих случаях эти параметры можно задавать вручную и настроить их автоматическое изменение, используя инструменты и возможности commercetools. Наряду с этим, заказам, платежам и транзакциям на стороне платформы commercetools автоматически присваиваются идентификаторы, состоящие из тридцати двух случайных символов, а оплатам в платформе Ecommpay — идентификаторы, соответствующие идентификаторам платежей в платформе commercetools\(например, `eeb30cda-a8a1-4895-ab43-5ef8bb29ee80`\), и статусы в соответствии с моделью проведения платежей Ecommpay \([подробнее](ru_platform_payment_model.md)\).С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру Ecommpay. ## Установка {#ru_cms_commercetools_installation} Чтобы начать работу с плагином от Ecommpay версии 1.0, необходимо: 1. Создать учётную запись \([API client](https://docs.commercetools.com/api/projects/api-clients)\) с доступом к следующим возможностям \([scopes](https://docs.commercetools.com/api/scopes)\) в рамках проекта в платформе commercetools: - Управление платежами; - Управление наборами дополнительных полей \([custom types](https://docs.commercetools.com/api/projects/types)\). После этого мерчанту разово предоставляется доступ к данным о созданной учётной записи,указываемым в параметрах `project_key`, `client_id`, `secret`, `scope`, `API URL` и `Auth URL`. Эти данные следует сохранить для последующей работы с плагином в рамках созданной учётной записи. 2. Установить модули плагина в используемой средев соответствии с одной из инструкций, [на портале GitHub](https://github.com/ITECOMMPAY/ecommpay-commercetools-integration). 3. Создать наборы дополнительных полей \(custom types\) для указания в этих полях информации о платежах, инициируемых в платёжной платформе Ecommpay. Для этого в платформу commercetools следует направить соответствующие запросы с указанием идентификаторов сущностей `payment-interface-interaction` и `payment`. ```language-json { "key": "ecommpay-integration-interaction-payment-type", "name": { "en": "commercetools ecommpay integration payment interface interaction type" }, "resourceTypeIds": ["payment-interface-interaction"], "fieldDefinitions": [ { "name": "operation_id", "label": { "en": "Operation id" }, "required": false, "type": { "name": "Number" }, "inputHint": "SingleLine" }, { "name": "operation_type", "label": { "en": "Operation type" }, "required": false, "type": { "name": "String" }, "inputHint": "SingleLine" }, { "name": "operation_status", "label": { "en": "Operation status" }, "required": false, "type": { "name": "String" }, "inputHint": "SingleLine" }, { "name": "date", "label": { "en": "Date" }, "required": false, "type": { "name": "DateTime" }, "inputHint": "SingleLine" }, { "name": "sum_initial", "label": { "en": "Sum initial" }, "required": false, "type": { "name": "String" }, "inputHint": "SingleLine" }, { "name": "sum_converted", "label": { "en": "Sum converted" }, "required": false, "type": { "name": "String" }, "inputHint": "SingleLine" }, { "name": "message", "label": { "en": "Message" }, "required": false, "type": { "name": "String" }, "inputHint": "SingleLine" } ] } ``` В результате выполнения такого запроса в платформе commercetools создаются поля для указании информации об операциях, передаваемой в оповещениях от платёжной платформы.Эти поля отображаются в карточках заказов интерфейса Merchant Center \(на странице с данными об операциях из платёжной платформы\), а также включаются в ответы на запросы информации о платежах, отправляемые с использованием HTTP API. ```language-json { "key": "ecommpay-integration", "name": { "en": "commercetools ecommpay integration" }, "resourceTypeIds": ["payment"], "fieldDefinitions": [ { "name": "initial_request", "label": { "en": "Initial request" }, "type": { "name": "String" }, "inputHint": "SingleLine", "required": false }, { "name": "pp_url", "label": { "en": "Payment Page URL" }, "type": { "name": "String" }, "inputHint": "SingleLine", "required": false } ] } ``` В результате выполнения такого запроса в платформе commercetools создаются поля**Initial request** и **Payment Page****URL** — для указания дополнительных параметров открытия Payment Page и для указания URL для открытия платёжной формысоответственно. Поле **Initial request** может использоваться в запросах на инициирование платежей, отправляемых в платформу commercetools, а также, наряду с параметром для указания URL, отображается в карточках заказов интерфейса Merchant Center \(в секции **commercetools Ecommpay integration**\) и включаются в ответы на запросы информации о платежах, отправляемые с использованием HTTP API от commercetools. 4. Создать расширение API \([API extension](https://docs.commercetools.com/api/projects/api-extensions#create-extension)\) для взаимодействия платформы commercetools с плагином от Ecommpay. Для этого в платформу commercetools следует направить соответствующий запрос с указанием в объекте `destination` URL модуля расширения от Ecommpay. ```language-json { "key": "ecommpay-integration-payment-extension", "destination": { "type": "HTTP", "url": "" // URL модуля расширения от Ecommpay }, "triggers": [ { "resourceTypeId": "payment", "actions": ["Create","Update"], "condition": "paymentMethodInfo is defined AND paymentMethodInfo(paymentInterface is defined) AND paymentMethodInfo(paymentInterface=\"ecommpay-integration\")" } ], "timeoutInMs": 10000 ``` ## Тестирование {#ru_cms_commercetools_testing} ### Общая информация {#ru_cms_commercetools_testing_overview} Тестировать работу плагина и проводить тестовые платежи по различным платёжным сценариямбез реального списания средств можно через тестовую среду платёжной платформы Ecommpay. Подключиться к платформе можно, используя соответствующую форму [на основном сайте компании](https://ecommpay.com/apply-now/) иполученные идентификатор и ключ тестового проекта. Также необходимо сообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина от Ecommpay, и валюту проведения платежей. Наряду с этим следует учитывать, что при работе с плагином от Ecommpay для платформы commercetools вызов Payment Page обеспечивается на стороне веб-сервиса с учётом параметров, включённых в URL для открытия Payment Page.Если необходимо использовать дополнительные [параметры вызова платёжной формы](ru_PP_Parameters.md), их следует передать в запросе, отправляемом в платформу commercetools для инициирования платежа, — в параметре `initial_request` в объекте `fields` внутри объекта `custom`. Информация об организации работы с платёжной формой Payment Page представлена [в соответствующей статье этого портала](ru_pp_interaction_organisation.md). ```language-json { "amountPlanned": { "currencyCode": "EUR", "centAmount": 1000 }, "paymentMethodInfo": { "paymentInterface": "ecommpay-integration", "method": "ecommpay-integration" }, "custom": { "type": { "typeId": "type", "key": "ecommpay-integration" }, "fields": { "initial_request": "\"{\\\"customer_id\\\":123,\\\"billing_country\\\":\\\"DE\\\",\\\"customer_country\\\":\\\"DE\\\"}\"" } } } ``` ### Проведение тестовых оплат {#ru_cms_commercetools_testing_purchase} В рамках работы с плагином можно проводить тестовые оплаты в веб-сервисе и получать базовые сведения о них через интерфейс Merchant Center и через HTTP API от commercetools.При этом можно использовать специальные платёжные реквизиты, позволяющие тестировать заданные сценарии работы. Чтобы тестировать проведение карточных платежей, можно использовать номера тестовых карт. При этом для тестирования по заданным кратчайшим сценариям\(без эмулирования аутентификации 3‑D Secure\) можно использовать следующие номера карт: - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей\(в том числе с аутентификацией 3‑D Secure\), представленных в статье [Номера тестовых карт](ru_test_cards.md). Чтобы тестировать проведение платежей с использованием альтернативных методов, можно использовать информацию, представленную в статье [Возможности тестирования](ru_pm_testing.md), а также в соответствующих разделах статей о работе с отдельными методами. ### Выполнение тестовых возвратов {#ru_cms_commercetools_testing_refund} #### Введение {#section_k1j_3bk_kbc .section} После проведения тестовых оплат можно тестировать выполнение возвратовчерез HTTP API от commercetools, и если актуально, через интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом можно учитывать, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочей среде. #### Обеспечение синхронизации данных между платформами {#section_wnj_kbk_kbc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о платежах в платформе commercetools обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о платежах через интерфейсы платформы commercetools, важно обеспечить отправку и приём оповещений для автоматического обновления информации в платформе commercetools. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к модулю уведомлений плагина, на URL, указанный при установке плагина в качестве переменной среды для модуля расширения. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. В ином случае в протоколах работы среды, в которой установлен плагин, при обновлении информации о платеже в платформе commercetools могут возникать ошибки. - На стороне веб-сервиса обеспечена доступность URL, используемого для получения оповещений со стороны платёжной платформы, IP-адреса Ecommpay добавлены в список доверенных и оповещения не блокируются на уровне межсетевых экранов или других сетевых устройств. Это может быть актуальным, в частности, при работе с платформами Docker и Node.js. #### Процедуры {#section_efy_1ck_kbc .section} Выполнять возвраты можно для тех оплат, которые были проведены и по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформ Ecommpay и commercetools. Чтобы выполнить возврат через HTTP API платформы commercetools, следует направить соответствующий запрос на обновление информации о платеже \([подробнее](https://docs.commercetools.com/api/projects/payments#update-payment)\). При этом в запросе следует передать массив `actions` со следующими данными: - Параметр `action` с названием действия, которое необходимо выполнить в рамках платежа. Для инициирования возврата следует указать значение `addTransaction`. - Объект `transaction` со следующими данными: - Параметр `type` с типом транзакции в платформе commercetools. Для инициирования возврата следует указать значение `Refund`. - Объект `amount` с параметрами `currencyCode` и `centAmount`, в которых следует указать валюту и сумму возврата соответственно. Для выполнения частичного возврата можно указать сумму, не превышающую актуальную сумму платежа. ```language-json "actions": [ { "action": "addTransaction", "transaction": { "type": "Refund", "amount": { "centAmount": 8300, "currencyCode": "EUR" } } } ] ``` Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ## Использование {#ru_cms_commercetools_usage} ### Общая информация {#ru_cms_commercetools_usage_overview} Для проведения платежей с реальным списанием средств, прежде всего, необходимо решить все организационные вопросы по взаимодействию с Ecommpay\(подать заявку на подключение, предоставить всю необходимую информацию и получить от Ecommpay уведомление о возможности проводить платежи, а также идентификатор и секретный ключ рабочего проекта\). Также необходимо сообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина от Ecommpay, и валюту проведения платежей. Наряду с этим, следует учитывать, что при работе с плагином от Ecommpay для платформы commercetools вызов Payment Page обеспечивается на стороне веб-сервиса с учётом параметров, включённых в URL для открытия Payment Page.Если необходимо использовать дополнительные [параметры вызова платёжной формы](ru_PP_Parameters.md), их следует передать в запросе, отправляемом в платформу commercetools для инициирования платежа, — в параметре `initial_request` в объекте `fields` внутри объекта `custom`. Информация об организации работы с платёжной формой Payment Page представлена [в соответствующей статье этого портала](ru_pp_interaction_organisation.md). **Прим.:** Расширен набор сведений, необходимых для аутентификации 3‑D Secure при проведении карточных оплат. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты. После решения всех организационных и технических вопросов можно указать полученные идентификатор и ключ рабочего проекта в значениях переменных среды, в которой были установлены модули плагина, и приступить к использованию плагина в рабочих целях. Если после этого потребуется приостановить работу плагина, можно отключить возможность проводить оплаты с использованием плагина от Ecommpay в веб-сервисе, удалить модули плагина из используемой среды или остановить работу этой среды. ### Выполнение возвратов {#ru_cms_commercetools_usage_refund} #### Введение {#section_iss_drm_vzb .section} После проведения оплат можно выполнять возвраты по нимчерез HTTP API от commercetools, и если актуально, через интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом все возможности и процедуры по работе с возвратами в рабочей среде соответствуют тем, которые доступны в тестовой среде. #### Обеспечение синхронизации данных между платформами {#section_xc4_dgk_kbc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о платежах в платформе commercetools обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о платежах через интерфейсы платформы commercetools, важно обеспечить отправку и приём оповещений для автоматического обновления информации в платформе commercetools. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к модулю уведомлений плагина, на URL, указанный при установке плагина в качестве переменной среды для модуля расширения. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. В ином случае в протоколах работы среды, в которой установлен плагин, при обновлении информации о платеже в платформе commercetools могут возникать ошибки. - На стороне веб-сервиса обеспечена доступность URL, используемого для получения оповещений со стороны платёжной платформы, IP-адреса Ecommpay добавлены в список доверенных и оповещения не блокируются на уровне межсетевых экранов или других сетевых устройств. Это может быть актуальным, в частности, при работе с платформами Docker и Node.js. #### Процедуры {#section_f1c_hgk_kbc .section} Выполнять возвраты можно для тех оплат, которые были проведены и по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформ Ecommpay и commercetools. Чтобы выполнить возврат через HTTP API платформы commercetools, следует направить соответствующий запрос на обновление информации о платеже \([подробнее](https://docs.commercetools.com/api/projects/payments#update-payment)\). При этом в запросе следует передать массив `actions` со следующими данными: - Параметр `action` с названием действия, которое необходимо выполнить в рамках платежа. Для инициирования возврата следует указать значение `addTransaction`. - Объект `transaction` со следующими данными: - Параметр `type` с типом транзакции в платформе commercetools. Для инициирования возврата следует указать значение `Refund`. - Объект `amount` с параметрами `currencyCode` и `centAmount`, в которых следует указать валюту и сумму возврата соответственно. Для выполнения частичного возврата можно указать сумму, не превышающую актуальную сумму платежа. ```language-json "actions": [ { "action": "addTransaction", "transaction": { "type": "Refund", "amount": { "centAmount": 8300, "currencyCode": "EUR" } } } ] ``` Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ### Контроль платежей и заказов {#ru_cms_commercetools_usage_monitoring} Контролировать информацию о платежах, проводимых с помощью плагина от Ecommpay, а также о соответствующих заказах можно через интерфейс Merchant Center и HTTP API от commercetools. Также при необходимости можно использовать интерфейсы Dashboard и Data API от Ecommpay, но следует учитывать, что в этом случае можно получать информацию только о платежах, инициируемых в платёжной платформе. При работе с интерфейсом Merchant Center в разделе **Orders** отображается реестр заказов с основными сведениями о каждом из них, а также с возможностями поиска, фильтрации и перехода к карточкам отдельных заказов. ![](images/universal/cms/commercetools/cms_commercetools_orders.png "Реестр заказов в интерфейсе Merchant Center") Для перехода к карточке конкретного заказа можно щёлкнуть его строку в реестре. В карточках на отдельных вкладках отображаются развёрнутые сведения о заказах и платежах, включая дату создания заказа, его сумму и статус и другую информацию. При работе с плагином от Ecommpay актуально использование следующих вкладок: - **General** — с информацией о заказе и расчётном адресе пользователя; - **Custom Fields** — с набором дополнительных полей, используемых в рамках заказа; - **Shipping & Delivery** — с информацией о способе доставки товаров; - **Returns** — с информацией о возврате товаров; - **Payments** — с информацией о платежах и транзакциях в рамках заказа. Для получения информации о платеже, проведённом через плагин от Ecommpay, следует перейти на вкладку **Payments**. На этой вкладке отображается код платёжного метода\(в параметре **Payment method name**\), название способа оплаты\(в параметре **Payment method**\), сумма и валюта платежа\(в параметре **Amount planned**\), статус, присвоенный платежу в платформе Ecommpay,\(в параметре **PSP Status Code**\) и другие сведения. ![](images/ecommpay/cms/commercetools/cms_commercetools_order.png "Карточка заказа в интерфейсе Merchant Center") В таблице **Payment transactions** отображается информация о транзакциях в платформе commercetools. Эта таблица состоит из следующих столбцов: - **Date** — дата создания транзакции; - **Transaction type** — тип транзакции\(`Charge` для операции типа `sale` и `Refund` для операции типа `refund` или `reversal`\); - **Status** — статус транзакции; - **Amount** — сумма и валюта транзакции; - **Interaction ID** — идентификатор операции, относящейся к конкретной транзакции, присвоенный на стороне Ecommpay; - **Transaction ID** — идентификатор транзакции. Статус каждой транзакции в платформе commercetools зависит от состояния соответствующей операции в платформе Ecommpay.Так, транзакциям присваиваются следующие статусы: - `Initial`, если оповещение с информацией о соответствующей операции ещё не поступило в платформу commercetools; - `Pending`, если операция находится в промежуточном статусе; - `Successful`, если операция выполнена; - `Failure`, если операция отклонена. ![](images/ecommpay/cms/commercetools/cms_commercetools_order_table.png "Таблица с данными о транзакциях в карточке заказа интерфейса Merchant Center") Для получения информации об операциях, инициированных в платформе Ecommpay, следует щёлкнуть ссылку **View PSP transaction log**, в результате чего открывается страница с данными обо всех операциях в рамках конкретного платежа.Эти данные передаются в оповещениях от платёжной платформы и сохраняются в полях, созданных на этапе установки плагина. ![](images/universal/cms/commercetools/cms_commercetools_callback_data.png "Страница с данными об операциях из оповещений от платёжной платформы") При работе через HTTP API, чтобы получить информацию о платеже, следует направить соответствующий запрос в платформу commercetools \([подробнее](https://docs.commercetools.com/api/projects/payments#get-payment)\).Данные о платеже из платформы Ecommpay в ответе на такой запрос указываются в дополнительных полях, созданных при установке плагина. ```language-json { "id": "7c081cc3-353d-4a80-8879-36e2f7dc5ac4", "version": 15, "versionModifiedAt": "2023-12-19T11:47:37.374Z", "lastMessageSequenceNumber": 10, "createdAt": "2023-12-19T11:27:56.278Z", "lastModifiedAt": "2023-12-19T11:47:37.374Z", "lastModifiedBy": { "clientId": "4cD5VUC9rScyTo69eOueu6Jh", "isPlatformClient": false }, "createdBy": { "clientId": "4cD5VUC9rScyTo69eOueu6Jh", "isPlatformClient": false, "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902" }, "amountPlanned": { "type": "centPrecision", "currencyCode": "EUR", "centAmount": 12300, "fractionDigits": 2 }, "paymentMethodInfo": { "paymentInterface": "ecommpay-integration", "method": "ecommpay-integration", "name": { "en": "card" } }, "custom": { "type": { "typeId": "type", "id": "62408c35-a8b1-4bd0-9c15-99aa86cf8efc" }, "fields": { "initial_request": "{\"redirect_success_url\":\"https://example.com/complete-redirect?id=success\"...}", "pp_url": "https://paymentpage.ecommpay.com/payment?project_id=109751&interface_type=33..." } }, "paymentStatus": { "interfaceCode": "success" }, "transactions": [ { "id": "a503a5e0-9677-46d8-bab2-2dbbb10595ce", "timestamp": "2023-12-19T11:27:56.272Z", "type": "Charge", "amount": { "type": "centPrecision", "currencyCode": "EUR", "centAmount": 12300, "fractionDigits": 2 }, "interactionId": "47382010085133", "state": "Success" }, { "id": "424ca2fd-0d31-475c-98f1-0f945a30a9ef", "type": "Refund", "amount": { "type": "centPrecision", "currencyCode": "EUR", "centAmount": 8300, "fractionDigits": 2 }, "interactionId": "0", "state": "Initial" } ], "interfaceInteractions": [ { "type": { "typeId": "type", "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86" }, "fields": { "operation_type": "sale", "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}", "date": "2023-12-19T11:47:18+0000", "operation_id": 47382010085133, "operation_status": "awaiting 3ds result", "message": "Awaiting processing", "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}" } }, { "type": { "typeId": "type", "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86" }, "fields": { "operation_type": "sale", "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}", "date": "2023-12-19T11:47:25+0000", "operation_id": 47382010085133, "operation_status": "awaiting 3ds result", "message": "Awaiting processing", "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}" } }, { "type": { "typeId": "type", "id": "8978cfd5-fb49-4082-a4cf-2e49237e1c86" }, "fields": { "operation_type": "sale", "sum_initial": "{\"amount\":12300,\"currency\":\"EUR\"}", "date": "2023-12-19T11:47:35+0000", "operation_id": 47382010085133, "operation_status": "success", "message": "Success", "sum_converted": "{\"amount\":10592,\"currency\":\"GBP\"}" } } ], "anonymousId": "f661235a-abf9-4ec6-915a-e7c4b3154902" } } } ``` Более подробная информация о работе с платежами и заказами с использованием инструментов платформы commercetools представлена [в документации commercetools](https://docs.commercetools.com/docs/composable-commerce). --- # Использование плагина от Ecommpay для CMS Magento {#ru_CMS__magento} статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS Magento **На уровень выше:**[Интеграция с использованием плагинов](ru_CMS.md) ## Введение {#ru_cms_magento_overview} В этой статье представлена информация о работе с платёжным плагином от Ecommpayверсии2.1.6. Он может использоваться в веб-сервисах, разработанных на базе CMS Magento версии 2.2 и выше. **Прим.:** В документации Magento и Hyvä для обозначения плагинов используется термин *modules*. Плагин от Ecommpay позволяет открывать пользователям платёжную форму Payment Page от Ecommpay и обеспечивать все необходимые действия для проведения платежей, как в части взаимодействия с пользователями, так и в части взаимодействия с платёжной платформой Ecommpay, с передачей и приёмом всей необходимой информации. ![](images/ecommpay/cms/magento/cms_magento_methods.png "Административный интерфейс Magento") ![](images/ecommpay/cms/magento/cms_magento_pp_embedded_glr.png "Интерфейс платёжной формы Payment Page на странице веб-сервиса") ## Общая информация {#ru_cms_magento_general} ### Возможности {#section_ebc_2yf_2yb .section} При использовании плагина от Ecommpay можно: - Встраивать в веб-сервис возможность вызова платёжной формы Payment Page от Ecommpay. Для этого достаточно установить плагин от Ecommpay и настроить его использование через интерфейс Magento. - Настраивать использование отдельных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать непосредственно через соответствующие раскрывающиеся блоки в интерфейсе Magento. Технически для подключения отдельных платёжных методов может быть достаточно минимальных действий в интерфейсе Magento либо не требоваться никаких действий вовсе, а все организационные вопросы можно решать через курирующего менеджера Ecommpay. - Настраивать оформление веб-сервиса с использованием тем оформления от Hyvä Themes и со встраиванием платёжной формы Payment Page от Ecommpay на страницу формирования заказов Hyvä Checkout. Для этого достаточно установить необходимые плагины в дополнение к плагину от Ecommpay и настроить их использование через интерфейс Magento. - Тестировать работу платёжной формы и возможности проведения платежей. При этом для начального тестирования достаточно тестового режима работы плагина \(без каких-либо дополнительных действий\), а для более глубокого тестирования можно оформить тестовый проект в платёжной платформе Ecommpay \(что можно сделать [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\). - Проводить разовые оплаты в одну или две стадии. В рамках одного проекта можно выбрать один из вариантов проведения оплат: с незамедлительным списанием средств \(в одну стадию\)с использованием любого из подключённых платёжных методов либо с предварительной блокировкой и последующим списанием средств \(в две стадии\)с использованием любого из методов, для которого поддерживается проведение таких оплат через Payment Page. - Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина. Это можно делать в рамках тех методов, для которых поддерживается выполнение возвратов.При этом инициировать возвраты можно через интерфейс Magento и, если актуально, интерфейсы платёжной платформы Ecommpay \(пользовательский интерфейс Dashboard и Gate API\). Вместе с тем, при использовании интерфейсов платёжной платформы Ecommpay информация о платежах в интерфейсе Magento обновляется, только если настроена отправка оповещений со стороны платёжной платформы \([подробнее](ru_dbl_projects.md)\). - Контролировать информацию о платежах, проводимых с помощью плагина. Это можно делать через интерфейс Magento и, если актуально, — через Data API и пользовательский интерфейс Dashboard от Ecommpay. - Управлять заказами, оплаты по которым проводятся с помощью плагина, через интерфейс Magento. При этом можно отменять такие заказы и корректировать их статусы вручную. - Настраивать параметры работы платёжной формы Payment Page, адаптируя её под специфику веб-сервиса, и применять различные возможности, обеспечиваемые со стороны Ecommpay. В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking иподключать отправку пользователям уведомлений о результатах оплат \([подробнее](ru_PP_receipt_data.md)\). Для подключения этих возможностей следует обращаться к специалистам технической поддержки Ecommpay. Столь широкий спектр возможностей позволяет подстраиваться под различные особенности бизнеса, гибко настраивать пользовательские сценарии и обеспечивать высокий уровень конверсии платёжной формы и проходимости платежей. Для подключения и применения возможностей, предоставляемых Ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам Ecommpay. ### Схемы работы {#section_ccj_fbg_2yb .section} В схемах проведения оплат в одну и две стадии с использованием плагина от Ecommpay задействуются пользователь, веб-сервис со встроенным в него плагином, платёжная форма Payment Page, платёжная платформа и платёжная среда. При этом с помощью плагина на стороне веб-сервиса обеспечиваются автоматический вызов Payment Page и автоматическое взаимодействие с платёжной платформой в соответствии с заданными параметрами работы. При работе *с одностадийными оплатами*на основании одного исходного запроса выполняются разовый перевод средств от пользователя к мерчанту и отправка к веб-сервису оповещения о результате проведения платежа. ![](images/universal/cms/ru_cms_workflow.svg) 1. Пользователь на стороне веб-сервиса открывает страницу перехода к оплатеи выбирает один из методов оплаты, доступных через плагин от Ecommpay. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Pageс учётом выбранного пользователем метода. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия для оплаты и подтверждает готовность провести оплату. 8. В платёжную платформу поступает итоговый запрос на оплату \(со всеми необходимыми сведениями\). 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе Magento формируется счёт на оплату и обновляются базовые сведения о платеже. 13. От платёжной платформы к Payment Page направляется информация о результате оплаты. 14. Информация о результате оплаты отображается пользователю в платёжной форме Payment Page. При работе *с двухстадийными оплатами* на основании исходного запроса \(на первой стадии\) выполняется блокировка средств пользователя, а затем \(на второй стадии\) на основании подтверждающего запроса или автоматически по истечении заданного срока выполняется списание заблокированных средств или отмена блокировки. При этом на каждой стадии к веб-сервису отправляется оповещение с информацией о соответствующем результате. ![](images/universal/cms/ru_cms_workflow_auth.svg) 1. Пользователь на стороне веб-сервиса открывает страницу перехода к оплатеи выбирает один из методов оплаты, доступных через плагин от Ecommpay. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Pageс учётом выбранного пользователем метода. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает запрос на выполнение блокировки средств. 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа и блокировка средств пользователя. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате блокировки средств. 12. От платёжной платформы к веб-сервису направляется оповещение о результате блокировки. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе Magento обновляются базовые сведения о платеже. 13. От платёжной платформы к Payment Page направляется информация о результате блокировки. 14. Информация о результате блокировки отображается пользователю в платёжной форме Payment Page. 15. После того как подтверждается необходимость списания средств, специалист мерчанта инициирует это списание, в результате чего \(с помощью плагина\) запрос на списание средств поступает в платёжную платформу и обрабатывается в ней. 16. Запрос передаётся в платёжную среду. 17. В платёжной среде выполняется обработка платежа. 18. Из платёжной среды к платёжной платформе направляется информация о результате списания. 19. От платёжной платформы к веб-сервису направляется оповещение о результате списания. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе Magento формируется счёт на оплату и обновляются базовые сведения о платеже. 20. Пользователь уведомляется о результате списания средствами веб-сервиса. Для взаимодействия с пользователями при проведении одностадийных оплат и блокировке средств в рамках двухстадийных оплат возможны два варианта работы: - со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса\(через элемент iframe\); - с открытием платёжной формы в модальном окне или отдельной вкладке. Первый из этих вариантов доступен только для оплат с прямым использованием платёжных карт и используется для них по умолчанию.В этом варианте пользователь указывает данные платёжной карты и подтверждает формирование заказа в CMS Magento и платежа в платформе Ecommpay непосредственно на странице перехода к оплате в веб-сервисе\(с помощью кнопки **Place Order**\). Второй вариант используется для всех альтернативных платёжных методов и для оплат с прямым использованием платёжных карт, если для них был выбран способ открытия формы в модальном окне или отдельной вкладке.В этомварианте пользователь сначала подтверждает формирование заказа в CMS Magento на странице перехода к оплате веб-сервиса\(с помощью кнопки **Place Order**\) и уже после этого указывает необходимые данные в открывшейся платёжной форме и подтверждает формирование платежа в платформе Ecommpay\(с помощью кнопки **Оплатить**\). Помимо прочего, при втором варианте возможны случаи, когда пользователь подтверждает формирование заказа, но не переходит к подтверждению оплаты. В таких случаях в веб-сервисе появляются заказы в статусе `Pending Payment`, при этом оплаты в рамках этих заказов не инициируются. В остальном работа с заказами и платежами по ним идентична для обоих вариантов. Контролировать информацию о заказах и платежах по ним можно через интерфейс Magento: в подразделе **Orders** раздела **Sales**. При этом следует учитывать, что для заказов и платежей используются разные идентификаторы и статусы.Заказам на стороне веб-сервиса присваиваются девятизначные номера \(например, `000001503`\) и статусы в соответствии с моделью выполнения заказов Magento \([подробнее](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-status.html?lang=en)\), платежам на стороне платёжной платформы — идентификаторы, включающие в себя префикс `mag_` и тринадцатизначный код \(например, `mag_64ca3135cffd3`\), и статусы в соответствии с моделью проведения платежей Ecommpay \([подробнее](ru_platform_payment_model.md)\). С вопросами о соответствии статусов заказов и платежей можно обращаться к курирующему менеджеру Ecommpay. ## Установка {#ru_cms_magento_installation} ### Общая информация {#section_vgj_bbh_mcc .section} Чтобы начать работу с плагином от Ecommpayверсии 2.1.6 для CMS Magento, его необходимо установить. Это можно сделать *через каталог плагинов* Magento\(без предварительного скачивания файлов плагина\) или *через загрузку zip-архива* с файлами плагина\(предварительно скачав этот архив\). При возникновении вопросов, касающихся установки описываемого плагина, можно обращаться к специалистам технической поддержки Ecommpay. ### Установка через каталог плагинов {#section_ttm_xbh_mcc .section} Для установки через каталог плагинов следует: 1. Выполнить команду `composer require ecommpay/module-payments` из корневой папки с файлами CMS Magento. 2. При необходимости [получить](https://experienceleague.adobe.com/en/docs/commerce-operations/installation-guide/prerequisites/authentication-keys) и указать ключ аутентификации для доступа к интеграционным модулям на стороне CMS Magento. 3. Выполнить следующие команды из корневой папки с файлами CMS Magento и дождаться завершения установки. ``` php bin/magento setup:upgrade php bin/magento cache:flush php bin/magento cache:clean php bin/magento setup:di:compile php bin/magento setup:static-content:deploy ``` ### Установка через загрузку архива {#section_nz3_kgh_mcc .section} Для установки плагина через загрузку zip-архива следует: 1. Скачать zip-архив плагина [с портала GitHub](https://github.com/ITECOMMPAY/ecommpay-magento2). 2. Распаковать zip-архив и добавить папку с файлами плагина в папку с исходным кодом веб-сервиса на базе CMS Magento — во вложенную папку `app/code`. **Прим.:** Если до установки плагина использовалась и не была удалена одна из его предыдущих версий, папку с файлами этой версии следует удалить из папки с исходным кодом веб-сервиса перед добавлением папки с новой версией. Также стоит учитывать, что в зависимости от структуры файлов в папке с исходным кодом веб-сервиса для подключения к ней могут потребоваться дополнительные действия \(например, подключение по протоколу SSH\). 3. Выполнить следующие команды из корневой папки с файлами CMS Magento и дождаться завершения установки. ``` php bin/magento indexer:reindex php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento cache:flush php bin/magento cache:clean php bin/magento setup:static-content:deploy ``` ## Тестирование {#ru_cms_magento_testing} ### Общая информация {#ru_cms_magento_testing_overview} Для проверки работы плагина и проведения тестовых платежей без реального списания средств можно использовать два варианта: - *Тестирование через тестовый режим работы плагина.* Это вариант с локальным базовым тестированием, без подключения к платёжной платформе Ecommpay.Он позволяет оперативно проверять работу платёжной формы и отдельные сценарии проведения карточных платежей. При этом в идентификаторах таких платежей, условно проводимых в таком варианте тестирования, используются кодовое слово `test` и доменное имя веб-сервиса \(например, `test_mysite_mag_64ca3135cffd3`\), что может быть удобным при контроле проведения платежей. - *Тестирование через тестовую среду платёжной платформы Ecommpay.* Это вариант с комплексным тестированием, с подключением к платёжной платформе Ecommpay и задействованием её компонентов.Подключиться к платформе можно в течение нескольких минут, используя соответствующую форму [на основном сайте компании](https://ecommpay.com/sign-up/) и полученные идентификатор и ключ тестового проекта. В таком случае плагин переводится в рабочий режим и позволяет тестировать большее число платёжных сценариев, в том числе с использованием альтернативных методов, для которых поддерживается работа с эмуляторами \([подробнее](ru_pm_testing.md)\).При этом все платежи остаются тестовыми \(хотя в их идентификаторах уже и не используются кодовое слово `test` и доменное имя веб-сервиса\). Для сопоставления этих вариантов тестирования можно использовать следующую таблицу. |Возможности тестирования|через тестовый режим плагина|через тестовую среду платформы| |------------------------|----------------------------|------------------------------| |Открытие платёжной формы с применением различных способов и параметров работы|+|+| |Проведение разовых оплат \(в одну и в две стадии\)|+|+| |Использование альтернативных платёжных методов \(при обращении к специалистам Ecommpay\)|–|+| |Использование дополнительных возможностей платёжной формы Payment Page \(при обращении к специалистам Ecommpay\)|–|+| |Выполнение возвратов|+|+| |Контроль информации о платежах|+|+| |Управление заказами|+|+| Независимо от выбранного варианта тестирования \(в тестовом режиме или с тестовой средой платёжной платформы Ecommpay\), плагин подключается к веб-сервису и становится доступен пользователям как вариант оплаты. Поэтому в тех случаях, когда плагин подключается к работающему веб-сервису, рекомендуется выполнять тестирование в период низкой нагрузки и предупреждать пользователей о проводимых работах. ### Настройка параметров {#ru_cms_magento_testing_setup} Чтобы подготовить плагин к тестированию, необходимо определить предпочтительный вариант тестирования и настроить плагин в интерфейсе Magento следующим образом: 1. Перейти к параметрам работы плагина в интерфейсе Magento. Для этого следует: 1. Выбрать раздел **Stores** на панели навигации и пункт **Configuration** в появившемся меню. 2. Выбрать раздел **Sales** и пункт **Payment Methods** в левом меню подраздела **Configuration**. 3. Найти секцию с параметрами работы плагина от Ecommpay на открывшейся странице и щёлкнуть кнопку **Configure**. 2. Задать основные параметры работы плагина в раскрывающемся блоке **General settings**: - **Plugin Enabled** — возможность подключить плагин к веб-сервису. Если для этого параметра задано значение **Yes**, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если задано значение **No**, то все платёжные методы отключаются от веб-сервиса и становятся недоступными для проведения платежей. - **Demo mode** — возможность установить тестовый режим работы плагина. Для использования тестового режима работы плагина необходимо задать значение **Yes**, для использования тестовой среды платформы — задать значение **No** и параметры подключения, полученные от Ecommpay, в полях **Project ID** и **Secret Key**. **Прим.:** При работе в тестовом режиме плагина значения, заданные в полях **Project ID** и **Secret Key**, игнорируются. Поэтому для использования тестового проекта в платёжной платформе Ecommpay необходимо отключить тестовый режим плагина. - **Project ID** — идентификатор тестового проекта. - **Secret Key** — ключ тестового проекта для взаимодействия с платформой. - **Language** — язык отображения платёжной формы. - **Additional parameters** — дополнительные [параметры вызова платёжной формы](ru_PP_Parameters.md). При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &. - **Payment action** — вариант проведения оплат: - **Authorize** — в две стадии \(с предварительной блокировкой и последующим списанием средств\); - **Authorize and Capture** — в одну стадию \(с незамедлительным списанием средств\). Первый вариант доступен только для платежей с прямым использованием карт или методов Apple Pay и Google Pay, а второй — для всех платёжных методов, подключённых для работы через плагин. ![](images/ecommpay/cms/magento/cms_magento_settings_general.png "Блок General settings с основными параметрами подключения") 3. Задать параметры использования платёжных методов \([подробнее](ru_CMS__magento.md)\). При работе в тестовом режиме плагина достаточно задать параметры для карточных платежей в раскрывающемся блоке **Card payments** или **More payment methods via Ecommpay**. 4. Сохранить параметры работы плагина. Для этого следует щёлкнуть кнопку **Save Config**. ### Проведение тестовых оплат {#ru_cms_magento_testing_purchase} #### Введение {#section_lvb_xhk_2yb .section} В рамках работы с плагином можно проводить тестовые оплаты в веб-сервисе и получать базовые сведения о них через интерфейс Magento— в подразделе **Orders** раздела **Sales**. При этом можно использовать специальные платёжные реквизиты, позволяющие тестировать заданные сценарии работы. Чтобы тестировать проведение карточных платежей, можно использовать номера тестовых карт. При этом для тестирования по заданным кратчайшим сценариям \(без эмулирования аутентификации 3‑D Secure\)можно использовать следующие номера карт: - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей\(в том числе с аутентификацией 3‑D Secure\), представленных в статье [Номера тестовых карт](ru_test_cards.md). Чтобы тестировать проведение платежей с использованием альтернативных методов\(при подключении соответствующих методов через курирующего менеджера или техническую поддержку и при использовании тестовой среды платёжной платформы\), можно использовать информацию, представленную в статье [Возможности тестирования](ru_pm_testing.md), а также в разделах о тестировании отдельных методов. #### Обеспечение синхронизации данных {#section_s1z_sg2_lcc .section} При работе с двухстадийными оплатами вторые стадии можно инициировать как через интерфейс Magento, так и через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\). Во втором случае информация о заказах в интерфейсе Magento обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускается инициирование вторых стадий оплат через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс Magento, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе Magento. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате `https:///ecommpay/endpayment/index`. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. #### Процедуры {#section_fbx_wh2_lcc .section} Оплата в одну стадию, как и первая стадия двухстадийной оплаты\(блокировка средств\), инициируется пользователем при подтверждении им платежа. Одностадийная оплата проводится автоматически, в то время как для проведения двухстадийной оплаты сначала автоматически выполняется только первая стадия, с блокировкой средств, и уже после этого может выполняться вторая стадия, со списанием средств или отменой блокировки. Инициировать вторую стадию можно также автоматически, по истечении установленного срока блокировки, либо по запросу со стороны мерчанта, через интерфейс Magento или интерфейсы платёжной платформы Ecommpay — Dashboard\([подробнее](ru_dbl_payments.md)\) и Gate API\([подробнее](ru_gate_payment_auth.md)\). При этом списания по запросам могут выполняться как на полную, так и на частичную сумму заблокированных средств. Чтобы инициировать вторую стадию через интерфейс Magento, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **Sales** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты. 3. Инициировать вторую стадию оплаты. Для списания заблокированных средств следует выполнить следующее: 1. Щёлкнуть кнопку **Invoice** в верхнем меню карточки заказа. 2. Убедиться, что в столбце **Qty to Invoice** на открывшейся странице выбрано количество товаров, за которое необходимо выполнить списание. **Прим.:** Следует учитывать, что при списании средств только за часть товаров в рамках заказа блокировка оставшейся суммы автоматически отменяется. 3. Убедиться, что для параметра **Amount** в нижней части страницы выбрано значение **Capture Online**, и щёлкнуть кнопку **Submit Invoice**. Для отмены блокировки средств следует щёлкнуть кнопку **Void** в верхнем меню карточки заказа и подтвердить действие в появившемся диалоговом окне. Для настройки автоматического инициирования второй стадии двухстадийных оплат следует обращаться к специалистам технической поддержки Ecommpay. **Прим.:** В соответствии с требованиями международных платёжных систем на стороне платёжной платформы Ecommpay ограничивается время, на которое могут быть заблокированы средства пользователей \([подробнее](ru_pp_purchase_auth.md#section_cmc_b3s_1mb)\).Если по истечении предельного времени средства не были списаны или их блокировка не была отменена, платёж автоматически отклоняется на стороне платформы. ### Выполнение тестовых возвратов {#ru_cms_magento_testing_refund} #### Введение {#section_tyk_2jk_2yb .section} После проведения тестовых оплат можно тестировать выполнение возвратовчерез интерфейс Magento и, если актуально, интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе Magento должны быть в статусах `Processing` или `Complete`, а платежи в платформе Ecommpay — в статусах `success`, `partially reversed` или `partially refunded`. Также можно иметь в виду, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочем режиме. **Прим.:** Когда из платформы Ecommpay в веб-сервис поступает информации о платеже, проведённом в рамках заказа, для этого заказа в интерфейсе Magento автоматически формируется счёт на оплату — *invoice* \(информацию о таком счёте можно получить в разделе **Invoices** в карточке заказа\). До формирования счёта на оплату выполнить возврат в рамках соответствующего заказа через интерфейс Magento нельзя. #### Обеспечение синхронизации данных {#section_v14_rkq_hcc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о заказах в интерфейсе Magento обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс Magento, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе Magento. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате `https:///ecommpay/endpayment/index`. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. #### Процедуры {#section_zl4_slq_hcc .section} Выполнять возвраты можно для проведённых оплат, по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы Ecommpay и интерфейс Magento. Чтобы выполнить возврат через интерфейс Magento, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **Sales** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, по которому необходимо выполнить возврат средств, и выбрать пункт **Invoices**в левом меню карточки заказа. 3. Выбрать счёт на оплату, в рамках которого был проведён платёж, в таблице и щёлкнуть кнопку **Credit Memo**в верхнем меню страницы счёта на оплату. 4. Указать количество товаров, которые необходимо вернуть, и при необходимости щёлкнуть кнопку **Update Qty's** для обновления суммы возвратана странице выполнения возвратов **New Memo**. 5. При необходимости указать комментарий для возврата в поле **Credit Memo Comments**. 6. Подтвердить выполнение возврата. Для этого следует щёлкнуть кнопку **Refund**. 7. Убедиться в том, что в истории заказа отображается информация о выполненном возврате. При выполнении частичного возврата заказу присваивается статус `Processing`, при выполнении полного возврата заказу присваивается статус `Closed`. ![](images/universal/cms/magento/cms_magento_refund.png "Карточка заказа в интерфейсе Magento") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). При выполнении возвратов через интерфейс Magento в этом интерфейсе формируются записи с информацией о таких возвратах — *credit memos*. Просматривать такие записи можно через раздел **Credit Memos** в карточках отдельных заказов, а более детальную информацию о возвратах можно получать через интерфейсы платформы Ecommpay \(например, Dashboard и Data API\). ## Использование {#ru_cms_magento_usage} ### Общая информация {#ru_cms_magento_usage_overview} Для проведения платежей с реальным списанием средств, прежде всего, необходимо решить все организационные вопросы по взаимодействию с Ecommpay\(подать заявку на подключение, предоставить всю необходимую информацию и получить от Ecommpay уведомление о возможности проводить платежи, а также идентификатор и секретный ключ рабочего проекта\). Вместе с тем, необходимосообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина от Ecommpay,и валюту проведения платежей. После этого можно перевести плагин в рабочий режим, указать в параметрах его работы полученныеидентификатор и ключ и задать другие необходимые параметры\(или проверить их актуальность для рабочего применения\). Если после этого потребуется приостановить работу плагина, например для тестирования при подключении дополнительных функций, его можно перевести в тестовый режим или отключить от веб-сервиса. ### Настройка параметров {#ru_cms_magento_usage_setup} Чтобы настроить параметры работы плагина, следует: 1. Перейти к параметрам работы плагина в интерфейсе Magento. Для этого следует: 1. Выбрать раздел **Stores** на панели навигации и пункт **Configuration** в появившемся меню. 2. Выбрать раздел **Sales** и пункт **Payment Methods** в левом меню подраздела **Configuration**. 3. Найти секцию с параметрами работы плагина от Ecommpay на открывшейся странице и щёлкнуть кнопку **Configure**. 2. Задать основные параметры работы плагина в раскрывающемся блоке **General settings**: - **Plugin Enabled** — возможность подключить плагин к веб-сервису. Если для этого параметра задано значение **Yes**, то все платёжные методы, ранее подключённые для работы через плагин, становятся доступными в веб-сервисе. Если задано значение **No**, то все платёжные методы отключаются от веб-сервиса и становятся недоступными для проведения платежей. - **Demo mode** — возможность установить тестовый режим работы плагина. Для использования рабочей среды платформы следует задать значение **No** и параметры подключения, полученные от Ecommpay, в полях **Project ID** и **Secret Key**. - **Project ID** — идентификатор рабочего проекта. - **Secret Key** — ключ рабочего проекта для взаимодействия с платформой. - **Language** — язык отображения платёжной формы. - **Additional parameters** — дополнительные [параметры вызова платёжной формы](ru_PP_Parameters.md).При указании в этом поле нескольких параметров в качестве разделителя необходимо использовать символ &. - **Payment action** — вариант проведения оплат: - **Authorize** — в две стадии \(с предварительной блокировкой и последующим списанием средств\); - **Authorize and Capture** — в одну стадию \(с незамедлительным списанием средств\). Первый вариант доступен только для платежей с прямым использованием карт или методов Apple Pay и Google Pay, а второй — для всех платёжных методов, подключённых для работы через плагин. ![](images/ecommpay/cms/magento/cms_magento_settings_general.png "Блок General settings с основными параметрами подключения") 3. Задать параметры использования платёжных методов \([подробнее](ru_CMS__magento.md)\). 4. Сохранить параметры работы плагина. Для этого следует щёлкнуть кнопку **Save Config**. ### Проведение оплат {#ru_cms_magento_usage_purchase} #### Введение {#section_xff_vp2_lcc .section} Если веб-сервис и плагин корректно настроены, проведение одностадийных оплат и блокировка средств для двухстадийных оплат осуществляются автоматически.При этом важно обеспечивать сбор всех необходимых данных на стороне веб-сервиса. **Прим.:** Расширен набор сведений, необходимых для аутентификации 3‑D Secure при проведении карточных оплат. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты. С вопросами и проблемами, касающимися проведения оплат, можно обращаться к специалистам технической поддержки Ecommpay. #### Обеспечение синхронизации данных {#section_hrb_5r2_lcc .section} При работе с двухстадийными оплатами вторые стадии можно инициировать как через интерфейс Magento, так и через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\). Во втором случае информация о заказах в интерфейсе Magento обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускается инициирование вторых стадий оплат через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс Magento, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе Magento. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате `https:///ecommpay/endpayment/index`. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. #### Процедуры {#section_vsg_yt2_lcc .section} Оплата в одну стадию, как и первая стадия двухстадийной оплаты\(блокировка средств\), инициируется пользователем при подтверждении им платежа. Одностадийная оплата проводится автоматически, в то время как для проведения двухстадийной оплаты сначала автоматически выполняется только первая стадия, с блокировкой средств, и уже после этого может выполняться вторая стадия, со списанием средств или отменой блокировки. Инициировать вторую стадию можно также автоматически, по истечении установленного срока блокировки, либо по запросу со стороны мерчанта, через интерфейс Magento или интерфейсы платёжной платформы Ecommpay — Dashboard\([подробнее](ru_dbl_payments.md)\) и Gate API\([подробнее](ru_gate_payment_auth.md)\). При этом списания по запросам могут выполняться как на полную, так и на частичную сумму заблокированных средств. Чтобы инициировать вторую стадию через интерфейс Magento, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **Sales** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты. 3. Инициировать вторую стадию оплаты. Для списания заблокированных средств следует выполнить следующее: 1. Щёлкнуть кнопку **Invoice** в верхнем меню карточки заказа. 2. Убедиться, что в столбце **Qty to Invoice** на открывшейся странице выбрано количество товаров, за которое необходимо выполнить списание. **Прим.:** Следует учитывать, что при списании средств только за часть товаров в рамках заказа блокировка оставшейся суммы автоматически отменяется. 3. Убедиться, что для параметра **Amount** в нижней части страницы выбрано значение **Capture Online**, и щёлкнуть кнопку **Submit Invoice**. Для отмены блокировки средств следует щёлкнуть кнопку **Void** в верхнем меню карточки заказа и подтвердить действие в появившемся диалоговом окне. Для настройки автоматического инициирования второй стадии двухстадийных оплат следует обращаться к специалистам технической поддержки Ecommpay. **Прим.:** В соответствии с требованиями международных платёжных систем на стороне платёжной платформы Ecommpay ограничивается время, на которое могут быть заблокированы средства пользователей \([подробнее](ru_pp_purchase_auth.md#section_cmc_b3s_1mb)\).Если по истечении предельного времени средства не были списаны или их блокировка не была отменена, платёж автоматически отклоняется на стороне платформы. ### Выполнение возвратов {#ru_cms_magento_usage_refund} #### Введение {#section_d3n_znz_hcc .section} После проведения оплат можно выполнять возвраты по нимчерез интерфейс Magento и, если актуально, интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе Magento должны быть в статусах `Processing` или `Complete`, а платежи в платформе Ecommpay — в статусах `success`, `partially reversed` или `partially refunded`. Также можно иметь в виду, что все возможности и процедуры по работе с возвратами в рабочем режиме соответствуют тем, которые доступны в тестовом режиме. **Прим.:** Когда из платформы Ecommpay в веб-сервис поступает информации о платеже, проведённом в рамках заказа, для этого заказа в интерфейсе Magento автоматически формируется счёт на оплату — *invoice* \(информацию о таком счёте можно получить в разделе **Invoices** в карточке заказа\). До формирования счёта на оплату выполнить возврат в рамках соответствующего заказа через интерфейс Magento нельзя. #### Обеспечение синхронизации данных {#section_hvr_44z_hcc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о заказах в интерфейсе Magento обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс Magento, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе Magento. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS Magento, на URL в формате `https:///ecommpay/endpayment/index`. Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. Иначе в протоколах работы плагина появляются сообщения об ошибках, связанных с обработкой оповещений от платёжной платформы. #### Процедуры {#section_rxn_p4z_hcc .section} Выполнять возвраты можно для проведённых оплат, по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы Ecommpay и интерфейс Magento. Чтобы выполнить возврат через интерфейс Magento, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **Sales** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, по которому необходимо выполнить возврат средств, и выбрать пункт **Invoices**в левом меню карточки заказа. 3. Выбрать счёт на оплату, в рамках которого был проведён платёж, в таблице и щёлкнуть кнопку **Credit Memo**в верхнем меню страницы счёта на оплату. 4. Указать количество товаров, которые необходимо вернуть, и при необходимости щёлкнуть кнопку **Update Qty's** для обновления суммы возвратана странице выполнения возвратов **New Memo**. 5. При необходимости указать комментарий для возврата в поле **Credit Memo Comments**. 6. Подтвердить выполнение возврата. Для этого следует щёлкнуть кнопку **Refund**. 7. Убедиться в том, что в истории заказа отображается информация о выполненном возврате. При выполнении частичного возврата заказу присваивается статус `Processing`, при выполнении полного возврата заказу присваивается статус `Closed`. ![](images/universal/cms/magento/cms_magento_refund.png "Карточка заказа в интерфейсе Magento") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). При выполнении возвратов через интерфейс Magento в этом интерфейсе формируются записи с информацией о таких возвратах — *credit memos*. Просматривать такие записи можно через раздел **Credit Memos** в карточках отдельных заказов, а более детальную информацию о возвратах можно получать через интерфейсы платформы Ecommpay \(например, Dashboard и Data API\). ### Контроль платежей и заказов {#ru_cms_magento_usage_monitoring} Контролировать информацию о заказах, включая базовые сведения о платежах, проводимых с помощью плагина от Ecommpay, можно через интерфейс Magento, используя инструменты подраздела **Orders** в разделе **Sales**. Для получения более детальных сведений о платежах и возвратах можно использовать интерфейс Dashboard от Ecommpay\(но в нём не отображается информация о заказах\). В подразделе **Orders** отображается реестр заказов с основными сведениями о каждом из них, а также с возможностями поиска, фильтрации, перехода к карточкам отдельных заказов и выполнения различных действий. ![](images/universal/cms/magento/cms_magento_orders.png "Реестр заказов в интерфейсе Magento") Для перехода к карточке конкретного заказа можно щёлкнуть его строку в реестре. В карточкахотображаются развёрнутые сведения о заказах\(включая дату создания, статус, сумму заказа и адрес доставки\), а также базовые сведения о платежах и другая информация. Карточки заказов состоят из следующих секций: - **Order & Account Information** — с информацией о заказе и пользователе; - **Address Information** — с информацией о расчётном адресе и адресе доставки пользователя; - **Payment & Shipping Method** — с базовыми сведениями о платеже и способе доставки; - **Items Ordered** — с информацией о приобретённых товарах. ![](images/universal/cms/magento/cms_magento_order.png "Карточка заказа в интерфейсе Magento") В пункте **Transactions** левого меню отображаются сведения о транзакциях в рамках заказа.Каждая транзакция соответствует отдельной операции, выполненной на стороне платформы Ecommpay. Так, могут создаваться транзакции следующих типов: - **Authorization** — при блокировке средств \(выполнении операции `auth`\); - **Capture** — при списании средств \(выполнении операции `capture` для двухстадийной оплаты или операции `sale` для одностадийной оплаты\); - **Void** — при отмене блокировки средств в рамках двухстадийной оплаты \(выполнении операции `cancel`\); - **Refund** — при выполнении возврата \(выполнении операции `refund`\). Идентификатор каждой транзакции \(**Transaction ID**\) соответствует идентификатору запроса на выполнение операции в платёжной платформе и присваивается следующей транзакции в заказе в качестве идентификатора „родительской“ транзакции \(**Parent Transaction ID**\). ![](images/universal/cms/magento/cms_magento_transactions.png "Реестр транзакций в интерфейсе Magento") Более подробная информация о работе с заказами в интерфейсе Magento представлена [в документации Magento](https://experienceleague.adobe.com/docs/commerce-admin/stores-sales/order-management/orders/order-processing.html?lang=en). ## Использование тем оформления Hyvä {#ru_cms_magento_theme} ### Общая информация {#section_ktt_vnk_kfc .section} Для веб-сервисов, разработанных на базе CMS Magento версии 2.0, доступна возможность использовать вместо базовых тем Blank и Luma альтернативную тему оформления от Hyvä с поддержкой актуальных технологий и тенденций \([подробнее](https://www.hyva.io/)\). При работе с плагином от Ecommpay для Magento можно использовать эту тему, установив в дополнение к нему следующие плагины: - Hyvä Themes версии 1.3 и выше— для подключения темы оформления веб-сервиса; - Hyvä Checkout версии 1.3 и выше— для подключения темы оформления страницы формирования заказов; - Ecommpay Hyvä— для подключения платёжной формы Payment Page, адаптированной под работу с плагином Hyvä Checkout. С темой оформления от Hyvä можно гибко настраивать страницу формирования заказов, размещая все шаги \(заполнение контактных данных пользователей, информации о доставке и оплате\) на одном экране или разделяя их на отдельные экраны. Независимо от выбранного варианта, работа с платёжной формой Payment Page поддерживается двумя способами — со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса и с открытием платёжной формы в модальном окне или отдельной вкладке. Кроме того, платёжная форма Payment Page, подключаемая с плагином Ecommpay Hyvä, обратно совместима с базовыми темами Blank и Luma, благодаря чему использование базовых тем с этим плагином не влияет на проходимость платежей. ### Установка и настройка {#section_az2_wnk_kfc .section} Чтобы начать работу с темой оформления Hyvä вместе с плагином от Ecommpay для CMS Magento версии 2.0, необходимо дополнительно установить плагины от Hyvä и Ecommpay и применить тему оформления Hyvä. Установка выполняется через *через каталог плагинов* Magento\(без предварительного скачивания файлов плагина\) или *через загрузку zip-архива* с файлами плагина\(предварительно скачав этот архив\). Для работы с темой оформления Hyvä следует: 1. Установить плагины Hyvä Themes и Hyvä Checkout и убедиться, что они установлены в качестве зависимостей. Для этого необходимо установить плагины в соответствии с инструкциями [Hyvä Themes](https://docs.hyva.io/hyva-themes/getting-started/index.html) и [Hyvä Checkout](https://docs.hyva.io/checkout/hyva-checkout/getting-started/index.html) и проверить в файле composer.json из корневой папки с файлами CMS Magento наличие следующих зависимостей. ``` {#codeblock_hpd_cqk_kfc} "hyva-themes/magento2-default-theme": "^1.3", "hyva-themes/magento2-hyva-checkout": "^1.3" ``` 2. Установить плагин Ecommpay Hyvä в дополнение к плагину от Ecommpay для CMS Magento версии 2.0 и убедиться, что он установлен в качестве зависимости. Для установки плагина *через каталог плагинов* необходимо выполнить следующие команды из корневой папки с файлами CMS Magento. ``` {#codeblock_f5s_vfl_kfc} composer config repositories.ecommpay/hyva-magento git https://github.com/ITECOMMPAY/hyva-magento.githttps://github.com/ITECOMMPAY/hyva-magento.git composer require ecommpay/hyva-magento ``` Для установки плагина *через загрузку zip-архива* следует скачать zip-архив плагина [с портала GitHub](https://github.com/ITECOMMPAY/hyva-magento), распаковать zip-архив и добавить папку с файлами плагина в папку с исходным кодом веб-сервиса на базе CMS Magento. В случае, если плагин от Ecommpay для CMS Magento версии 2.0 ещё не установлен, он устанавливается автоматически вместе с плагином Ecommpay Hyvä через каталог плагинов либо самостоятельно через загрузку zip-архива \([подробнее](ru_CMS__magento.md)\). Для проверки наличия зависимостей необходимо открыть файл composer.json из корневой папки с файлами CMS Magento и найти их по названиям — `ecommpay/hyva-magento` и `ecommpay/module-payments`. 3. Активировать установленные плагины, выполнив следующие команды. ``` {#codeblock_dtb_x4k_kfc} bin/magento setup:upgrade bin/magento cache:flush bin/magento cache:clean bin/magento setup:di:compile bin/magento setup:static-content:deploy ``` 4. Применить тему оформления Hyvä и, при необходимости, настроить свойства плагинов в интерфейсе Magento, следуя инструкциям [Hyvä Themes](https://docs.hyva.io/hyva-themes/getting-started/index.html) и [Hyvä Checkout](https://docs.hyva.io/checkout/hyva-checkout/getting-started/index.html). **Прим.:** Важно учитывать, что в набор обязательных сведений для проведении карточных оплат включены параметры, которые необходимы для проверки AVS \(Address Verification Service\). Поэтому при открытии платёжной формы в элементе iframe \(в режиме **Embedded**\) на странице перехода к оплате должны использоваться поля для указания пользователем его почтового индекса и адреса доставки. Для этого в свойствах плагина Hyvä Checkout необходимо отметить поле `postcode` и одно из полей из группы `street` в качестве обязательных для заполнения пользователем. 5. Убедиться, что активированы установленные плагины и применена тема оформления Hyvä. Для этого необходимо перейти в веб-сервис и протестировать формирование заказа с переходом к его оплате. При возникновении вопросов, касающихся установки, можно обращаться к специалистам технической поддержки Ecommpay. ## Параметры использования платёжных методов {#ru_cms_magento_methods} При работе с плагином от Ecommpay в интерфейсе Magento можно настраивать использование различных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать черезотдельные раскрывающиеся блоки на странице с параметрами работы плагина— **Card payments** \(с параметрами для карточных платежей\) и **Alternative payment settings** \(с параметрами использования альтернативных методов\).Последний блок в частности содержит блок **More payment methods via Ecommpay**, в котором можно настраивать использование полной группы методов, подключённых в проекте, — это может быть актуально, например, когда используются методы, для которых не выделены отдельные блоки в параметрах работы плагина. **Прим.:** Раскрывающиеся блоки, отображаемые по умолчанию, исключить из параметров работы плагина нельзя, даже если соответствующие методы не используются в проекте.Если актуально работать с другими методами, их использование в плагине можно настраивать только в блоке **More payment methods via Ecommpay**, предварительно обратившись к специалистам технической поддержки Ecommpay для подключения методов в проекте. В раскрывающихся блоках для настройки использования платёжных методов можно задавать следующие параметры: - Общие параметры: - **Enabled** — возможность подключить платёжный метод для работы через плагин. Для подключения метода следует установить значение **Yes**, для отключения метода — значение **No**. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе. - **Show Description** — возможность отображения текста из параметра **Description**. - **Description** — текст, отображаемый пользователям при выборе конкретного платёжного метода. - **Sort Order** — порядковый номер отображения названия платёжного метода, доступного через плагин от Ecommpay, на странице перехода к оплате в веб-сервисе. Чтобы название метода отображалось первым в списке методов, следует задать значение `0` или оставить поле пустым. При этом, если платёжный метод отключён от веб-сервиса, то вместо него отображается название метода под следующим номером. Если задать значение `0` или оставить поле пустым для нескольких методов, то названия этих методов отображаются в порядке расположения блоков с параметрами использования методов. - Параметры, актуальные только для блока **Card payments**: - **Display mode** — способ открытия платёжной формы Payment Page. Можно выбрать один из следующих способов: - **Redirect** — открытие в виде отдельной HTML-страницы; - **Popup** — открытие в модальном окне; - **Embedded** — открытие в элементе iframe. **Прим.:** При установке плагина или обновлении его версии этот способ настроен по умолчанию. В случае, если платёжная форма открыта в элементе iframe\(способ **Embedded**\), при выборе пользователем оплаты с использованием платёжной карты в списке вариантов для оплаты ему отображается платёжная форма Payment Page, с адаптацией под стандартное оформление страницы перехода к оплате в веб-сервисе и без кнопки для подтверждения согласия на оплату. В открывшейся форме пользователь может выбрать реквизиты платёжной карты \(если они были сохранены ранее\) или указать их, а затем — подтвердить готовность провести оплату с помощью кнопки для перехода к оплате на странице веб-сервиса. При выборе других платёжных методов пользователь перенаправляется на последующие страницы. ![](images/ecommpay/cms/magento/cms_magento_pp_embedded.png "Пример открытия платёжной формы Payment Page на странице перехода к оплате") ![](images/ecommpay/cms/magento/cms_magento_settings_card.png "Блок Card payments с параметрами для карточных платежей") - Параметр, актуальный только для блока **More payment methods via Ecommpay**: - **Payment method code** — код платёжного метода, используемого как единственный дополнительный \(по отношению к методам, для настройки работы с которыми применяются отдельные раскрывающиеся блоки\). - Если не применять этот параметр, то при выборе метода оплаты в интерфейсе веб-сервиса пользователь может выбрать вариант **More payment methods** и перейти к платёжной форме с возможностью выбрать там один из методов, доступных для инициируемого платежа через платформу Ecommpay.При этом все методы от Ecommpay, доступные для выбора непосредственно в веб-сервисе \(наряду с вариантом **More payment methods**\), оказываются доступными и в платёжной форме. - Если указать в значении этого параметра код одного из доступных методов\(в соответствии [со справочником](ru_pm_codes.md)\), то при выборе методов оплаты в интерфейсе веб-сервиса наряду с другими доступными там для выбора методами пользователь может выбрать указанный и перейти к работе с ним, минуя выбор каких-либо других методов в платёжной форме.Чтобы не допускать коллизий с таким выбором, при указании кода какого-либо метода в этом разделе также следует указывать название этого метода для отображения в веб-сервисе \(в поле **Title**\). **Прим.:** Поскольку в тестовом режиме работы плагина доступны оплаты только с прямым использованием платёжных карт, тестировать работу блока **More payment methods via Ecommpay** в таком случае можно только для метода `card`. ![](images/ecommpay/cms/magento/cms_magento_settings_pm.png "Блок More payment methods via Ecommpay с параметрами использования полной группы методов") --- # Использование плагина Ecommpay payments для CMS PrestaShop {#ru_cms_prestashop} статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS PrestaShop **На уровень выше:**[Интеграция с использованием плагинов](ru_CMS.md) ## Введение {#ru_cms_prestashop_overview} В этой статье представлена информация о работе с платёжным плагином Ecommpay payments версии 2.0.0. Этот плагин может использоваться в веб-сервисах, разработанных на базе CMS PrestaShop версий 8.1.5 и выше. Плагин Ecommpay payments устанавливается через интерфейс PrestaShop и позволяет открывать пользователям платёжную форму Payment Page от Ecommpay и обеспечивать все необходимые действия для проведения платежей, как в части взаимодействия с пользователями, так и в части взаимодействия с платёжной платформой Ecommpay, с передачей и приёмом всей необходимой информации. ![](images/ecommpay/cms/prestashop/cms_prestashop_orders_overview.svg "Административный интерфейс PrestaShop ") ![](images/unimethods/ru_pp_browser_tab.svg "Интерфейс платёжной формы Payment Page") ## Общая информация {#ru_cms_prestashop_general} ### Возможности {#section_jvy_jhc_lwb .section} При использовании плагина Ecommpay payments можно: - Оперативно встраивать в веб-сервис возможность вызова платёжной формы Payment Page от Ecommpay. Для этого достаточно всего нескольких действий в интерфейсе CMS PrestaShop. - Настраивать использование платёжных методов, доступных для работы через плагин, — с прямым использованием карт, сервисов Apple Pay и Google Pay и других альтернативных методов\(если эти методы подключены для используемого проекта\). Для этого можно использовать вкладки с параметрами использования платёжных методов, расположенные на странице настройки плагина Ecommpay payments в интерфейсе PrestaShop. - Тестировать работу платёжной формы и возможности проведения платежей. Для этого можно оформить тестовый проект в платёжной платформе Ecommpay \(что можно сделать [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\) и использовать идентификатор и ключ этого проекта. - Проводить разовые одностадийные оплатыс применением различных платёжных методов. При этом для решения всех организационных вопросови подключения платёжных методов следует обращаться к курирующему менеджеру Ecommpay. - Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина. Для этого можно использовать интерфейс PrestaShop и, если актуально, интерфейсы платёжной платформы Ecommpay \(пользовательский интерфейс Dashboard и Gate API\). Вместе с тем, при использовании интерфейсов платёжной платформы Ecommpay информация о заказах в интерфейсе PrestaShop обновляется, только если настроена отправка оповещений со стороны платёжной платформы \([подробнее](ru_dbl_projects.md)\). - Контролировать информацию о платежах, проводимых с помощью плагина. Это можно делать через интерфейс PrestaShop и, если актуально, — через Data API и пользовательский интерфейс Dashboard от Ecommpay. - Управлять заказами, оплаты по которым проводятся с помощью плагина. Для этого можно использовать интерфейс PrestaShop, который позволяет отменять такие заказы и корректировать их статусы вручную. - Настраивать параметры работы платёжной формы Payment Page, адаптируя её под специфику веб-сервиса, и применять различные возможности, обеспечиваемые со стороны Ecommpay. В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking \([подробнее](pm_openbanking.md#section_yln_qjn_ftb)\), делать доступными для пользователей повторные попытки оплаты \([подробнее](ru_PP_Try_Again.md)\) и подключать отправку пользователям уведомлений о результатах оплат \([подробнее](ru_PP_receipt_data.md)\). Такой спектр возможностей позволяет подстраиваться под различные особенности бизнеса, гибко настраивать пользовательские сценарии и обеспечивать высокие уровни конверсии платёжной формы и проходимости платежей. Для подключения и применения возможностей, предоставляемых Ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам Ecommpay. ### Схема работы {#section_wqc_ssv_szb .section} В схеме проведения оплат с использованием плагина Ecommpay payments для CMS PrestaShop задействуются пользователь, веб-сервис со встроенным в него плагином, платёжная форма Payment Page, платёжная платформа Ecommpay и платёжная среда. При этом с помощью плагина Ecommpay payments на стороне веб-сервиса обеспечиваются автоматический вызов Payment Page и автоматическое взаимодействие с платёжной платформой в соответствии с заданными параметрами работы. ![](images/universal/cms/ru_cms_workflow.svg) 1. Пользователь на стороне веб-сервиса выбирает вариант оплаты с использованием плагина Ecommpay payments. 2. На стороне веб-сервиса формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Page. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платёжной платформе выполняется обработка запроса, с проверкой его корректности. 5. В платёжной платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает итоговый запрос на оплату \(со всеми необходимыми сведениями\). 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе PrestaShop обновляется информация о заказе. 13. От платёжной платформы к Payment Page направляется информация о результате оплаты. 14. Информация о результате оплаты отображается в платёжной форме Payment Page \(если используется способ открытия платёжной формы в модальном окне или отдельной вкладке\)или на странице веб-сервиса \(если используется способ открытия платёжной формы непосредственно в веб-сервисе\). ### Варианты использования платёжной формы {#section_rtj_mwk_bgd .section} В рамках описанной общей схемы работы с плагином Ecommpay payments могут применяться разные варианты открытия платёжной формы Payment Page: - для платежей с прямым использованием карт по умолчанию используется вариант со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса\(через элемент iframe\), а также можно использовать варианты с открытием платёжной формы в модальном окне или отдельной вкладке; - для платежей альтернативными платёжными методами используется вариант открытия платёжной формы в отдельной вкладке. При использовании варианта со встраиванием платёжной формы Payment Page непосредственно в интерфейс веб-сервиса \(через элемент iframe\) пользователь указывает данные платёжной карты и подтверждает формирование заказа в CMS PrestaShop и платежа в платформе Ecommpay непосредственно на странице перехода к оплате в веб-сервисе\(с помощью кнопки **Place Order**\). При использовании вариантов открытия платёжной формы Payment Page в модальном окне или отдельной вкладке пользователь сначала подтверждает формирование заказа в CMS PrestaShop на странице перехода к оплате веб-сервиса\(с помощью кнопки **Place Order**\) и уже после этого указывает необходимые данные в открывшейся платёжной форме и подтверждает формирование платежа в платформе Ecommpay\(с помощью кнопки **Оплатить**\). ![](images/ecommpay/cms/prestashop/ru_cms_prestashop_pp_embedded.svg "Встраивание в интерфейс веб-сервиса") ![](images/ecommpay/cms/prestashop/ru_cms_prestashop_pp_popup.svg "Использование модального окна") Более подробную информацию о способах открытия Payment Page можно получить в [соответствующих статьях](ru_PP_Integration.md). ### Контроль заказов и платежей {#section_vgh_wyk_bge .section} При работе с плагином Ecommpay payments следует учитывать, что для заказов в веб-сервисе и платежей в платёжной платформе используются разные идентификаторы и статусы. Заказам на стороне веб-сервиса присваиваются порядковые номера \(например, `71`\) и статусы, ассоциированные со статусами платежей в платформе Ecommpay: - `Ecommpay: Pending` — если платёж по заказу находится в промежуточном состоянии; - `Ecommpay: Approved` — если платёж по заказу проведён; - `Ecommpay: Declined` — если платёж по заказу отклонён; - `Ecommpay: Partially refunded` — если в рамках заказа был выполнен частичный возврат средств; - `Ecommpay: Refund` — если в рамках заказа был выполнен возврат полной суммы платежа. В свою очередь, платежам на стороне платёжной платформы присваиваются идентификаторы, включающие в себя префикс `pt_` и десятизначный код \(например, `pt_64ca3135cf`\), и статусы в соответствии с моделью проведения платежей Ecommpay \([подробнее](ru_platform_payment_model.md)\). С вопросами о соответствии между идентификаторами и статусами заказов и платежей можно обращаться к курирующему менеджеру Ecommpay. ## Установка {#ru_cms_prestashop_installation} Чтобы начать работу с плагином Ecommpay payments версии 2.0.0, его необходимо установить. Если ранее использовалась одна из предыдущих версий этого плагина, перед его обновлением рекомендуется выполнить следующее: 1. Скопировать значения параметров работы плагина для их последующего указания при работе с новой версией. Это связано с тем, что при обновлении плагина указанные ранее данные не сохраняются. 2. Деактивировать предыдущую версию плагина. Это можно сделать через список установленных плагинов в интерфейсе PrestaShop, с помощью кнопки **Uninstall**. Для установки плагина необходимо скачать его [zip-архив](https://github.com/ITECOMMPAY/ecommpay-prestashop) и выполнить следующие действия в интерфейсе PrestaShop: 1. Выбрать раздел **Modules** и пункт **Module Manager** в секции **IMPROVE** на панели навигации. 2. Щёлкнуть кнопку **Upload a module** на странице **Module Manager** и выбрать предварительно скачанный zip-архив плагина. 3. Дождаться завершения загрузки и автоматической установки плагина. После выполнения этих действий на странице **Module Manager** можно найти панель плагина Ecommpay payments и приступить к работе с ним. ![](images/ecommpay/cms/prestashop/cms_prestashop_installation.png "Страница Module Manager с панелью плагина в интерфейсе PrestaShop") ## Тестирование {#ru_cms_prestashop_testing} ### Общая информация {#ru_cms_prestashop_testing_overview} Тестировать работу плагина и проводить тестовые платежи по различным платёжным сценариямбез реального списания средств можно через тестовую среду платёжной платформы Ecommpay. Подключиться к платформе можно, используя соответствующую форму [на основном сайте компании](https://ecommpay.com/apply-now/) иполученные идентификатор и ключ тестового проекта. Также необходимо сообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина от Ecommpay, и валюту проведения платежей. Следует учитывать, что при использовании тестовой среды платёжной платформы Ecommpay плагин подключается к веб-сервису и становится доступен пользователям как вариант оплаты. Поэтому в тех случаях, когда плагин подключается к работающему веб-сервису, рекомендуется выполнять тестирование в период низкой нагрузки и предупреждать пользователей о проводимых работах. ### Настройка параметров {#ru_cms_prestashop_testing_setup} Чтобы подготовить плагин к тестированию, необходимо определить предпочтительный вариант тестирования и настроить плагин в интерфейсе PrestaShop. Для этого следует: 1. Перейти к параметрам работы плагина в интерфейсе PrestaShop. Для этого следует: 1. Выбрать раздел **Modules** и пункт **Module Manager** в секции **IMPROVE** на панели навигации. 2. Выполнить поиск плагина Ecommpay payments на открывшейся странице и щёлкнуть кнопку **Configure** в соответствующей строке. 2. Задать основные параметры работы плагина на вкладке **General Settings**и сохранить изменения, щёлкнув кнопку **Save Settings**: - **Project ID** — идентификатор тестового проекта. - **Secret key** — ключ тестового проекта. - **Language** — язык отображения платёжной формы. ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Вкладка с основными параметрами работы плагина") 3. Задать общие параметры использования платёжных методови сохранить изменения, щёлкнув кнопку **Save Settings**: - **Enabled** — возможность подключить платёжный метод для работы через плагин. Для подключения метода следует установить флажок. По умолчанию флажок снят. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе. - **Description** — текст, отображаемый пользователям при выборе конкретного платёжного метода. **Прим.:** При необходимости поля **Title** и **Description** могут использоваться для предупреждения пользователей о работе плагина в тестовом режиме. 4. При необходимости задать остальные параметры использования платёжных методов \([подробнее](ru_cms_prestashop.md)\) и сохранить изменения, щёлкнув кнопку **Save Settings** на каждой вкладке. ### Проведение тестовых оплат {#ru_cms_prestashop_testing_purchase} В рамках работы с плагином можно проводить тестовые оплаты в веб-сервисе и получать информацию о них через интерфейс PrestaShopв подразделе **Orders** одноимённого раздела. При этом можно использовать специальные платёжные реквизиты, позволяющие тестировать заданные сценарии работы. Чтобы тестировать проведение карточных платежей, можно использовать номера тестовых карт. При этом для тестирования по заданным кратчайшим сценариям\(без эмулирования аутентификации 3‑D Secure\) можно использовать следующие номера карт: - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей\(в том числе с аутентификацией 3‑D Secure\), представленных в статье [Номера тестовых карт](ru_test_cards.md). Чтобы тестировать проведение платежей с использованием альтернативных методов\(при подключении соответствующих методов через курирующего менеджера или техническую поддержку и при использовании тестовой среды платёжной платформы\), можно использовать информацию, представленную в статье [Возможности тестирования](ru_pm_testing.md), а также в разделах о тестировании отдельных методов. ### Выполнение тестовых возвратов {#ru_cms_prestashop_testing_refund} #### Введение {#section_k1j_3bk_kbc .section} После проведения тестовых оплат можно тестировать выполнение возвратовчерез интерфейс PrestaShop, и если актуально, через интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay.Выполнять возвраты можно для оплат, которые удовлетворяют двум условиям. Во-первых, это должны быть оплаты такими методами, для которых поддерживается возможность возвратов. Во-вторых, это должны быть проведённые оплаты, по которым не были возвращены полные суммы — на стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы Ecommpay и интерфейс PrestaShop. Также можно иметь в виду, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочей среде. #### Обеспечение синхронизации данных {#section_wnj_kbk_kbc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о заказах в интерфейсе PrestaShop обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс PrestaShop, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе PrestaShop. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS PrestaShop, на URL, отображаемый на странице с параметрами работы плагина \(в формате `https:///en/module/Ecommpay/callback`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. #### Процедуры {#section_efy_1ck_kbc .section} Выполнять возвраты можно для проведённых оплат, по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы Ecommpay и интерфейс PrestaShop. Чтобы выполнить возврат через интерфейс PrestaShop, следует: 1. Перейти к карточке заказа, в рамках которого необходимо выполнить возврат. Для этого следует выбрать пункт **Orders** в разделе **Orders** секции **SELL** и щёлкнуть строку требуемого заказа. 2. Инициировать возврат. Для этого следует: 1. Раскрыть панель **Products**, щёлкнув кнопку **Partial refund**. 2. Указать сумму возврата в поле **Amount \(Tax included\)** и установить флажок **Refund via Ecommpay**. 3. Щёлкнуть кнопку **Partial refund** в правой нижней части панели **Products**. 3. Убедиться в выполнении возврата. Для этого можно проверить, что статус заказа изменился на `Ecommpay: Partially refunded` \(при частичном возврате\) или `Ecommpay: Refund` \(при полном возврате\). ![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Панель Products с возможностью выполнения возвратов в карточке заказа") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ## Использование {#ru_cms_prestashop_usage} ### Общая информация {#ru_cms_prestashop_usage_overview} Для проведения платежей с реальным списанием средств, прежде всего, необходимо решить все организационные вопросы по взаимодействию с Ecommpay\(подать заявку на подключение, предоставить всю необходимую информацию и получить от Ecommpay уведомление о возможности проводить платежи, а также идентификатор и секретный ключ рабочего проекта\). Также необходимосообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина Ecommpay payments,и валюту проведения платежей. После этого можно указать в параметрах работы плагина идентификатор и ключ рабочего проекта, полученные от Ecommpay, и задать другие необходимые параметры\(или проверить их актуальность для рабочего применения\). Если впоследствии потребуется приостановить работу плагина, можно отключить его платёжные методы. Кроме того, при необходимости дополнительного тестирования, например при подключении новых функций, можно переключать плагин на работу с тестовым проектом. ### Настройка параметров {#ru_cms_prestashop_usage_setup} Чтобы настроить параметры работы плагина, следует: 1. Перейти к параметрам работы плагина в интерфейсе PrestaShop. Для этого следует: 1. Выбрать раздел **Modules** и пункт **Module Manager** в секции **IMPROVE** на панели навигации. 2. Выполнить поиск плагина Ecommpay payments на открывшейся странице и щёлкнуть кнопку **Configure** в соответствующей строке. 2. Задать основные параметры работы плагина на вкладке **General Settings**и сохранить изменения, щёлкнув кнопку **Save Settings**: - **Project ID** — идентификатор рабочего проекта. - **Secret key** — ключ рабочего проекта. - **Language** — язык отображения платёжной формы. ![](images/ecommpay/cms/prestashop/cms_prestashop_general.png "Вкладка с основными параметрами работы плагина") 3. Задать общие параметры использования платёжных методови сохранить изменения, щёлкнув кнопку **Save Settings**: - **Enabled** — возможность подключить платёжный метод для работы через плагин. Для подключения метода следует установить флажок. По умолчанию флажок снят. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе. - **Description** — текст, отображаемый пользователям при выборе конкретного платёжного метода. **Прим.:** Если при тестировании плагина в полях **Title** и **Description** использовались соответствующие предупреждения, при переходе к использованию рабочего проекта в плагине важно их убрать. 4. При необходимости задать остальные параметры использования платёжных методов \([подробнее](ru_cms_prestashop.md)\) и сохранить изменения, щёлкнув кнопку **Save Settings** на каждой вкладке. ### Проведение оплат {#ru_cms_prestashop_usage_purchase} Если веб-сервис и плагин корректно настроены, оплаты проводятся автоматически.При этом важно обеспечивать сбор всех необходимых данных на стороне веб-сервиса. **Прим.:** Расширен набор сведений, необходимых для аутентификации 3‑D Secure при проведении карточных оплат. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты. При возникновении вопросов или проблем с проведением оплат можно обращаться к специалистам технической поддержки Ecommpay. ### Выполнение возвратов {#ru_cms_prestashop_usage_refund} #### Введение {#section_k1j_3bk_kbc .section} После проведения оплат можно выполнять возвраты по нимчерез интерфейс PrestaShop, и если актуально, через интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе PrestaShop должны быть в статусах `Ecommpay: Approved` или `Ecommpay: Partially refunded`, а платежи на стороне платёжной платформы Ecommpay — в статусах `success`, `partially reversed` или `partially refunded`. Также можно иметь в виду, что все возможности и процедуры по работе с возвратами в рабочем режиме соответствуют тем, которые доступны в тестовом режиме. #### Обеспечение синхронизации данных {#section_f3t_f24_4bc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о заказах в интерфейсе PrestaShop обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс PrestaShop, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе PrestaShop. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS PrestaShop, на URL, отображаемый на странице с параметрами работы плагина \(в формате `https:///en/module/Ecommpay/callback`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. #### Процедуры {#section_lqm_3f4_4bc .section} Выполнять возвраты можно для проведённых оплат, по которым не были возвращены их полные суммы.На стороне платёжной платформы Ecommpay таким оплатам соответствуют статусы `success`, `partially reversed` или `partially refunded`. В свою очередь, контролировать выполнение возвратов можно через интерфейсы платформы Ecommpay и интерфейс PrestaShop. Чтобы выполнить возврат через интерфейс PrestaShop, следует: 1. Перейти к карточке заказа, в рамках которого необходимо выполнить возврат. Для этого следует выбрать пункт **Orders** в разделе **Orders** секции **SELL** и щёлкнуть строку требуемого заказа. 2. Инициировать возврат. Для этого следует: 1. Раскрыть панель **Products**, щёлкнув кнопку **Partial refund**. 2. Указать сумму возврата в поле **Amount \(Tax included\)** и установить флажок **Refund via Ecommpay**. 3. Щёлкнуть кнопку **Partial refund** в правой нижней части панели **Products**. 3. Убедиться в выполнении возврата. Для этого можно проверить, что статус заказа изменился на `Ecommpay: Partially refunded` \(при частичном возврате\) или `Ecommpay: Refund` \(при полном возврате\). ![](images/ecommpay/cms/prestashop/cms_prestashop_info_refund.png "Панель Products с возможностью выполнения возвратов в карточке заказа") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ### Контроль платежей и заказов {#ru_cms_prestashop_usage_monitoring} Контролировать информацию о платежах, проводимых с использованием плагина Ecommpay payments, и соответствующих заказах можно через интерфейс PrestaShop, используя инструменты подраздела **Orders** в одноимённом разделе. При этом более подробную информацию о платежах и возвратах можно получать через интерфейс Dashboard \([подробнее](ru_dbl_payments.md)\) и Data API \([подробнее](ru_dbl_using_api.md)\) от Ecommpay. При работе с интерфейсом PrestaShop в подразделе **Orders** отображается реестр заказов с основными сведениями о каждом из них, а также с возможностями поиска, фильтрации, перехода к карточкам отдельных заказов и выполнения различных действий. ![](images/ecommpay/cms/prestashop/cms_prestashop_orders.png "Реестр заказов в интерфейсе PrestaShop") Для перехода к карточке конкретного заказа можно щёлкнуть его строку \(или кнопку ![](images/universal/cms/prestashop/cms_prestashop_icon_view.png)\) в реестре. Через карточки, в частности,можнополучать развёрнутые сведения озаказах \(например, о пользователях, приобретённых продуктах и способах доставки\) и платежах, а также инициировать выполнение возвратов. Для получения информации о платеже, инициированном через плагин от Ecommpay, следует использовать секцию **Payment**.В этой секции отображаются информация о сумме и валюте платежа, а также другие актуальные сведения. При этом следует учитывать, что отдельные сведения, касающиеся состояния и деталей проведения платежа \(в частности, информация о выбранном пользователем платёжном методе\), актуализируются по итогам получения оповещений от платёжной платформы. ![](images/ecommpay/cms/prestashop/cms_prestashop_order_tab.png "Карточка заказа в интерфейсе PrestaShop") Более подробную информацию о работе с заказами можно получить с помощью кнопки **Help** в подразделе **Orders** одноимённого раздела в интерфейсе PrestaShop. ## Параметры использования платёжных методов {#ru_cms_prestashop_methods} При работе с плагином от Ecommpay в интерфейсе PrestaShop можно настраивать использование различных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать на отдельных вкладках страницы с параметрами работы плагина— таких как **Card Settings** \(с параметрами для оплат с прямым использованием карт\), **Apple Pay** \(с параметрами для оплат с использованием сервиса Apple Pay\), **Google Pay** \(с параметрами для оплат с использованием сервиса Google Pay\) и **More Methods** \(с параметрами для оплат с использованием остальных альтернативных методов\). На вкладках для настройки использования платёжных методов можно задавать следующие параметры: - Общие параметры: - **Enabled** — возможность подключить платёжный метод для работы через плагин. Для подключения метода следует установить флажок. По умолчанию флажок снят. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в веб-сервисе. - **Description** — текст, отображаемый пользователям при выборе конкретного платёжного метода. - Параметр, актуальный только для вкладки **Card Settings**: - **Display mode** — способ открытия платёжной формы Payment Page. Можно выбрать один из следующих способов: - **Popup** — открытие в модальном окне; - **Redirect** — открытие в виде отдельной HTML-страницы; - **Embedded** — открытие в элементе iframe. При установке плагина или обновлении его версии этот способ настроен по умолчанию. ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_card.png "Вкладка Card Settings с параметрами для платежей с прямым использованием карт") В случае, если платёжная форма открыта в элементе iframe\(способ **Embedded**\), при выборе пользователем оплаты с использованием платёжной карты в списке вариантов для оплаты ему отображается платёжная форма Payment Page, с адаптацией под стандартное оформление страницы перехода к оплате в веб-сервисе и без кнопки для подтверждения согласия на оплату. В открывшейся форме пользователь может выбрать реквизиты платёжной карты \(если они были сохранены ранее\) или указать их, а затем — подтвердить готовность провести оплату с помощью кнопки для перехода к оплате на странице веб-сервиса. При выборе других платёжных методов пользователь перенаправляется на последующие страницы. ![](images/ecommpay/cms/prestashop/ru_cms_prestashop_pp_embedded.png "Пример открытия платёжной формы Payment Page в элементе iframe") - Параметр, актуальный только для вкладки **More Methods**: - **Payment method code** — код платёжного метода, используемого как единственный дополнительный \(по отношению к методам, для настройки работы с которыми применяются отдельные вкладки\). - Если не применять этот параметр, то при выборе метода оплаты в интерфейсе веб-сервиса пользователь может выбрать вариант, название которого указано в поле **Title** \(по умолчанию используется вариант **More payment methods**\) и перейти к платёжной форме с возможностью выбрать там один из методов, доступных для инициируемого платежа через платформу Ecommpay.При этом все методы от Ecommpay, доступные для выбора непосредственно в веб-сервисе \(наряду с вариантом **More payment methods**\), оказываются доступными и в платёжной форме. - Если указать в значении этого параметра код одного из доступных методов\(в соответствии [со справочником](ru_pm_codes.md)\), то при выборе методов оплаты в интерфейсе веб-сервиса наряду с другими доступными там для выбора методами пользователь может выбрать указанный метод и перейти к работе с ним, минуя выбор каких-либо других методов в платёжной форме.Чтобы не допускать коллизий с таким выбором, при указании кода какого-либо метода в этом разделе также следует указывать название этого метода для отображения в веб-сервисе \(в поле **Title**\). ![](images/ecommpay/cms/prestashop/cms_prestashop_settings_pm.png "Вкладка More Methods с параметрами для остальных альтернативных методов") --- # Использование плагина Ecommpay Payments для CMS WordPress {#ru_CMS__wordpress} статья о порядке применения плагина для встраивания Payment Page в сайты на базе CMS WordPress с установленным плагином WooCommerce **На уровень выше:**[Интеграция с использованием плагинов](ru_CMS.md) ## Введение {#ru_cms_wordpress_overview} В этой статье представлена информация о работе с платёжным плагином Ecommpay Paymentsверсии 5.0. Плагин этой версии расширяет возможности плагина WooCommerce для веб-сервисов, разработанных на базе CMS WordPress, с соблюдением следующих условий: - CMS WordPress версии 6.2 или выше, - плагин WooCommerce версии 8.2 или выше, - язык PHP версии 7.4 или выше. Плагин Ecommpay Payments устанавливается через интерфейс WordPress и позволяет открывать пользователям платёжную форму Payment Page от Ecommpay и обеспечивать все необходимые действия для проведения платежей, как в части взаимодействия с пользователями, так и в части взаимодействия с платёжной платформой Ecommpay, с передачей и приёмом всей необходимой информации. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_methods.png "Административный интерфейс WordPress") ## Общая информация {#ru_cms_wordpress_general} ### Возможности {#section_jvy_jhc_lwb .section} При использовании плагина Ecommpay Payments можно: - Оперативно встраивать в веб-сервис возможность вызова платёжной формы Payment Page от Ecommpay. Для этого достаточно всего нескольких действий в интерфейсе CMS WordPress. - Настраивать использование отдельных платёжных методов, подключённых в рамках проекта мерчанта. Для этого можно использовать вкладки с параметрами использования платёжных методов, расположенные в карточке плагина интерфейса WordPress. - Тестировать работу платёжной формы и возможности проведения платежей. Для этого можно оформить тестовый проект в платёжной платформе Ecommpay \(что можно сделать [через заявку](https://ecommpay.com/sign-up/) на основном сайте компании\) и использовать идентификатор и ключ этого проекта. - Проводить разовые оплаты в одну или две стадии. В рамках одного проекта можно выбрать один из вариантов проведения оплат: с незамедлительным списанием средств \(в одну стадию\) с использованием любого из подключённых платёжных методов либо с предварительной блокировкой и последующим списанием средств \(в две стадии\) с использованием любого из методов, для которого поддерживается проведение таких оплат через Payment Page. - Регистрировать и проводить повторяемые оплаты \(*по подпискам*\)с прямым использованием платёжных карт и с применением методов Apple Pay и Google Pay — при использовании в веб-сервисе дополнения [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/). При этом можно управлять свойствами таких оплат \(в частности, суммой и периодичностью списаний, а также длительностью бесплатного периода подписки\), информировать пользователей о связанных со списаниями событиях и объединять разные оплаты в общие заказы. - Выполнять частичные и полные возвраты средств по оплатам, проведённым с помощью плагина. Это можно делать в рамках тех методов, для которых поддерживается выполнение возвратов, инициируя операции через интерфейс WordPress и, если актуально, через интерфейсы платёжной платформы Ecommpay \(пользовательский интерфейс Dashboard и Gate API\). Вместе с тем, при инициировании возвратов через интерфейсы платёжной платформы Ecommpay информация о платежах в интерфейсе WordPress обновляется, только если настроена отправка оповещений со стороны платёжной платформы \([подробнее](ru_dbl_projects.md)\). - Контролировать информацию о платежах, проводимых с помощью плагина. Для этого можно использовать интерфейс WordPress, и если необходимо, — интерфейс Dashboard от Ecommpay, с синхронизацией информации между этим интерфейсом и интерфейсом WordPress. - Управлять заказами, оплаты по которым проводятся с помощью плагина, через интерфейс WordPress. При этом можно отменять и удалять такие заказы и корректировать их статусы вручную. - Настраивать параметры работы платёжной формы Payment Page, адаптируя её под специфику веб-сервиса, и применять различные возможности, обеспечиваемые со стороны Ecommpay. В частности, можно применять процедуру подтверждения зачислений при работе с платёжными методами Open Banking, делать доступными для пользователей повторные попытки оплаты \([подробнее](ru_PP_Try_Again.md)\) и подключать отправку пользователям уведомлений о результатах оплат \([подробнее](ru_PP_receipt_data.md)\). Для подключения таких возможностей следует обращаться к специалистам технической поддержки Ecommpay. - Использовать различные возможности, обеспечиваемые со стороны разработчиков плагина WooCommerce. В частности, можно регулировать применение этого плагина \(и связанного с ним плагина Ecommpay Payments\) в разных странах \([подробнее](https://woocommerce.com/document/setting-up-shipping-zones/)\). Такой широкий спектр возможностей позволяет подстраиваться под различные особенности бизнеса, гибко настраивать пользовательские сценарии и обеспечивать высокий уровень конверсии платёжной формы и проходимости платежей. Для подключения и применения возможностей, предоставляемых Ecommpay, следует обращаться к технической документации на этом портале и, по мере необходимости, к специалистам Ecommpay. С вопросами о применении различных возможностей для плагина WooCommerce можно обращаться к документации [на соответствующем портале](https://woocommerce.com/documentation/). ### Схемы работы {#section_lkg_mhc_lwb .section} В схемах проведения оплат в одну и две стадии с использованием плагина Ecommpay Payments задействуются пользователь, веб-сервис со встроенными в него плагинами WooCommerce и Ecommpay Payments, платёжная форма Payment Page, платёжная платформа и платёжная среда. При этом с помощью плагина на стороне веб-сервиса обеспечиваются автоматический вызов Payment Page и автоматическое взаимодействие с платёжной платформой в соответствии с заданными параметрами работы. При работе *с одностадийными оплатами*на основании одного исходного запроса выполняются разовый перевод средств от пользователя к мерчанту и отправка к веб-сервису оповещения о результате проведения платежа. ![](images/universal/cms/ru_cms_workflow.svg) 1. Пользователь на стороне веб-сервиса открывает страницу перехода к оплате интерфейса WooCommerceи выбирает вариант оплаты с помощью одного из платёжных методов, доступных через плагин Ecommpay Payments. Как правило, при этом в веб-сервисе автоматически формируется соответствующий заказ. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Pageс учётом выбранного пользователем метода. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page или к перенаправлению пользователя к стороннему сервису в соответствии с параметрами вызова. 6. Пользователю отображается платёжная форма или выполняется его перенаправление к стороннему сервису— в соответствии с тем, что актуально для выбранного метода. 7. Пользователь выполняет необходимые действия для оплаты и подтверждает готовность провести оплату. 8. В платёжную платформу поступает итоговый запрос на оплату \(со всеми необходимыми сведениями\). При перенаправлениях к сторонним сервисам это может обеспечиваться ранее, на шаге 5. 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате оплаты. 12. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе WordPress обновляется информация о заказе и платеже. 13. От платёжной платформы к Payment Page направляется информация о результате оплаты. 14. Информация о результате оплаты отображается пользователю: в веб-сервисе мерчанта, на странице с информацией об оплате заказа интерфейса WooCommerce, \(в общем случае\) или в платёжной форме Payment Page \(если подключена возможность повторных попыток проведения платежей\). При работе *с двухстадийными оплатами* на основании исходного запроса \(на первой стадии\) выполняется блокировка средств пользователя, а затем \(на второй стадии\) на основании подтверждающего запроса или автоматически по истечении заданного срока выполняется списание заблокированных средств или отмена блокировки. При этом на каждой стадии к веб-сервису отправляется оповещение с информацией о соответствующем результате. ![](images/ecommpay/cms/wordpressplugin/ru_cms_workflow_auth.svg) 1. Пользователь на стороне веб-сервиса открывает страницу перехода к оплате интерфейса WooCommerceи выбирает вариант оплаты с помощью одного из платёжных методов, доступных через плагин Ecommpay Payments. Как правило, при этом в веб-сервисе автоматически формируется соответствующий заказ. 2. С помощью плагина автоматически формируется и отправляется в платёжную платформу Ecommpay запрос на открытие платёжной формы Payment Pageс учётом выбранного пользователем метода. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платформе выполняется обработка запроса, с проверкой его корректности. 5. В платформе обеспечивается подготовка к открытию Payment Page. 6. Пользователю отображается платёжная форма. 7. Пользователь выполняет необходимые действия и подтверждает готовность провести оплату. 8. В платёжную платформу поступает запрос на выполнение блокировки средств. 9. Запрос передаётся в платёжную среду. 10. В платёжной среде выполняется обработка платежа и блокировка средств пользователя. При этом, если необходимо, обеспечивается выполнение дополнительных действий со стороны платформы и пользователя \(например, для аутентификации 3‑D Secure\). 11. Из платёжной среды к платёжной платформе направляется информация о результате блокировки средств. 12. От платёжной платформы к веб-сервису направляется оповещение о результате блокировки. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе WordPress обновляется статус платежа и заказа. 13. От платёжной платформы к Payment Page направляется информация о результате блокировки. 14. Информация о результате блокировки отображается пользователю в платёжной форме Payment Page. 15. После того как подтверждается необходимость списания средств, специалист мерчанта инициирует это списание, в результате чего \(с помощью плагина\) запрос на списание средств поступает в платёжную платформу и обрабатывается в ней. 16. Запрос передаётся в платёжную среду. 17. В платёжной среде выполняется обработка платежа. 18. Из платёжной среды к платёжной платформе направляется информация о результате списания. 19. От платёжной платформы к веб-сервису направляется оповещение о результате списания. Оно автоматически обрабатывается с помощью плагина, благодаря чему в интерфейсе WordPress обновляется информация о платеже и заказе. 20. Пользователь уведомляется о результате списания средствами веб-сервиса. ### Способы открытия платёжной формы {#section_lss_ggm_djc .section} Для взаимодействия с пользователями при проведении одностадийных оплат и блокировке средств в рамках двухстадийных оплат допустимы три способа работы: - `Redirect` — с открытием платёжной формы в отдельной вкладке браузера\([подробнее](ru_PP_method_NewTab.md)\). Этот способ применим для всех платёжных методов и активируется по умолчанию при установке плагина, при обновлениях его версии и в тех случаях, когда другой выбранный способ не применим. - `Popup` — с открытием платёжной формы в модальном окне поверх интерфейса веб-сервиса\([подробнее](ru_PP_method_ModalWindow.md)\). Этот способ применим для большинства платёжных методов, а в тех случаях, когда он не может быть использован, он заменяется способом `Redirect`. - `Embedded` — со встраиванием платёжной формы непосредственно в интерфейс веб-сервиса\(через элемент iframe; [подробнее](ru_pp_microframe_solution.md)\). Этот способ применим только для классических карточных платежей при условии предварительного согласования со специалистами технической поддержки Ecommpay. При открытии платёжной формы в элементе iframe используется облегчённая редакция платёжной формы Payment Page, без кнопки для подтверждения согласия на оплату.Форма отображается в блоке для оплаты с прямым использованием платёжной карты, и пользователь может выбрать в ней реквизиты платёжной карты \(если они были сохранены ранее\) или ввести их, а затем — подтвердить готовность провести оплату с помощью соответствующей кнопки в пользовательском интерфейсе плагина WooCommerce. При выборе других платёжных методов в таком варианте работы пользователь перенаправляется к платёжной форме в виде отдельной страницы\(способом `Redirect`\). ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_redirect.svg "Payment Page в отдельной вкладке браузера") ![](images/ecommpay/cms/wordpressplugin/cms_popup.svg "Payment Page в модальном окне") ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_embedded.svg "Payment Page в элементе iframe интерфейса веб-сервиса") Настраивать способ открытия платёжной формы можно отдельно для каждого платёжного метода, через карточку плагина\([подробнее](ru_CMS__wordpress.md)\). ### Контроль заказов и платежей {#section_xmd_4gm_djc .section} При работе с плагином Ecommpay Payments следует учитывать, что для заказов в веб-сервисе и платежей в платёжной платформе используются разные идентификаторы и статусы. Порядок формирования заказа и платежа зависит от способа открытия платёжной формы и использования повторных попыток проведения одного и того же платежа. - Если для открытия платёжной формы используется способ `Embedded`\(с элементом iframe; [подробнее](ru_pp_microframe_solution.md)\), то и заказ, и платёж формируются только после подтверждения пользователем готовности провести оплату. В таком случае идентификатор платежа формируется из префикса `wp_` и произвольной последовательности в тринадцать символов\(например, `wp_ert12h2t1o270`\). При этом каждая повторная попытка оплатить заказ приводит к формированию нового заказа и нового платежа. - Если для открытия платёжной формы используется любой другой способ\(кроме `Embedded`\), то заказ формируется после перехода пользователя к оплате и вызова платёжной формы, а платёж — после подтверждения готовности провести оплату в интерфейсе платёжной формы. В таком случае идентификатор платежа формируется из номера заказа и номера попытки оплатить этот заказ в веб-сервисе\(например, для второй попытки оплатить заказ под номером `123` актуален идентификатор `123_2`\). Если при этом используется возможность повторных попыток проведения платежей, последняя цифра в идентификаторе платежа всегда равна единице, поскольку все повторные попытки выполняются в рамках одного платежа \(так, для заказа под номером `123` независимо от числа попыток в рамках платежа актуален идентификатор `123_1`\). Статусы заказов и платежей также определяются по-разному. Оплатам, проводимым по представленным схемам через платёжную платформу Ecommpay, присваиваются статусы в соответствии с моделью проведения платежей Ecommpay \([подробнее](ru_platform_payment_model.md)\), а заказам, формируемым на стороне веб-сервиса — в соответствии с моделью выполнения заказов WooCommerce \([подробнее](https://woocommerce.com/document/managing-orders/#visual-diagram-to-illustrate-order-statuses)\).Контролировать такие статусы и другую информацию о платежах и заказах можно в разделах интерфейса WordPress: **Orders** \(для разовых оплат\) и **Subscriptions** \(для повторяемых оплат\). С вопросами о соответствии статусов платежей и заказов можно обращаться к курирующему менеджеру Ecommpay. ## Установка {#ru_cms_wordpress_installation} ### Общая информация {#section_bfh_xsl_xwb .section} Чтобы начать работу с плагином Ecommpay Payments версии 5.0, его необходимо установить. При этом, если ранее использовалась одна из предыдущих версий этого плагина, такую версию рекомендуется предварительно деактивировать\(это можно сделать через список установленных плагинов в интерфейсе WordPress\). Установить плагин можно через интерфейс WordPress двумя способами — непосредственно *через магазин плагинов* WordPress \(без предварительного скачивания файла плагина\) или*с помощью функции загрузки плагинов* в интерфейсе \(предварительно скачав файл\). Скачать файл плагина можно [из каталога плагинов](https://wordpress.org/plugins/ecommpay-payments/) или [на портале GitHub](https://github.com/ITECOMMPAY/woocommerce-ecommpay). **Внимание:** Если до установки плагина использовалась и не была деактивирована одна из его предыдущих версий, то после установки в интерфейсе WordPress может отображаться уведомление о необходимости обновить параметры работы. В таком случае необходимо щёлкнуть кнопку **Run the updater** и дождаться обновления параметров, иначе ранее настроенные параметры могут не сохраниться. ### Установка через каталог плагинов {#section_dlj_2tl_xwb .section} Для установки через каталог плагинов следует перейти в интерфейс WordPress и выполнить следующие действия: 1. Выбрать раздел **Plugins**на панели навигации и пункт **Add New Plugin**в появившемся меню. 2. Выполнить поиск плагина Ecommpay Payments от Ecommpayна открывшейся странице. Для этого стоит использовать поисковую строку в правой части страницы, а в результатах поиска следует проверить, что плагин предоставляется со стороны Ecommpay \(об этом свидетельствует надпись **By Ecommpay**\). 3. Щёлкнуть кнопку **Install now** \(или кнопку **Update Now**, если использовалась более ранняя версия плагина\) на этой панели и дождаться завершения установки. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_shop_installation.png "Использование страницы CMS WordPress для установки плагина через каталог") 4. Активировать плагин с помощью кнопки **Activate**, которая отображается вместо кнопки **Install now** \(или кнопки **Update Now**\) после установки. 5. Если выполняется обновление плагина для уже работающего веб-сервиса и обновляемая или деактивированная ранее версия плагина была подключённой — убедиться, что плагин не был автоматически подключён к веб-сервису при активировании\(во избежание доступности плагина пользователям до настройки параметров его работы\). Для этого следует: 1. Перейти на вкладку **Payments** в подразделе **Settings** раздела **WooCommerce**. 2. Найти в столбце **Method**платёжные методы для работы с Ecommpay и убедиться, чтов строках для всех методов переключатель **Enable** выключен \(и выключить его, если это необходимо\). **Прим.:** Если ранее использовалась одна из предыдущих версий плагина, обновить плагин до новой версии можно также через список установленных плагинов в интерфейсе WordPress \(в подразделе **Installed Plugins** раздела **Plugins**\). ### Установка с помощью функции загрузки {#section_lv4_htl_xwb .section} Для установки с помощью функции загрузки плагинов следует перейти в интерфейс WordPress и выполнить следующие действия: 1. Выбрать раздел **Plugins**на панели навигации и пункт **Add New Plugin**в появившемся меню. 2. Щёлкнуть кнопку **Выберите файл**на открывшейся странице. ![](images/universal/cms/wordpressplugin/cms_wordpress_installation.png "Использование страницы CMS WordPress для установки плагина через функцию загрузки") 3. Выбрать предварительно скачанный zip-архив плагина. 4. Щёлкнуть кнопку **Install Now** и дождаться завершения установки. 5. Щёлкнуть кнопку **Activate Plugin** для активации плагина \(если плагин ещё не был установлен в веб-сервисе\)или кнопку **Replace current with uploaded** для обновления его версии\(если плагин уже был установлен\). **Прим.:** При попытке обновить плагин в интерфейсе WordPress может отображаться уведомление о невозможности обновления и в списке установленных плагинов могут отображаться обе версии — предыдущая и новая. Это может быть вызвано тем, что названия zip-архивов с предыдущей и новой версиями отличаются. В таком случае для корректной работы плагина следует деактивировать и удалить предыдущую версию и активировать новую. 6. Если выполняется обновление плагина для уже работающего веб-сервиса и обновляемая или деактивированная ранее версия плагина была подключённой — убедиться, что плагин не был автоматически подключён к веб-сервису при активировании \(во избежание доступности плагина пользователям до настройки параметров его работы\). Для этого следует: 1. Перейти на вкладку **Payments** в подразделе **Settings** раздела **WooCommerce**. 2. Найти в столбце **Method**платёжные методы для работы с Ecommpay и убедиться, что в строках для всех методов переключатель **Enable** выключен \(и выключить его, если это необходимо\). 7. Если в интерфейсе WordPress отображается уведомление о необходимости обновить параметры работы плагина, щёлкнуть кнопку **Run the updater** и дождаться обновления параметров. ## Тестирование {#ru_cms_wordpress_testing} ### Общая информация {#ru_cms_wordpress_testing_overview} Тестировать работу плагина Ecommpay Payments и проводить тестовые платежи по различным платёжным сценариям без реального списания средств можно через тестовую среду платёжной платформы Ecommpay.Подключиться к платформе можно в течение нескольких минут, используя соответствующую форму [на основном сайте компании](https://ecommpay.com/sign-up/) и полученные идентификатор и ключ тестового проекта. Также необходимо сообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина, и валюту проведения платежей. Следует учитывать, что при использовании тестовой среды платёжной платформы Ecommpay плагин подключается к веб-сервису и становится доступен пользователям как вариант оплаты. Поэтому в тех случаях, когда плагин подключается к работающему веб-сервису, рекомендуется выполнять тестирование в период низкой нагрузки и предупреждать пользователей о проводимых работах. ### Настройка параметров {#ru_cms_wordpress_testing_setup} Чтобы подготовить плагин к тестированию, следует: 1. Открыть карточку плагина в интерфейсе WordPress. Для этого следует: 1. Перейти на вкладку **Payments** в подразделе **Settings** раздела **WooCommerce**. 2. Найти в столбце **Method** один из настроенных платёжных методов для работы с Ecommpay и щёлкнуть кнопку **General settings** в соответствующей строке. 2. Задать основные параметры работы плагина на вкладке **General**: - **Project ID** — идентификатор тестового проекта. - **Secret Key** — ключ тестового проекта для взаимодействия с платформой. - **Purchase type** — вариант проведения оплат: - **Sale \(one-step purchase\)** — в одну стадию \(с незамедлительным списанием средств\); - **Auth \(two-step purchase\)** — в две стадии \(с предварительной блокировкой и последующим списанием средств\). - **Automatic cancellation of payments** — автоматическая отмена блокировки средств в рамках двухстадийных оплат при отмене соответствующих заказов. Для подключения этой возможности, следует установить флажок **Enable**. В таком случае при переводе заказа в статус **Cancelled** двухстадийная оплата в рамках этого заказа автоматически отклоняется. - **Language** — язык отображения платёжной формы. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_general.png "Вкладка General с основными параметрами подключения") 3. При необходимости задать дополнительные параметры работы плагина. Для этого на вкладке **General** необходимо щёлкнуть ссылку **Advanced settings** и задать параметры в секциях **Transaction Cache** и **Shop Admin Setup**: - **Enable Caching** — возможность кеширования данных о платежахдля оптимизации работы плагина в веб-сервисе. - **Cache Expiration** — время хранения кешированных данных в секундах. - **Log Level** — уровень протоколирования работы плагина. Информацию о созданных протоколах можно найти на вкладке **Logs** в подразделе **Status** раздела **WooCommerce**. - **Fetch Payment Info** — возможность отображения статусов платежей в разделе **Orders**. Если необходимо, чтобы статусы платежей отображались в разделе **Orders**, необходимо установить флажок **Enable**, иначе — снять. По умолчанию флажок установлен. - **Complete order automatically** — возможность автоматического завершения заказов при проведении платежей. Если необходимо, чтобы при присвоении соответствующим платежам статуса **Success** заказы переводились в статус **Completed**, следует установить флажок **Enable**, иначе — снять. По умолчанию флажок снят. - **Payment page version** — поколение платёжной формы Payment Page, которое следует использовать в работе плагина. **Прим.:** Использование этого параметра следует согласовывать со специалистами технической поддержки Ecommpay.Как правило, он актуален в случаях, когда необходимо открывать платёжную форму Payment Page в элементе iframe \([подробнее](ru_CMS__wordpress.md#section_lss_ggm_djc)\). Для этого следует выбрать значение `v5`, иначе — оставить значение `v4`. ![](images/universal/cms/wordpressplugin/cms_wordpress_advanced.jpg "Вкладка General с дополнительными параметрами подключения") 4. Сохранить основные параметры работы плагина. Для этого следует щёлкнуть кнопку **Save changes**. 5. При необходимости подключить возможность незамедлительного списания средств в рамках заказов с определёнными типами товаров. Использование этой возможности может быть актуально при работе с двухстадийными оплатами и осуществляется через проведение одностадийных оплат. Чтобы подключить возможность незамедлительного списания средств, следует перейти на вкладку **Products** в параметрах работы плагина и установить флажки **Enable automatic confirmation of payments** в следующих параметрах: - **Virtual products** — для заказов с виртуальными товарами; - **Downloadable products** — для заказов со скачиваемыми товарами. При этом необходимо учитывать следующие условия: - Если флажок установлен для одного из параметров, то незамедлительное списание средств осуществляется, только если в заказе присутствуют товары соответствующего типа \(virtual или downloadable\). Если же в заказе присутствуют товары разных типов или хотя бы один физический товар, выполняется блокировка средств в рамках двухстадийной оплаты. - Если флажок установлен для обоих параметров, то незамедлительное списание средств происходит, если в заказе присутствуют товары одного из указанных типов или обоих этих типов \(virtual и downloadable\). Если же в заказе присутствует хотя бы один физический товар, выполняется блокировка средств в рамках двухстадийной оплаты. Информация о работе с типами товаров virtual и downloadable представлена [в документации WooCommerce](https://woocommerce.com/document/managing-products/virtual-downloadable/). 6. Сохранить изменения. Для этого следует щёлкнуть кнопку **Save changes**. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_products.png "Вкладка Products с параметрами для настройки незамедлительного списания средств") 7. Если используется дополнение [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/), при необходимости подключить возможность незамедлительного списания средств для регистрации оплат по подпискам в рамках заказов с определёнными типами товаров. Использование этой возможности может быть актуально при работе с двухстадийными оплатами и осуществляется через проведение одностадийных оплат. Чтобы подключить возможность незамедлительного списания средств, следует перейти на вкладку **Subscriptions** в параметрах работы плагина и установить флажки **Enable automatic confirmation of payments** в следующих параметрах: - **Virtual subscriptions** — для заказов с виртуальными товарами; - **Downloadable subscriptions** — для заказов со скачиваемыми товарами; - **Other subscriptions** — для заказов с товарами любого типа, кроме виртуальных и скачиваемых. При этом необходимо учитывать следующие условия: - Если флажок установлен для одного из параметров, то незамедлительное списание средств осуществляется, только если в заказе присутствуют товары соответствующего типа \(например, virtual или downloadable\). Если же в заказе присутствуют товары разных типов или типов, для которых флажок не установлен, выполняется блокировка средств в рамках двухстадийной оплаты. - Если флажок установлен для нескольких параметров, то незамедлительное списание средств происходит, если в заказе присутствуют товары одного из указанных типов или всех типов, для которых установлен флажок. 8. Сохранить изменения. Для этого следует щёлкнуть кнопку **Save changes**. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_subscriptions.png "Вкладка Subscriptions с параметрами для настройки незамедлительного списания средств") 9. Задать параметры использования платёжных методов \([подробнее](ru_CMS__wordpress.md)\). ### Проведение тестовых оплат {#ru_cms_wordpress_testing_purchase} #### Введение {#section_mp4_kgb_rdc .section} В рамках работы с плагином можно проводить тестовые оплаты в веб-сервисе и получать информацию о них через интерфейс WordPressв разделе **Orders**. При этом можно использовать специальные платёжные реквизиты, позволяющие тестировать заданные сценарии работы. Чтобы тестировать проведение карточных платежей, можно использовать номера тестовых карт. При этом для тестирования по заданным кратчайшим сценариям\(без эмулирования аутентификации 3‑D Secure\) можно использовать следующие номера карт: - `4000 0000 0000 0077` — для проведения оплаты; - `4111 1111 1111 1111` — для отклонения оплаты. Для более масштабного тестирования можно использовать расширенный набор тестовых данных для карточных платежей\(в том числе с аутентификацией 3‑D Secure\), представленных в статье [Номера тестовых карт](ru_test_cards.md). Чтобы тестировать проведение платежей с использованием альтернативных методов\(при подключении соответствующих методов через курирующего менеджера или техническую поддержку и при использовании тестовой среды платёжной платформы\), можно использовать информацию, представленную в статье [Возможности тестирования](ru_pm_testing.md), а также в разделах о тестировании отдельных методов. #### Обеспечение синхронизации данных {#section_s1z_sg2_lcc .section} При работе с двухстадийными оплатами вторые стадии можно инициировать как через интерфейс WordPress, так и через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\). Во втором случае информация о заказах в интерфейсе WordPress обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускается инициирование вторых стадий оплат через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс WordPress, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе WordPress. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS WordPress, на URL, указанный в параметрах работы плагина в поле **Merchant callback URL** \(в формате `https:///?wc-api=WC_Ecommpay`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. #### Процедуры {#section_fbx_wh2_lcc .section} Оплата в одну стадию, как и первая стадия двухстадийной оплаты\(блокировка средств\), инициируется пользователем при подтверждении им платежа. Одностадийная оплата проводится автоматически, в то время как для проведения двухстадийной оплаты сначала автоматически выполняется только первая стадия, с блокировкой средств, и уже после этого может выполняться вторая стадия, со списанием средств или отменой блокировки. Инициировать вторую стадию можно также автоматически, по истечении установленного срока блокировки, либо по запросу со стороны мерчанта, через интерфейс WordPress или интерфейсы платёжной платформы Ecommpay — Dashboard\([подробнее](ru_dbl_payments.md)\) и Gate API\([подробнее](ru_gate_payment_auth.md)\). При этом списания по запросам могут выполняться как на полную, так и на частичную сумму заблокированных средств. Чтобы инициировать вторую стадию через интерфейс WordPress, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **WooCommerce** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты. 3. Если необходимо выполнить списание части суммы платежа, изменить сумму заказа, используя кнопку ![](images/ecommpay/cms/wordpressplugin/edit_item.png) в строке нужного товара в карточке заказа. 4. Инициировать вторую стадию оплаты. Для списания заблокированных средств следует щёлкнуть кнопку **Capture** с суммой для списания и подтвердить действие в появившемся диалоговом окне. Для отмены блокировки средств следует щёлкнуть кнопку **Cancel payment** и подтвердить действие в появившемся диалоговом окне. Для настройки автоматического инициирования второй стадии двухстадийных оплат следует обращаться к специалистам технической поддержки Ecommpay. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_order_auth.png "Карточка заказа с возможностью инициировать вторую стадию двухстадийной оплаты в интерфейсе WordPress") **Прим.:** В соответствии с требованиями международных платёжных систем на стороне платёжной платформы Ecommpay ограничивается время, на которое могут быть заблокированы средства пользователей \([подробнее](ru_pp_purchase_auth.md#section_cmc_b3s_1mb)\).Если по истечении предельного времени средства не были списаны или их блокировка не была отменена, платёж автоматически отклоняется на стороне платформы. ### Выполнение тестовых возвратов {#ru_cms_wordpress_testing_refund} #### Введение {#section_vry_vpz_tcc .section} После проведения тестовых оплат можно тестировать выполнение возвратовчерез интерфейс WordPress и, если актуально, интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе WordPress должны быть в статусах `Processing` или `Completed`, а платежи в платформе Ecommpay — в статусах `success`, `partially reversed` или `partially refunded`. Также можно иметь в виду, что вся информация о тестовых возвратах, представленная в этом подразделе, актуальна и для выполнения возвратов в рабочей среде. #### Обеспечение синхронизации данных {#section_hkb_qrc_5cc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о платежах и заказах в интерфейсе WordPress обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о платежах и заказах через интерфейс WordPress, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе WordPress. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS WordPress, на URL, указанный в параметрах работы плагина в поле **Merchant callback URL** \(в формате `https:///?wc-api=WC_Ecommpay`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. **Внимание:** Следует учитывать, что при выполнении возвратов через интерфейсы платформы Ecommpay в CMS WordPress не фиксируется информация о том, за какие товары \(или услуги\) были возвращены средства. #### Процедуры {#section_yxq_qyd_5cc .section} Чтобы выполнить возврат через интерфейс WordPress, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **WooCommerce** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, по которому необходимо выполнить возврат средств, и щёлкнуть кнопку **Refund**в открывшейся карточке заказа. 3. Указать количество товаров, которые необходимо вернуть \(сумма возврата при этом рассчитывается автоматически\), либо сумму возврата, не изменяя количество товаров в заказе. 4. При необходимости указать причину возврата в поле **Reason for refund**. 5. Подтвердить выполнение возврата. Для этого следует щёлкнуть кнопку **Refund via** Ecommpay. 6. Убедиться в том, что сумма заказа изменилась на сумму возврата и в правой боковой панели **Order notes** отображается уведомление о выполненной операции. При выполнении частичного возврата заказу присваивается статус `Processing` или `Completed`, при выполнении полного возврата — `Refunded`. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_refund.png "Карточка заказа в интерфейсе WordPress") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ## Использование {#ru_cms_wordpress_usage} ### Общая информация {#ru_cms_wordpress_usage_overview} Для проведения платежей с реальным списанием средств, прежде всего, необходимо решить все организационные вопросы по взаимодействию с Ecommpay\(подать заявку на подключение, предоставить всю необходимую информацию и получить от Ecommpay уведомление о возможности проводить платежи, а также идентификатор и секретный ключ рабочего проекта\). Также необходимосообщить специалистам технической поддержки Ecommpay название и адрес веб-сервиса, для которого актуально использование плагина Ecommpay Payments,и валюту проведения платежей. После этого можно указать в параметрах работы плагина идентификатор и ключ рабочего проекта, полученные от Ecommpay, и задать другие необходимые параметры\(или проверить их актуальность для рабочего применения\). Если впоследствии потребуется приостановить работу плагина, можно отключить его платёжные методы. Кроме того, при необходимости дополнительного тестирования, например при подключении новых функций, можно переключать плагин на работу с тестовым проектом. ### Настройка параметров работы с разовыми оплатами {#ru_cms_wordpress_usage_setup} Чтобы настроить параметры работы плагина с разовыми оплатами, следует: 1. Открыть карточку плагина в интерфейсе WordPress. Для этого следует: 1. Перейти на вкладку **Payments** в подразделе **Settings** раздела **WooCommerce**. 2. Найти в столбце **Method** один из настроенных платёжных методов для работы с Ecommpay и щёлкнуть кнопку **General settings** в соответствующей строке. 2. Задать основные параметры работы плагина на вкладке **General**: - **Project ID** — идентификатор рабочего проекта; - **Secret Key** — ключ рабочего проекта для взаимодействия с платформой; - **Purchase type** — вариант проведения оплат: - **Sale \(one-step purchase\)** — в одну стадию \(с незамедлительным списанием средств\); - **Auth \(two-step purchase\)** — в две стадии \(с предварительной блокировкой и последующим списанием средств\). - **Automatic cancellation of payments** — автоматическая отмена списаний в рамках двухстадийных оплат при отмене соответствующих заказов. Для подключения этой возможности, следует установить флажок **Enable**. В таком случае при переводе заказа в статус **Cancelled** двухстадийная оплата в рамках этого заказа автоматически отклоняется. - **Language** — язык отображения платёжной формы. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_general.png "Вкладка General с основными параметрами подключения") 3. При необходимости, задать дополнительные параметры работы плагина. Для этого на вкладке **General** необходимо щёлкнуть ссылку **Advanced settings** и задать параметры в секциях **Transaction Cache** и **Shop Admin Setup**: - **Enable Caching** — возможность кеширования данных о платежахдля оптимизации работы плагина в веб-сервисе. - **Cache Expiration** — время хранения кешированных данных в секундах. - **Log Level** — уровень протоколирования работы плагина. Информацию о созданных протоколах можно найти на вкладке **Logs** в подразделе **Status** раздела **WooCommerce**. - **Fetch Payment Info** — возможность отображения статусов платежей в разделе **Orders**. Если необходимо, чтобы статусы платежей отображались в разделе **Orders**, необходимо установить флажок **Enable**, иначе — снять. По умолчанию флажок установлен. - **Complete order automatically** — возможность автоматического завершения заказов при проведении платежей. Если необходимо, чтобы при присвоении соответствующим платежам статуса **Success** заказы переводились в статус **Completed**, следует установить флажок **Enable**, иначе — снять. По умолчанию флажок снят. - **Payment page version** — поколение платёжной формы Payment Page, которое следует использовать в работе плагина. **Прим.:** Использование этого параметра следует согласовывать со специалистами технической поддержки Ecommpay.Как правило, он актуален в случаях, когда необходимо открывать платёжную форму Payment Page в элементе iframe \([подробнее](ru_CMS__wordpress.md#section_lss_ggm_djc)\). Для этого следует выбрать значение `v5`, иначе — оставить значение `v4`. ![](images/universal/cms/wordpressplugin/cms_wordpress_advanced.png "Вкладка General с дополнительными параметрами подключения") 4. Сохранить основные параметры работы плагина. Для этого следует щёлкнуть кнопку **Save changes**. 5. При необходимости подключить возможность незамедлительного списания средств в рамках заказов с определёнными типами товаров. Использование этой возможности может быть актуально при работе с двухстадийными оплатами, когда нет необходимости инициировать списание средств вручную, и осуществляется через проведение одностадийных оплат. Чтобы подключить возможность незамедлительного списания средств, следует перейти на вкладку **Products** в параметрах работы плагина и установить флажки **Enable automatic confirmation of payments** в следующих параметрах: - **Virtual products** — для заказов с виртуальными товарами; - **Downloadable products** — для заказов со скачиваемыми товарами. При этом необходимо учитывать следующие условия: - Если флажок установлен для одного из параметров, то незамедлительное списание средств осуществляется только, если в заказе присутствуют товары соответствующего типа \(virtual или downloadable\). Если же в заказе присутствуют товары разных типов или хотя бы один физический товар, выполняется блокировка средств в рамках двухстадийной оплаты. - Если флажки установлены для обоих параметров, то незамедлительное списание средств происходит, если в заказе присутствуют товары одного из указанных типов или обоих этих типов \(virtual и downloadable\). Если же в заказе присутствует хотя бы один физический товар, выполняется блокировка средств в рамках двухстадийной оплаты. Информация о работе с типами товаров virtual и downloadable представлена [в документации WooCommerce](https://woocommerce.com/document/managing-products/virtual-downloadable/). 6. Сохранить изменения. Для этого следует щёлкнуть кнопку **Save changes**. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_products.png "Вкладка Products с параметрами для настройки незамедлительного списания средств") 7. Задать параметры использования платёжных методов \([подробнее](ru_CMS__wordpress.md)\). ### Настройка параметров работы с повторяемыми оплатами {#ru_cms_wordpress_usage_setup_recurring} Чтобы настроить регистрацию и проведение повторяемых оплат \(*по подпискам*\) с использованием плагина Ecommpay Payments и дополнения [WooCommerce Subscriptions](https://woocommerce.com/products/woocommerce-subscriptions/), следует настроить рабочие параметры плагина Ecommpay Payments \(как и для разовых оплат\) и использовать инструменты, расположенные в карточке плагина WooCommerce на вкладке **Subscriptions**.Среди прочего, на этой вкладке можно задавать названия кнопок, используемых для добавления в корзину и оплаты товаров по подписке, варианты возобновления повторяемых оплат после их приостановки и другие параметры. Информацию о работе с повторяемыми оплатами через дополнение WooCommerce Subscriptions можно найти [в документации WooCommerce](https://woocommerce.com/document/subscriptions/store-manager-guide/#section-25). ![](images/universal/cms/wordpressplugin/cms_wordpress_subscriptions_setup.png "Вкладка Subscriptions с параметрами для настройки повторяемых оплат") Также при работе с плагином Ecommpay Payments можно подключить возможность незамедлительного списания средств для регистрации оплат по подпискам в рамках заказов с определёнными типами товаров.Это может быть актуально, когда в параметрах работы плагина выбран вариант проведения двухстадийных оплат и для регистрации повторяемых оплат нет необходимости инициировать списание средств вручную. В таком случае повторяемые оплаты регистрируются через проведение разовых одностадийных оплат. Чтобы настроить возможность незамедлительного списания средств при регистрации оплат по подпискам, следует перейти на вкладку **Subscriptions** в параметрах работы плагина Ecommpay Payments и установить флажки **Enable automatic confirmation of payments** в следующих параметрах: - **Virtual subscriptions** — для заказов с виртуальными товарами; - **Downloadable subscriptions** — для заказов со скачиваемыми товарами; - **Other subscriptions** — для заказов с товарами любого типа, кроме виртуальных и скачиваемых. При этом необходимо учитывать следующие условия: - Если флажок установлен для одного из параметров, то незамедлительное списание средств осуществляется, только если в заказе присутствуют товары соответствующего типа \(virtual или downloadable\). Если же в заказе присутствуют товары разных типов или хотя бы один физический товар, автоматически выполняется только блокировка средств в рамках двухстадийной оплаты. - Если флажки установлены для обоих параметров, то незамедлительное списание средств происходит, если в заказе присутствуют товары одного из указанных типов или обоих этих типов \(virtual и downloadable\). Если же в заказе присутствует хотя бы один физический товар, автоматически выполняется только блокировка средств в рамках двухстадийной оплаты. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_subscriptions.png "Вкладка Subscriptions с параметрами для настройки незамедлительного списания средств") ### Проведение оплат {#ru_cms_wordpress_usage_purchase} #### Введение {#section_myj_t1k_rdc .section} Если веб-сервис и плагин корректно настроены, проведение одностадийных оплат и блокировка средств для двухстадийных оплат осуществляются автоматически.При этом важно обеспечивать сбор всех необходимых данных на стороне веб-сервиса. **Прим.:** Расширен набор сведений, необходимых для аутентификации 3‑D Secure при проведении карточных оплат. Для сбора и передачи таких сведений на странице перехода к оплате должны использоваться поля для указания пользователем номера его телефона или адреса электронной почты. С вопросами и проблемами, касающимися проведения оплат, можно обращаться к специалистам технической поддержки Ecommpay. #### Обеспечение синхронизации данных {#section_vw3_v1k_rdc .section} При работе с двухстадийными оплатами вторые стадии можно инициировать как через интерфейс WordPress, так и через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\). Во втором случае информация о заказах в интерфейсе WordPress обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускается инициирование вторых стадий оплат через интерфейсы платформы Ecommpay и контроль информации о заказах через интерфейс WordPress, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе WordPress. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS WordPress, на URL, указанный в параметрах работы плагина в поле **Merchant callback URL** \(в формате `https:///?wc-api=WC_Ecommpay`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. #### Процедуры {#section_oz4_bbk_rdc .section} Оплата в одну стадию, как и первая стадия двухстадийной оплаты\(блокировка средств\), инициируется пользователем при подтверждении им платежа. Одностадийная оплата проводится автоматически, в то время как для проведения двухстадийной оплаты сначала автоматически выполняется только первая стадия, с блокировкой средств, и уже после этого может выполняться вторая стадия, со списанием средств или отменой блокировки. Инициировать вторую стадию можно также автоматически, по истечении установленного срока блокировки, либо по запросу со стороны мерчанта, через интерфейс WordPress или интерфейсы платёжной платформы Ecommpay — Dashboard\([подробнее](ru_dbl_payments.md)\) и Gate API\([подробнее](ru_gate_payment_auth.md)\). При этом списания по запросам могут выполняться как на полную, так и на частичную сумму заблокированных средств. Чтобы инициировать вторую стадию через интерфейс WordPress, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **WooCommerce** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, в рамках которого необходимо инициировать вторую стадию оплаты. 3. Если необходимо выполнить списание части суммы платежа, изменить сумму заказа, используя кнопку ![](images/ecommpay/cms/wordpressplugin/edit_item.png) в строке нужного товара в карточке заказа. 4. Инициировать вторую стадию оплаты. Для списания заблокированных средств следует щёлкнуть кнопку **Capture** с суммой для списания и подтвердить действие в появившемся диалоговом окне. Для отмены блокировки средств следует щёлкнуть кнопку **Cancel payment** и подтвердить действие в появившемся диалоговом окне. Для настройки автоматического инициирования второй стадии двухстадийных оплат следует обращаться к специалистам технической поддержки Ecommpay. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_order_auth.png "Карточка заказа с возможностью инициировать вторую стадию двухстадийной оплаты в интерфейсе WordPress") **Прим.:** В соответствии с требованиями международных платёжных систем на стороне платёжной платформы Ecommpay ограничивается время, на которое могут быть заблокированы средства пользователей \([подробнее](ru_pp_purchase_auth.md#section_cmc_b3s_1mb)\).Если по истечении предельного времени средства не были списаны или их блокировка не была отменена, платёж автоматически отклоняется на стороне платформы. ### Выполнение возвратов {#ru_cms_wordpress_usage_refund} #### Введение {#section_d1x_g2y_5cc .section} После проведения оплат можно выполнять возвраты по нимчерез интерфейс WordPress и, если актуально, интерфейсы [Gate](ru_Gate_Refund.md) и [Dashboard](ru_dbl_payments.md) от Ecommpay. При этом следует учитывать, что для выполнения возвратов заказы в интерфейсе WordPress должны быть в статусах `Processing` или `Completed`, а платежи в платформе Ecommpay — в статусах `success`, `partially reversed` или `partially refunded`. Также можно иметь в виду, что все возможности и процедуры по работе с возвратами в рабочей среде соответствуют тем, которые доступны в тестовой среде. #### Обеспечение синхронизации данных {#section_wbj_2gy_5cc .section} При инициировании возвратов через интерфейсы платёжной платформы Ecommpay \(Dashboard и Gate API\) информация о платежах и заказах в интерфейсе WordPress обновляется, только если настроена отправка оповещений со стороны платёжной платформы. Поэтому в случаях, когда со стороны мерчанта допускаются возвраты через интерфейсы платформы Ecommpay и контроль информации о платежах и заказах через интерфейс WordPress, важно обеспечить отправку оповещений для автоматического обновления информации в интерфейсе WordPress. Для этого должны выполняться следующие условия: - Для используемого проекта настроена отправка оповещений от платёжной платформы к CMS WordPress, на URL, указанный в параметрах работы плагина в поле **Merchant callback URL** \(в формате `https:///?wc-api=WC_Ecommpay`\). Информация о работе с правилами отправки оповещений представлена [в отдельной статье](ru_dbl_projects.md). - Среди используемых правил отправки оповещений нет дублирующих: с совпадением типа платежа, типа события и кода платёжного метода. **Внимание:** Следует учитывать, что при выполнении возвратов через интерфейсы платформы Ecommpay в CMS WordPress не фиксируется информация о том, за какие товары \(или услуги\) были возвращены средства. #### Процедуры {#section_rvz_2gy_5cc .section} Чтобы выполнить возврат через интерфейс WordPress, следует: 1. Перейти к реестру заказов. Для этого следует перейти в раздел **WooCommerce** и выбрать пункт **Orders** в появившемся меню. 2. Выбрать заказ, по которому необходимо выполнить возврат средств, и щёлкнуть кнопку **Refund**в открывшейся карточке заказа. 3. Указать количество товаров, которые необходимо вернуть \(сумма возврата при этом рассчитывается автоматически\), либо сумму возврата, не изменяя количество товаров в заказе. 4. При необходимости указать причину возврата в поле **Reason for refund**. 5. Подтвердить выполнение возврата. Для этого следует щёлкнуть кнопку **Refund via** Ecommpay. 6. Убедиться в том, что сумма заказа изменилась на сумму возврата и в правой боковой панели **Order notes** отображается уведомление о выполненной операции. При выполнении частичного возврата заказу присваивается статус `Processing` или `Completed`, при выполнении полного возврата — `Refunded`. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_refund.png "Карточка заказа в интерфейсе WordPress") Чтобы выполнить возврат через Gate API или Dashboard платформы Ecommpay, следует использовать процедуры, представленные в соответствующих статьях: [Возвраты средств после оплат](ru_Gate_Refund.md)\(для Gate API\) и [Выполнение возвратов](ru_dbl_payments.md)\(для интерфейса Dashboard\). ### Контроль платежей и заказов {#ru_cms_wordpress_usage_monitoring} Контролировать информацию о платежах \(в том числе о списаниях в рамках повторяемых оплат\), проводимых с помощью плагина Ecommpay Payments, а также о соответствующих заказах можно можно через интерфейс WordPress, используя инструменты подраздела **Orders** в разделе **WooCommerce**. Также для получения информации о платежах можно использовать интерфейс Dashboard от Ecommpay \([подробнее](ru_dbl_payments.md)\), в котором доступна информация о платежах и возвратах, проводимых через платформу Ecommpay, но не отображается информация о заказах. В подразделе **Orders** отображается реестр заказов с основными сведениями о каждом из них, а также с возможностями поиска, фильтрации, перехода к карточкам отдельных заказов и выполнения различных действий. \(Вместе со статусами заказов в этом реестре могут отображаться и статусы платежей — если в параметрах работы плагина установлен флажок **Fetch Payment Info**.\) ![](images/universal/cms/wordpressplugin/cms_wordpress_orders.png "Реестр заказов в интерфейсе WordPress") Для перехода к карточке конкретного заказа можно щёлкнуть его строку в реестре. В карточкахотображаются развёрнутые сведения о заказах и платежах, включая дату создания заказа, сумму, способ и статус оплаты, адрес доставки и другую информацию. Также в карточках доступны специализированные панели: - **Ecommpay** **Payment** — с информацией о платеже и возможностью обновлять эту информацию вручную с помощью кнопки **Refresh**; - **Order actions** — с инструментами для выполнения различных действий, доступных в рамках заказа; - **Order notes** — с уведомлениями о различных событиях, касающихся заказа и платежа. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_order_tab.png "Карточка заказа в интерфейсе WordPress") Более подробная информация о работе с заказами в интерфейсе WordPress представлена [в документации WooCommerce](https://woocommerce.com/document/managing-orders/?quid=0126ec88eba314cb70e4e8a8db82482e#viewing-and-managing-multiple-orders). ### Контроль повторяемых оплат {#ru_cms_wordpress_usage_recurring} При использовании дополнения WooCommerce Subscriptions в разделе **WooCommerce** становится доступным подраздел **Subscriptions** с информацией о проведении повторяемых оплат \(в дополнение к информации, отображаемой в подразделе **Orders**\).По аналогии с подразделом **Orders** в подразделе **Subscriptions** отображается реестр подписок с основными сведениями о каждой из них, а также с возможностями поиска, фильтрации, перехода к карточкам отдельных подписок и выполнения различных действий. ![](images/universal/cms/wordpressplugin/cms_wordpress_subscriptions.png "Реестр подписок в интерфейсе WordPress") Более подробная информация о работе с повторяемыми оплатами в интерфейсе WordPress представлена [в документации WooCommerce](https://woocommerce.com/document/subscriptions/store-manager-guide/#section-14). ## Параметры использования платёжных методов {#ru_cms_wordpress_methods} При работе с плагином Ecommpay Payments в интерфейсе WordPress можно настраивать использование различных платёжных методов, подключённых в рамках проекта мерчанта. Это можно делать через отдельные вкладки в карточке плагина— такие как **Card settings** \(с параметрами для карточных платежей\), **Pay by Bank** \(с параметрами для использования методов группы Open Banking в странах Европы\) или **More methods** \(с параметрами для использования полной группы методов, подключённых в проекте\). **Прим.:** Вкладки, отображаемые по умолчанию, исключить из карточки нельзя, даже если соответствующие методы не используются в проекте.Если актуально работать с другими методами, их использование в плагине можно настраивать только на вкладке **More methods**, предварительно обратившись к специалистам технической поддержки Ecommpay для подключения методов в проекте. На вкладках для настройки использования платёжных методов можно задавать следующие параметры: - Общие параметры: - **Enable/Disable** — возможность подключения платёжного метода для работы через плагин. - **Title** — название платёжного метода, отображаемое на странице перехода к оплате в интерфейсе WooCommerce. - **Show Description** — возможность отображения текста из параметра **Description**. - **Description** — текст, отображаемый пользователям при выборе конкретного платёжного метода. - **Order button text** — название кнопки для перехода к оплате\(например, «Оплатить заказ»\). - Параметры, актуальные только для вкладки **Card settings**: - **Display mode** — способ открытия платёжной формы Payment Page. Можно выбрать один из следующих способов: - `Redirect` — открытие в виде отдельной HTML-страницы \(применяется по умолчанию\). - `Popup` — открытие в модальном окне. - `Embedded` — открытие в элементе iframe. Этот способ доступен при условии предварительного согласования со специалистами технической поддержки Ecommpay. Для его использования необходимооткрыть раздел **WooCommerce**, перейти в подразделе **Settings** на вкладку **Payments**, щёлкнуть ссылку **Advanced settings** и задать для параметра **Payment page version** значение `v5` \([подробнее](ru_CMS__wordpress.md)\). - **Close on misclick** — возможность закрытия платёжной формы, отображаемой в модальном окне, по щелчку вне этого окна. После такого закрытия пользователь может открыть платёжную форму повторно, но без восстановления введённых им ранее данных. Если не использовать этот режим, закрыть модальное окно можно только с помощью кнопки-крестика или по результатам проведения оплаты. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_card_settings.png "Вкладка Card settings с параметрами для карточных платежей") - Параметр, актуальный только для вкладки **More methods**: - **Payment method code** — код платёжного метода, используемого как единственный дополнительный \(по отношению к методам, для настройки работы с которыми применяются отдельные вкладки\). - Если не применять этот параметр, то при выборе метода оплаты в интерфейсе веб-сервиса пользователь может выбрать вариант **More payment methods** \(или любое другое название этого варианта, которое задаётся в поле **Title**\) и перейти к платёжной форме с возможностью выбрать там один из методов, доступных для инициируемого платежа через платформу Ecommpay.При этом все методы от Ecommpay, доступные для выбора непосредственно в веб-сервисе \(наряду с вариантом **More payment methods**\), оказываются доступными и в платёжной форме. - Если указать в значении этого параметра код одного из доступных методов\(в соответствии [со справочником](ru_pm_codes.md)\), то при выборе методов оплаты в интерфейсе веб-сервиса наряду с другими доступными там для выбора методами пользователь может выбрать указанный и перейти к работе с ним, минуя выбор каких-либо других методов в платёжной форме.Чтобы не допускать коллизий с таким выбором, при указании кода какого-либо метода в этой вкладке также следует указывать название этого метода для отображения в веб-сервисе \(в поле **Title**\). **Прим.:** Поскольку в тестовом режиме работы плагина доступны оплаты только с прямым использованием платёжных карт, тестировать работу вкладки **More methods** в таком случае можно только для метода `card`. ![](images/ecommpay/cms/wordpressplugin/cms_wordpress_more_methods.png "Вкладка More methods с параметрами использования полной группы методов") --- # Встраивание облегчённой редакции Payment Page для карточных платежей {#ru_pp_microframe_solution} статья о порядке работы с облегчённой редакцией платёжной формы Payment Page для классических карточных платежей ## Общая информация {#section_rjf_5dl_bzb .section} В некоторых случаях может быть актуальным встраивать в пользовательский интерфейс веб-сервиса максимально лаконичную платёжную формуи обеспечивать своим пользователям более быстрый и „бесшовный“ сервис по сравнению с типовыми решениями, по крайней мере для наиболее востребованных вариантов платежей. В платёжной платформе Ecommpay для таких ситуаций предусмотрена *облегчённая редакция платёжной формы Payment Page*— с минимальным количеством полей ввода и без кнопки подтверждения \(чтобы оставлять реализацию такой кнопки или иного элемента управления на стороне веб-сервиса\). ![](images/ecommpay/ru_pp_microframe_solution_1.svg "Интерфейс облегчённой редакции платёжной формы. Основные поля") Облегчённая редакция сконфигурирована для проведения классических карточных платежей с поддержкой наиболее актуальных при этом процедур и возможностей. Для поддержки расширенных сценариев работы, как и для использования альтернативных платёжных методов, предусмотрены другие редакции Payment Page. При этом можно комбинировать применение различных редакций и подстраивать их оформление и возможности под специфику веб-сервиса.Так, для платежей с прямым использованием карт можно использовать облегчённую редакцию, для оплат с глубокой интеграцией сервисов Apple Pay и Google Pay — специализированную редакцию для этих сервисов \([подробнее](ru_pp_embedded_payment_buttons.md)\), а для работы с другими методами — основную редакцию Payment Page. ![](images/ecommpay/microframe_1.svg "Применение различных редакций платёжной формы для работы с разными методами") ## Возможности {#section_ql1_ggr_c3c .section} При работе с облегчённой редакцией Payment Page можно: - Настраивать вид формы с помощью конструктора оформления, встроенного в интерфейс Dashboard \([подробнее](ru_PP__design_customisation.md)\). - Настраивать состав отображаемых полей. В рамках такой настройки можно исключать поле для указания имени держателя карты\(если такая возможность настроена для используемого проекта\) и добавлять поля для сбора информации о пользователе\([подробнее](ru_PP_Gathering_customer_data.md)\). - Предоставлять пользователям возможности сохранения, использования и удаления реквизитов картпри работе с формой \(эта возможность по умолчанию доступна, но может быть отключена по согласованию с курирующим менеджером Ecommpay\). - Проводить классические карточные разовые оплаты\(в одну и две стадии\) и проверки действительности карт, с возможностью регистрировать при этом повторяемые оплаты — с выполнением актуальных вспомогательных процедур, включая аутентификацию 3‑D Secure, проверку адресов пользователей \(Address Verification Service\) и дополнение информации о платежах. ## Пользовательский сценарий {#section_eb2_pzd_qbc .section} Со стороны пользователя проведение оплаты с использованием облегчённой редакции Payment Page может выглядеть следующим образом. ![](images/ecommpay/ru_pp_microframe_solution_scenario_1.svg "Открытие платёжной формы") ![](images/ecommpay/ru_pp_microframe_solution_scenario_2.svg "Указание данных карты") ![](images/ecommpay/ru_pp_microframe_solution_scenario_3.svg "Отображение страницы ожидания веб-сервиса") ![](images/ecommpay/ru_pp_microframe_solution_scenario_4.svg "Выполнение аутентификации 3‑D Secure") ![](images/ecommpay/ru_pp_microframe_solution_scenario_5.svg "Отображение итоговой страницы веб-сервиса") 1. Пользователь инициирует в интерфейсе веб-сервиса оплату, после чего ему предоставляется возможность указать данные актуальной карты. На этом шаге в платёжной форме могут отображаться панели выбора карты \(если ранее для этого пользователя были сохранены реквизиты какой-либо карты\), поля для ввода данных актуальной карты, а также дополнительные поля и флажок для согласия на сохранение указанных данных \(если это настроено для используемого проекта\). 2. Пользователь указывает необходимые данные и подтверждает оплату. В случае, если данные не указаны или указаны некорректно, непосредственно в платёжной форме пользователю отображаются соответствующие уведомления. 3. Пользователю отображается информация об ожидании результата оплаты. Это может выполняться как в интерфейсе платёжной формы, так и в интерфейсе веб-сервиса — с учётом того, как это настроено на стороне веб-сервиса, но без закрытия платёжной формы. 4. Если это необходимо для проведения платежа, пользователю отображаются формы для дополнительных действий и он выполняет эти действия. Такими дополнительными формами могут выступать модальное окно с полями для ввода дополнительных сведений, отображаемое в рабочей области веб-сервиса \(поверх платёжной формы\), и страница аутентификации 3‑D Secure, отображаемая в используемом элементе iframe вместо платёжной формы. 5. Пользователю отображается информация о результате оплаты. Для этого задействуются платёжная форма и, если это настроено в веб-сервисе, то и его интерфейс. ## Схема работы {#section_pkd_zml_bzb .section} При проведении оплаты с использованием облегчённой редакции платёжной формы Payment Page взаимодействие между веб-сервисом и формой строится с применением специализированных библиотек Ecommpay. В типовом случае, когда на стороне веб-сервиса обеспечивается отображение собственной страницы ожидания \(поверх интерфейса платёжной формы\), такое взаимодействие может осуществляться следующим образом. **Прим.:** Перенаправлять пользователя на отдельную страницу ожидания или самостоятельно запрашивать информацию о состоянии платежа не требуется. Информация о состоянии платежа автоматически проверяется на стороне Payment Page и передаётся к веб-сервису с помощью соответствующих [функций](ru_pp_microframe_solution.md#section_n5w_tfs_k3c). ![scheme](images/ecommpay/ru_pp_microframe_solution_uml.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. На стороне веб-сервиса осуществляется вызов платёжной формы Payment Page с помощью метода `EPayWidget.runEmbedded`. 3. Запрос на открытие Payment Page поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается облегчённая редакция платёжной формы Payment Page, встроенная в страницу веб-сервиса. 7. Пользователь указывает необходимые данные и подтверждает оплату — тем способом, который реализован на стороне веб-сервиса. 8. На стороне веб-сервиса вызывается метод `trySubmit` используемого экземпляра класса `EPayWidget` — для первичной проверки указанных сведений. 9. На стороне Payment Page выполняется первичная проверка указанных пользователем сведений. 10. От Payment Page к веб-сервису с помощью функции обратного вызова `onCheckSubmit` передаётся информация о готовности к проведению оплаты и необходимости её подтверждения. 11. На стороне веб-сервиса выполняется метод `resolve` функции `onCheckSubmit`, в результате чего к Payment Page направляется информация о подтверждении оплаты. 12. На стороне веб-сервиса выполняется функция обратного вызова `onShowLoader` для отображения пользователю страницы ожидания веб-сервиса. 13. Пользователю отображается страница ожидания веб-сервиса. 14. В платёжную платформу передаётся запрос на проведение оплаты. 15. В платёжной платформе выполняются обработка полученного запроса и его отправка в платёжную среду. 16. В платёжной среде выполняется обработка платежа. 17. От платёжной среды к платёжной платформе направляется информация о результате оплаты. 18. От платёжной платформы к Payment Page направляется информация о результате оплаты. 19. На стороне веб-сервиса выполняется функция обратного вызова `onHideLoader` для скрытия страницы ожидания веб-сервиса и отображения пользователю платёжной формы. 20. Информация о результате оплаты отображается пользователю в Payment Page. ## Подключение, настройка и тестирование {#section_msg_fqr_c3c .section} Чтобы начать работу с облегчённой редакцией платёжной формы, следует: 1. Если ранее не были решены общие организационные вопросы, касающиеся взаимодействия с Ecommpay — решить эти вопросы, подав заявку и предоставив необходимую информацию \([подробнее](ru_pp_interaction_organisation.md)\). 2. Если ранее не были выполнены общие технические работы по интеграции Payment Page с применением специализированных библиотек — выполнить такие работы: 1. Подключить в клиентской части CSS- и JavaScript-библиотеки от Ecommpay, расположенные по адресам `https://paymentpage.ecommpay.com/shared/merchant.css` и `https://paymentpage.ecommpay.com/shared/merchant.js` соответственно. ``` {#codeblock_c31_yrr_c3c .language-xml} ``` **Внимание:** CSS- и JavaScript-библиотеки от Ecommpay должны подключаться только через сеть доставки содержимого \(Content Delivery Network, CDN\).Локальное использование этих библиотек может приводить к критичным ошибкам в работе с формой. 2. Настроить политику обеспечения безопасности контента с помощью директив Content Security Policy, указав в HTTP-заголовке `Content-Security-Policy` адреса источников, необходимых для корректной работы платёжной формы \([подробнее](ru_pp_interaction_organisation.md#section_m5x_m2v_njc)\). ``` {#codeblock_ejr_n4k_mjc} Content-Security-Policy: script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com; style-src https://paymentpage.ecommpay.com; img-src https://applepay.cdn-apple.com; frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com ``` 3. Обеспечить в серверной части сбор и подписывание параметров запросов на открытие Payment Page \(автоматизировав соответствующие [алгоритмы](ru_platform_signature.md) или используя [SDK](ru_sdk_overview.md#section_o1r_2pd_qvb)\), а также отправку подписанных данных в клиентскую часть веб-сервиса. 3. Обеспечить в клиентской части веб-сервиса технические возможности для работы с облегчённой редакцией Payment Page: 1. Возможность использования элемента для отображения формы. ``` {#codeblock_kpz_1sr_c3c .language-xml}
``` 2. Возможность вызова платёжной формы с использованием JavaScript-библиотеки от Ecommpay и метода `EPayWidget.runEmbedded` \(подробнее далее\). 3. Определение функций для обработки целевых интерфейсных событий \(подробнее далее\). 4. Если актуально, согласовать с курирующим менеджером Ecommpay состав отображаемых полей и использование настраиваемых возможностей. В рамках такой настройки могут согласовываться: - скрытие поля для указания имени держателя карты, с условием включения в каждый запрос на открытие платёжной формы параметров `customer_first_name` и `customer_last_name` \(и дальнейшим автоматическим заполнением имени держателя карты исходя из указанных в этих запросах сведений\) или с полным отсутствием сведений о держателе карты \(и возможным снижением проходимости платежей\); - отображение дополнительных полей для сбора данных о пользователях, например номеров их телефонов и адресов электронной почты \([подробнее](ru_PP_Gathering_customer_data.md)\); - предоставление пользователям возможностей сохранения, использования и удаления реквизитов картпри работе с формой \(такая возможность по умолчанию доступна, но может быть отключена\). 5. Если актуально, настроить оформление платёжной формы с помощью конструктора, встроенного в интерфейс Dashboard \([подробнее](ru_PP__design_customisation.md)\). 6. Протестировать проведение платежей и запустить решение в работу.При этом для тестирования можно использовать тестовые проекты и номера платёжных карт \([подробнее](ru_test_cards.md)\). При возникновении вопросов о работе с платформой через облегчённую редакцию Payment Page можно обращаться к настоящей документации, а также к курирующему менеджеру и специалистам технической поддержки Ecommpay. ## Работа с функциями обратного вызова {#section_n5w_tfs_k3c .section} Использование облегчённой редакции Payment Page подразумевает работу с функциями обратного вызова, определяемыми со стороны веб-сервиса при вызове формы. Прежде всего,для корректного проведения платежей должна определяться функция `onCheckSubmit`. В дополнение к этой функции могут быть актуальны следующие: - `onShowLoader` — для отображения страницы ожидания веб-сервиса; - `onHideLoader` — для скрытия страницы ожидания веб-сервиса\(и возвращения пользователя к интерфейсу платёжной формы\); - `onPaymentSubmitResult` — для получения информации о регистрации запроса на проведение платежа; - `onPaymentFail` — для получения информации об отказе в проведении платежа; - `onPaymentSuccess` — для получения информации о проведении платежа; - `onError` — для получения информации об ошибках на стороне платёжной формы. **Прим.:** Функции `onPaymentFail` и `onPaymentSuccess` следует использовать в качестве основного способа получения информации о результате проведения платежа, в том числе для инициирования перенаправления пользователя на соответствующую страницу веб-сервиса, если для этого не используется параметр `redirect_success_url` \([подробнее](ru_pp_microframe_solution.md#table_rxs_ryx_c3c)\). Перенаправлять пользователя на отдельную страницу ожидания или самостоятельно запрашивать информацию о состоянии платежа не требуется. Информация о состоянии платежа автоматически проверяется на стороне Payment Page и передаётся к веб-сервису с помощью соответствующих функций. Помимо этого, могут определяться и другие актуальные функции, позволяющие контролировать работу пользователей с интерфейсом платёжной формы \([подробнее](ru_pp_ui_monitoring.md)\). Определение актуальных функций в клиентской части веб-сервиса может выглядеть следующим образом. ``` {#codeblock_psg_fqr_c3c .language-javascript} const checkoutButtonsWidget = EPayWidget.runEmbedded({ ...configObj, // Определение функции для отображения страницы ожидания веб-сервиса onShowLoader: merchantPage.showMerchantLoader, // Определение функции для скрытия страницы ожидания веб-сервиса onHideLoader: merchantPage.hideMerchantLoader, // Определение функции для получения информации о проведении платежа и последующего перенаправления пользователя onPaymentSuccess: function (data) { merchantPage.redirectToSuccessPage(); }, // Определение функции для получения информации об отказе в проведении платежа и отображения пользователю соответствующего сообщения onPaymentFail: function (data) { merchantPage.showPaymentFailMessage(); }, // Определение функции для проверки возможности оплаты onCheckSubmit: async function (data, resolve, reject) { try { // Проверка корректности заказа if (!await merchantPage.validateCheckoutPage()) { return reject() // Отклонение оплаты из-за некорректного состава заказа } if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) { return reject() // Отклонение оплаты из-за ошибок с суммой и валютой платежа } // Регистрация заказа на стороне веб-сервиса const { orderId, additionalParameters } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo); if (!orderId) { return reject() // Отклонение оплаты из-за ошибок с регистрацией заказа } // Подтверждение оплаты со стороны веб-сервиса с указанием дополнительных сведений return resolve({ additional_parameters: additionalParameters}); } catch (error) { console.error('onCheckSubmit error:', error); return reject(); } }, // Определение функции для получения информации о регистрации запроса в платёжной платформе onPaymentSubmitResult: async function (data) { await merchantAPI.saveTransactionId(orderId, data.request_id) }, // Определение функции для отображения пользователю сообщений об ошибках onError: async function ({ messages }) { await merchantAPI.log("Payment error occurred " + messages) if (messages.includes("invalid payment_id")) { merchantPage.redirectToContactSupportPage(); } }, }, 'POST'); // Вызов функции trySubmit при подтверждении пользователем оплаты (щелчком по кнопке) document.getElementById('placeOrderBtn').addEventListener('click', function() { checkoutButtonsWidget.trySubmit(); }); ``` ## Использование {#section_frr_lrr_c3c .section} В целом для проведения платежа с использованием облегчённой редакции платёжной формы со стороны веб-сервиса необходимо следующее. 1. Сформировать запрос на открытие платёжной формы. В таком запросе должен указываться JavaScript-объект `configObj` [с параметрами вызова формы](ru_pp_microframe_solution.md#section_qgm_ywl_bzb) и [с подписью](ru_platform_signature.md) к ним. К базовому минимуму параметров, обязательному для проведения платежа, в этом случае относятся: - `target_element` — идентификатор тогоэлемента iframe, в котором необходимо открыть платёжную форму; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_amount` — сумма платежав дробных единицах валюты; - `payment_currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `merchant_domain` — доменное имя веб-сервиса, в котором необходимо открыть платёжную форму; - `force_payment_method` — служебный код платёжного метода, который следует использовать в качестве предварительно выбранного, со значением `card`; - `mode` — указатель режима работы Payment Page со значением `purchase` для любой из разовых оплат или `card_verify` для проверки действительности карты; - `signature` — подпись запроса, составленная после указания всех целевых параметров. ``` {#codeblock_nhw_3tr_c3c .language-json} const configObj = { target_element: "widget-container-card-embedded", payment_id: "X03937", payment_amount: 1960, payment_currency: "EUR", project_id: 22, merchant_domain: "cosmoshop.jupiter.example", force_payment_method : "card", signature: "0ByxpQ30hfTIjaCCsVIwVyabcDEF123" }; ``` 2. Вызвать платёжную форму с помощью метода `EPayWidget.runEmbedded`. При вызове платёжной формы необходимо указать JavaScript-объект `configObj` и определить целевые функции обратного вызова, такие как `onCheckSubmit`, `onShowLoader` и `onHideLoader` \(подробнее далее\). 3. При подтверждении пользователем оплаты, например при щелчке по кнопке подтверждения, вызвать метод `trySubmit` используемого экземпляра класса `EPayWidget`. В результате вызова этого метода на стороне Payment Page выполняется первичная проверка указанных пользователем сведений, после чего автоматически выполняется одна из функций: - `onCheckSubmit` — при отсутствии ошибок, без предоставления информации в объекте `data`; - `onValidationError` — при наличии ошибок, с указанием в объекте `data` информации об этих ошибках. ``` {#codeblock_nsp_4rw_c3c .language-json} "{\"message\":\"epframe.embedded_mode.validation_error\",\"data\":{\"pan\":\"Invalid card number.\",\"month_year\":\"Expiry date required.\",\"cvv\":\"CVV2/CVC2 required.\",\"card_holder\":\"Cardholder name required.\"},\"guid\":\"288d-f68c-e53d-3890\"}" ``` 4. Проверить сведения об оплате\(включая сумму и валюту платежа, а также другие обязательные сведения\) и обеспечить вызов актуального метода для функции `onCheckSubmit`: - `resolve` — для подтверждения оплаты\(при отсутствии ошибок\); - `reject` — для отклонения оплаты\(при наличии ошибок\). Вместе с подтверждением платежа на этом этапе можно указать в объекте `additional_parameters` дополнительные сведения о пользователе, если они не были переданы при вызове платёжной формы или их необходимо изменить, а также адреса веб-сервиса для автоматического итогового перенаправления пользователя при проведении и отклонении оплаты. ``` {#codeblock_rv4_xyr_c3c .language-json} { // Общие сведения о пользователе customer_id:"customer_112", customer_first_name:"Arthur", customer_last_name:"McDonald", customer_phone:"447700900123", customer_email:"mcdonald@space.com" // Сведения об адресе проживания пользователя customer_country:"GB", customer_city:"Belfast", customer_address:"14A Cosmos Crescent, Flat 25", customer_zip:"BT99 0ZZ", // Сведения о расчётном адресе пользователя billing_country:"GB", billing_city:"Belfast", billing_address:"14A Cosmos Crescent, Flat 25", billing_postal:"BT99 0ZZ", // Сведения об адресе пользователя, используемом для проверки Address Verification Service avs_street_address:"14A Cosmos Crescent, Flat 25", avs_post_code:"BT99 0ZZ", // Сведения для отображения пользователю актуальной страницы веб-сервиса по итогам оплаты redirect_success_url:"https://cosmoshop.jupiter.example/pages/success", redirect_success_mode:"parent_page", redirect_fail_url:"https://cosmoshop.jupiter.example/pages/failed", redirect_fail_mode:"parent_page" } ``` ## Используемые параметры {#section_qgm_ywl_bzb .section} При вызове облегчённой редакции платёжной формы могут использоваться следующие параметры. |Параметр|Описание| |--------|--------| |`avs_post_code` string, optional |Почтовый индекс пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Пример: `BT99 0ZZ` | |`avs_street_address` string, optional |Адрес пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Включает в себя номер дома и название улицы. Пример: `14A Cosmos Crescent, Flat 25` | |`billing_address` string, optional |Номер дома\(с обозначением корпуса или строения, где это актуально\) и название улицы в расчётном адресе пользователя. Пример: `14A Cosmos Crescent, Flat 25` | |`billing_city` string, optional |Название города в расчётном адресе пользователя. Пример: `Belfast` | |`billing_country` string, optional |Код страны в расчётном адресе пользователя. Указывается в формате ISO 3166-1 alpha-2. Пример: `GB` | |`billing_postal` string, optional |Почтовый индекс в расчётном адресе пользователя. Пример: `BT99 0ZZ` | |`customer_address` string, optional |Название улицы и номер дома\(с обозначением корпуса или строения, где это актуально\) в адресе проживания пользователя, с использованием разделительной запятой. Представляет собой строку длиной не более 255 символов. Пример: `14A Cosmos Crescent, Flat 25` | |`customer_city` string, optional |Название города \(или иного населённого пункта\) в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Belfast` | |`customer_country` string, optional |Код страны в адресе проживания пользователя. Указывается в формате ISO 3166-1 alpha-2. Пример: `GB` | |`customer_email` string, optional |Адрес электронной почты пользователя. Представляет собой строку длиной не более 255 символов, состоящую из локального адреса и доменного имени, разделённых символом `@`. Пример: `mcdonald@space.com` | |`customer_first_name` string, optional |Имя пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Arthur` | |`customer_id` string, optional |Идентификатор пользователя в рамках проекта\(указанного в значении параметра `project_id`\). Должен быть однозначно сопоставим с учётной записью пользователя в веб-сервисе, в том числе для корректной работы с рисками и борьбы с мошенническими операциями. Пример: `customer_112` | |`customer_last_name` string, optional |Фамилия пользователя. Представляет собой строку длиной не более 255 символов. Пример: `McDonald` | |`customer_phone` string, optional |Номер телефона пользователя. В общем случае должен быть полным, с кодом страны, хотя в отдельных случаях допустимо указание и без кода страны. Должен содержать не менее 4 и не более 24 цифр. Пример: `447700900123` | |`force_payment_method` string, required |В рамках проведения платежей с использованием облегчённой редакции платёжной формы должен принимать значение `card`. Пример: `card` | |`merchant_domain` string, required |Доменное имя веб-сервиса, в котором необходимо открыть платёжную форму. Пример: `cosmoshop.jupiter.example` | |`mode` string, required |Указатель режима работы Payment Page. В рамках проведения платежей с использованием кнопок должен принимать значение `purchase` для проведения оплаты или `card_verify` для проверки действительности карты. Пример: `purchase` | |`operation_type` string, optional |Указатель варианта проведения оплаты — в одну или две стадии. Актуален в тех случаях, когда необходимо использовать вариант, отличный от заданного по умолчанию.Может принимать одно из следующих значений: - `sale` — для оплаты в одну стадию\(с незамедлительным списанием средств; [подробнее](ru_pp_purchase.md)\); - `auth` — для оплаты в две стадии\(с предварительной блокировкой и последующим списанием средств; [подробнее](ru_pp_purchase_auth.md)\). Пример: `auth` | |`payment_amount` integer, required |Сумма платежа. Приводится в дробных единицах валюты без десятичного разделителя. Пример: `1960`\(для суммы 19,60 при использовании валюты с двумя дробными разрядами\) | |`payment_currency` string, required |Трёхбуквенный код валюты платежа. Указывается в формате ISO-4217 alpha-3, согласно [справочнику](ru_currency_codes.md). Пример: `EUR` | |`payment_id` string, required |Идентификатор платежа. Должен задаваться на стороне веб-сервиса и представлять собой строку длиной не более 255 символов с обеспечением регистронезависимости и уникальности в рамках используемого проекта. Пример: `X03936` | |`project_id` integer, required |Идентификатор проектавзаимодействия веб-сервиса с платёжной платформой, полученный от Ecommpayпри интеграции \([подробнее](ru_glossary.md)\). Пример: `22` | |`recurring` string, optional |Сведения о регистрируемой повторяемой оплате \([подробнее](ru_pp_recurring.md)\). При использовании JavaScript-библиотеки Ecommpay могут представлять собой JSON-объект, включающий в себя различные сведения из числа допустимых. ``` {#codeblock_st1_lbb_j3c .language-json} { "register": true, "type": "U" } ``` | |`redirect_fail_mode` string, optional |Способ открытия страницы веб-сервиса, адрес которой указан в параметре `redirect_fail_url`, при отклонении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницы втом же объекте iframe, в котором открыта форма; - `parent_page` — открытие страницы в используемой вкладке; - `blank_page` — открытие страницы в новой вкладке. Пример: `parent_page` | |`redirect_fail_url` string, optional |Адрес дляавтоматического итогового перенаправления пользователя при отклонении оплаты. Пример: `https://cosmoshop.jupiter.example/pages/failed` | |`redirect_success_mode` string, optional |Способ открытия страницы веб-сервиса, адрес которой указан в параметре `redirect_success_url`, при проведении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницы втом же объекте iframe, в котором открыта форма; - `parent_page` — открытие страницы в используемой вкладке; - `blank_page` — открытие страницы в новой вкладке. Пример: `parent_page` | |`redirect_success_url` string, optional |Адрес дляавтоматического итогового перенаправления пользователя при проведении оплаты. Пример: `https://cosmoshop.jupiter.example/pages/success` | |`signature` string, required |Цифровая подпись к параметрам запроса. Должна составляться после указания всех целевых параметров в соответствии с заданным алгоритмом \([подробнее](ru_platform_signature.md)\). | |`style_id` integer, optional |Идентификатор стиля оформления платёжной формы. Может использоваться при работе с различными стилями оформления Payment Page \([подробнее](ru_PP__design_customisation.md)\). Пример: `6123` | |`target_element` string, required |Идентификатор элемента iframe \(в рамках HTML-страницы веб-сервиса\), в котором необходимо открыть платёжную форму. Пример: `widget-container-card-embedded` | ## Дополнительные материалы {#section_j5w_yck_k3c .section} При работе с платёжной платформой через облегчённую редакцию платёжной формы Payment Page могут быть полезны следующие материалы: - [Индивидуальное оформление](ru_PP__design_customisation.md)— статья о работе с конструктором оформления Payment Page. - [Сбор данных о пользователях](ru_PP_Gathering_customer_data.md)— статья о возможности получать и использовать дополнительную информацию о пользователях. - [Повторные попытки проведения платежей](ru_PP_Try_Again.md)— статья о возможности предоставлять пользователям дополнительные попытки проведения платежей. - [Работа с подписью к данным](ru_platform_signature.md)— статья о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [SDK для работы с подписью](ru_sdk_overview.md#section_o1r_2pd_qvb)— материалы о порядке применения SDK для работы с подписью. - [Контроль интерфейсных событий](ru_pp_ui_monitoring.md)— статья о возможностях получать и обрабатывать информацию о различных интерфейсных событиях, связанных с платёжной формой и действиями пользователя в ней. - [Работа с информацией о платежах](ru_platform_payment_information.md)— раздел со статьями о способах получения информации, которая может быть актуальна для контроля проведения платежей и анализа результатов при работе с платёжной платформой. - [Номера тестовых карт](ru_test_cards.md)— статья об актуальных номерах карт для тестирования различных сценариев проведения платежей. **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Встраивание кнопок для платежей с использованием методов Apple Pay и Google Pay {#ru_pp_embedded_payment_buttons} статья о порядке работы со специализированной редакцией платёжной формы Payment Page для глубокой интеграции с сервисами Apple Pay и Google Pay ## Общая информация {#section_gsv_s5w_vgc .section} В некоторых случаях может быть актуальным использовать непосредственно в веб-сервисе брендированные кнопки, позволяющие оплачивать заказы широко известными платёжными методами, такими как Apple Pay и Google Pay. При работе с платёжной платформой Ecommpay для этого можно применять специализированную редакцию платёжной формы Payment Page, встраиваемую в веб-сервис в виде соответствующих кнопок и позволяющую проводить платежи со сбором всех необходимых сведений, в том числе о доставке, на стороне сервисов платёжных методов. ![](images/ecommpay/ru_pp_one_click_buttons.svg) При использовании этой редакции платёжной формы в интерфейсе веб-сервиса пользователю отображаются кнопки заданных методов, а при переходе по любой из этих кнопок выполняется перенаправление к соответствующему платёжному сервису, без использования интерфейса Payment Page. Вместе с тем, если для проведения платежа необходимо предоставить дополнительные сведения, пользователю может отображаться модальное окно с соответствующими страницами Payment Page. Чтобы избегать таких ситуаций, рекомендуется обеспечивать передачу необходимых сведений в запросах на открытие Payment Page, а также сбор таких сведений на стороне сервисов Apple Pay или Google Pay. Эта редакция платёжной формы позволяет работать с методами Apple Pay и Google Pay и может сочетаться с основной редакцией Payment Page, в том числе для поддержки платежей с использованием токенов платёжных карт \([подробнее](ru_PP_Payment_by_token.md)\), для перехода к другим методам через их предварительный выбор в веб-сервисе \([подробнее](ru_PP__PreselectingPS.md)\) и для вызова платёжной формы с полным набором доступных методов. При этом оформление кнопок можно настраивать с помощью параметров вызова платёжной формы \(подробнее [далеe](ru_pp_embedded_payment_buttons.md#section_ltd_zgx_mhc)\). Использование встроенного в интерфейс Dashboard конструктора оформления для этих кнопок не поддерживается, но может быть полезным для настройки оформления тех страниц платёжной формы, которые могут отображаться пользователям в случае необходимости предоставить дополнительные сведения. ## Особенности {#section_u5f_ftw_q3c .section} При использовании специализированных кнопок Apple Pay и Google Pay от Ecommpay стоит учитывать следующие особенности: - Встраивание брендированных кнопок непосредственно в веб-сервис мерчанта может улучшать пользовательский опыт и повышать конверсию. Это обеспечивается тем, что, во-первых, кнопки таких глобальных сервисов, как правило, легко узнаваемы и повышают доверие со стороны пользователей, и во-вторых, при работе с такими кнопками число действий в основном пользовательском сценарии сводится к минимуму, без каких-либо дополнительных перенаправлений и подтверждений. \(Так, открытие Payment Page с предварительно выбранным методом Apple Pay или Google Pay добавляет в схожий пользовательский сценарий по крайней мере один дополнительный шаг.\) - Оформление брендированных кнопок регулируется требованиями компаний Apple и Google и может настраиваться мерчантом с учётом их рекомендаций. - Минималистичный дизайн, используемый для встраиваемых кнопок, может быть удобен во многих случаях, например в интерфейсах с высокой плотностью информации и при работе с мобильных устройств. - При проведении оплат с использованием встраиваемых кнопок поддерживается сбор необходимых дополнительных сведений о пользователях \(включая их расчётные адреса, адреса и способы доставки товаров и иную информацию\) непосредственно в сервисах Apple Pay и Google Pay, в рамках платёжных сессий. Это позволяет избегать сбора соответствующих сведений на стороне веб-сервиса или платёжной формы Payment Page, с сопутствующим расширением пользовательских сценариев и дополнительными действиями по настройке такой функциональности. - В случаях, когда пользователь аутентифицирован в сервисе Apple Pay или Google Pay и на стороне этого сервиса есть соответствующая информация, возможно проведение „быстрых“ платежей \(по сценарию *Express checkout*\) — с автоматическим заполнением всех необходимых сведений о пользователе \(включая сведения о платёжной карте, расчётном адресе, адресе и способе доставки\). При этом релевантные сведения о доставке и расчётном адресе могут быть доступны мерчанту в рамках платёжной сессии соответствующего сервиса. Такой сценарий может быть особенно актуальным для тех пользователей, которые не аутентифицированы в веб-сервисе мерчанта, с поддержкой режима так называемого „гостевого заказа“ \(*guest checkout*\), без создания учётной записи в веб-сервисе. - Кнопки Apple Pay и Google Pay могут встраиваться на любую страницу веб-сервиса \(например, на страницу с описанием товара или в раздел каталога товаров\), практически в любой из структурных элементов \(включая меню и различные панели и блоки\), что обеспечивает высокую гибкость и позволяет реализовывать разнообразные способы перехода пользователей к оплатам. ## Пользовательский сценарий {#section_j1y_t5w_vgc .section} Со стороны пользователя проведение оплаты с использованием встроенных кнопок может выглядеть следующим образом. ![](images/ecommpay/ru_one_click_button_scenario_1.svg "Выбор метода") ![](images/ecommpay/ru_one_click_button_scenario_2.svg "Указание сведений о доставке") ![](images/ecommpay/ru_one_click_button_scenario_3.svg "Подтверждение платежа") ![](images/ecommpay/ru_one_click_button_scenario_4.svg "Возвращение к веб-сервису") 1. Пользователь переходит в интерфейсе веб-сервиса на страницу, где ему отображаются кнопки заданных методов, и инициирует оплату с помощью одного из них. 2. Пользователь перенаправляется к сервису выбранного метода. 3. В сервисе выбранного метода пользователь выбирает адрес и способ доставки, если это актуально, и выполняет другие необходимые действия. 4. Пользователю отображается информация о результате оплаты \(с учётом того, как это настроено на стороне веб-сервиса\). ## Варианты оформления {#section_phr_twq_x3c .section} Со стороны мерчанта можно настраивать различные параметры оформления брендированных кнопок, включая варианты их компоновки, наполнения \(в части названий и логотипов\) и цветового оформления, а также высоту и радиус скругления. Для этого предусмотрены соответствующие параметры вызова платёжной формы \(подробнее [далеe](ru_pp_embedded_payment_buttons.md#section_ltd_zgx_mhc)\). ![](images/ecommpay/ru_embedded_payment_buttons_customisation.svg "Типовой и индивидуальный варианты оформления") При работе с параметрами оформления брендированных кнопок стоит учитывать следующее: - Необходимо соблюдать требования и рекомендации компаний Apple \([подробнее](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Using-Apple-Pay-buttons)\) и Google \([подробнее](https://developers.google.com/pay/api/web/guides/brand-guidelines)\). - Вариант компоновки и размеры задаются как общие параметры и действуют идентично для всех применяемых кнопок, в то время как остальные параметры можно применять для каждого метода \(и соответствующей кнопки\) индивидуально. - При выборе варианта компоновки кнопок он применяется только в ситуациях, когда ширина элемента, в который встроены кнопки, превышает 1047 пикселей. В остальных случаях кнопки располагаются строго друг под другом. - Для статичного управления размерами доступна только высота кнопок, но не их ширина. Ширина устанавливается автоматически и меняется динамически, исходя из ширины элемента, в который встраиваются кнопки, и количества кнопок в одном ряду. Минимально допустимая ширина каждой кнопки составляет 160 пикселей, а максимально допустимая — ширине элемента, в который встраиваются кнопки. Высота кнопок по умолчанию составляет 44 пикселя. ## Схема работы {#section_yp4_55w_vgc .section} При проведении оплаты с использованием встроенных кнопок взаимодействие между веб-сервисом и платёжной формой строится с применением специализированных библиотек Ecommpay и осуществляется следующим образом. ![](images/ecommpay/ru_pp_one_click_buttons_uml.svg) 1. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 2. Запрос на проведение оплаты поступает в платёжную платформу. 3. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 4. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 5. Пользователю отображаются кнопки заданных методов. 6. Пользователь щёлкает кнопку одного из доступных платёжных методов. 7. На стороне Payment Page выполняется обработка запроса. 8. От Payment Page к веб-сервису направляется сообщение о необходимости подтвердить оплату. 9. От веб-сервиса к Payment Page направляется сообщение с подтверждением оплаты, после чего выполняются действия, актуальные для этого метода. 10. От Payment Page к веб-сервису направляется сообщение с информацией о результате оплаты и адресом страницы для перенаправления пользователя. Взаимодействие при указании сведений о доставке на стороне сервиса выбранного метода \(Apple Pay или Google Pay\) может осуществляться следующим образом. ![](images/ecommpay/ru_pp_one_click_buttons_shipping_uml.svg) 1. От веб-сервиса к Payment Page направляется сообщение с подтверждением оплаты. 2. В платёжную платформу передаётся запрос на открытие интерфейса и формы оплаты Google Pay. 3. Запрос на открытие интерфейса и формы оплаты Google Pay и получение информации о картах, доступных пользователю, передаётся в сервис Google Pay. 4. В сервисе Google Pay выполняется обработка запроса и формируется платёжная форма со списком карт, доступных пользователю. 5. Пользователю отображается интерфейс сервиса Google Pay со списком карт в маскированном виде и полями для указания сведений о доставке. 6. Пользователь указывает адрес доставки. 7. В сервисе Google Pay выполняется обработка запроса. 8. От сервиса Google Pay к Payment Page направляется сообщение со сведениями об адресе доставки. 9. От Payment Page к веб-сервису направляется сообщение со сведениями об адресе доставки. 10. От веб-сервиса к Payment Page направляется сообщение с подтверждением доступности доставки по этому адресу. 11. От Payment Page к сервису Google Pay направляется сообщение с подтверждением доступности доставки. 12. В сервисе Google Pay выполняется обработка запроса. 13. Пользователю отображается информация о доступных способах доставки. 14. Пользователь выбирает способ доставки. 15. В сервисе Google Pay выполняется обработка запроса. 16. От сервиса Google Pay к Payment Page направляется сообщение со сведениями о выбранном пользователем способе доставки. 17. От Payment Page к веб-сервису направляется сообщение со сведениями о выбранном пользователем способе доставки. 18. От веб-сервиса к Payment Page направляется сообщение с подтверждением доступности доставки выбранным способом. 19. От Payment Page к сервису Google Pay направляется сообщение с подтверждением доступности доставки. 20. В сервисе Google Pay выполняется обработка запроса. 21. Пользователю отображается информация об оплате с учётом выбранных им параметров доставки \(адреса и способа\). 22. Пользователь выполняет другие необходимые действия, если требуется, и подтверждает оплату. 23. В сервисе Google Pay выполняется обработка запроса. 24. От сервиса Google Pay к Payment Page направляется сообщение со сведениями об оплате с учётом выбранных пользователем параметров доставки. 25. От Payment Page к веб-сервису направляется сообщение со сведениями об оплате с учётом выбранных пользователем параметров доставки. 26. От веб-сервиса к Payment Page направляется сообщение с подтверждением оплаты, после чего выполняются действия, актуальные для этого метода. 27. От Payment Page к веб-сервису направляется сообщение с информацией о результате оплаты и адресом страницы для перенаправления пользователя. ## Подключение и настройка {#section_rys_fvw_vgc .section} Чтобы начать работу со встроенными кнопками, следует: 1. Подключить в клиентской части CSS- и JavaScript-библиотеки от Ecommpay, расположенные по адресам `https://paymentpage.ecommpay.com/shared/merchant.css` и `https://paymentpage.ecommpay.com/shared/merchant.js` соответственно. **Внимание:** Следует учитывать, что для корректной работы платёжной формы CSS- и JavaScript-библиотеки от Ecommpay должны подключаться через сеть доставки содержимого \(Content Delivery Network, CDN\); локальное хранение этих библиотек не допускается. ``` {#codeblock_evv_14l_wgc .language-xml} ``` 2. Настроить политику обеспечения безопасности контента с помощью директив Content Security Policy, указав в HTTP-заголовке `Content-Security-Policy` адреса источников, необходимых для корректной работы платёжной формы \([подробнее](ru_pp_interaction_organisation.md#section_m5x_m2v_njc)\). ``` {#codeblock_ejr_n4k_mjc} Content-Security-Policy: script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com; style-src https://paymentpage.ecommpay.com; img-src https://applepay.cdn-apple.com; frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com ``` 3. Добавить в клиентской части элемент, предназначенный для отображения в нём кнопок заданных методов. ``` {#codeblock_sc1_bpl_wgc .language-xml}
``` 4. Обеспечить в серверной части сбор и подписывание параметров запросов на открытие Payment Page \(в том числе с применением [SDK для работы с подписью](ru_sdk_overview.md), если это актуально\), а также отправку подписанных данных в клиентскую часть веб-сервиса. 5. Обеспечить в клиентской части вызов платёжной формы с использованием JavaScript-библиотеки от Ecommpay и метода `EPayWidget.runEmbedded`. 6. Реализовать в клиентской части функции для обработки интерфейсных событий. Вместе с функциями, информация о которых представлена в этой статье, могут использоваться и другие \([подробнее](ru_pp_ui_monitoring.md)\). 7. Для работы с платёжным методом Apple Pay — предварительно зарегистрировать рабочие домены веб-сервиса в сервисе Apple Pay. ## Использование {#section_nty_sml_wgc .section} В целом для проведения платежа с использованием встроенных кнопок со стороны веб-сервиса необходимо следующее: 1. Сформировать запросы для отображения необходимых кнопок. 2. Вызвать платёжную форму в виде брендированных кнопок. 3. Подтвердить переход к оплате при переходе пользователем по конкретной кнопке. 4. Подтвердить возможность доставки товара или услуги с учётом выбора пользователя. 5. Подтвердить проведение оплаты на итоговых условиях. Более детально эти действия можно представить следующим образом: 1. Сформировать необходимое число запросов на открытие платёжной формы в виде брендированных кнопок. Это может быть один общий запрос для отображения двух кнопок в одном элементе iframe, два частных запроса для отображения каждой кнопки в отдельном элементе iframe или один частный запрос для отображения лишь одной из кнопок. При этом в каждом используемом запросе должен указываться JavaScript-объект `configObj` [с параметрами вызова](ru_pp_embedded_payment_buttons.md) платёжной формы и [с подписью](ru_platform_signature.md) к ним. Также при формировании таких запросов необходимо учитывать следующее: - К базовому минимуму параметров, обязательному для проведения платежа, в этом случае относятся: - `target_element` — идентификатор того элемента iframe, в котором необходимо открыть платёжную форму; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_amount` — сумма платежа в дробных единицах валюты; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `merchant_domain` — доменное имя веб-сервиса, в котором необходимо открыть платёжную форму; - `force_payment_group` для отображения кнопок обоих методов \(со значением `one_click_buttons`\) или `force_payment_method` для отображения кнопки только одного из методов \(со значением `apple_pay_core` для метода Apple Pay или `google_pay_host` для метода Google Pay\); - `mode` — указатель режима работы Payment Page со значением `purchase`; - `signature` — подпись запроса, составленная после указания всех целевых параметров. - Для инициирования дополнительных действий на стороне сервисов Apple Pay и Google Pay дополнительно следует использовать параметр `payment_methods_options` и указывать в нём следующее: - перечень запрашиваемых сведений о пользователе в составе массива `billing_contact_fields` — для сбора определённых сведений о пользователе, если сбор этих сведений не настроен для всех платежей в рамках используемого проекта \([подробнее](ru_PP_Gathering_customer_data.md)\); - сведения о допустимых способах доставки товара или услуги пользователю в составе объекта `shipping` — для выбора пользователем одного из этих способов. Информация о сведениях, которые можно указывать в параметре `payment_methods_options` при работе со встроенными кнопками, представлена [далее](ru_pp_embedded_payment_buttons.md#section_ltd_zgx_mhc). ``` {#codeblock_hgm_1yl_wgc .language-javascript} { "target_element":"widget-container-one-click-buttons", "payment_id":"X03936", "payment_amount":131960, "payment_currency":"USD", "project_id":22, "merchant_domain":"cosmoshop.jupiter.example", "force_payment_group":"one_click_buttons", "mode":"purchase", "signature":"YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV" } ``` ``` {#codeblock_p4q_12m_dhc .language-json} { "express_checkout":{ "billing_contact_fields":[ "email", "name", "phone", "billing_address", "postal_code" ], "shipping":{ "shipping_fields":[ "shipping_address", "name", "phone" ], "allowed_country_codes":[ "GB", "IE" ], "shipping_methods":[ { "label":"Speed of sound shipping", "detail":"Express shipping (1 hour)", "amount":199, "identifier":"cosmo-shipping-009" }, { "label":"Warp drive shipping", "detail":"Instant shipping", "amount":2999, "identifier":"cosmo-shipping-012" } ] }, "buttons":{ "max_column":1, "height": 40, "border_radius": 100 } }, "google_pay_host":{ "shipping":{ "allowed_country_codes":[ "GB", "IE" ] }, "button":{ "color":"black", "type":"checkout", "border_type":"no_border" } }, "apple_pay_core":{ "button":{ "theme":"black", "type":"buy" } } } ``` 2. Вызвать платёжную форму с помощью метода `EPayWidget.runEmbedded`. При вызове платёжной формы необходимо указать JavaScript-объект `configObj` и определить целевые функции обратного вызова, такие как `onCheckSubmit` \(используемую для обработки информации о щелчке кнопки; подробнее далее\). ``` {#codeblock_s5r_xyl_wgc .language-javascript} const checkoutButtonsWidget = EPayWidget.runEmbedded({ ...configObj, onCheckSubmit: async function (data, resolve, reject) { if (!await merchantPage.validateCheckoutPage()) { return reject() // Отклонение оплаты } if (!await merchantAPI.validateCartAmount(checkoutButtonsWidget.configObj.payment_amount, checkoutButtonsWidget.configObj.payment_currency)) { return reject() // Отклонение оплаты }; return resolve(); // Подтверждение оплаты, с возможностью указать объект additional_parameters в качестве аргумента }, }, 'POST'); ``` 3. При подтверждении пользователем оплаты \(с переходом по встроенной кнопке\) — проверить сведения об оплате \(включая сумму и валюту платежа, а также другие значимые параметры\) и вызвать актуальную функцию: `resolve` для подтверждения оплаты или `reject` для её отклонения. Вместе с подтверждением платежа на этом этапе можно передать различные дополнительные сведения, если они не были переданы при вызове платёжной формы или их актуально изменить. Таким образом могут быть переданы: - сведения о пользователе и адреса для перенаправления — в объекте `additional_parameters`; - идентификатор пользователя, информация о товарных позициях и дополнительная информация о платеже для её учёта на стороне веб-сервиса — в объекте `payment_update` \(вместе с идентификатором проекта, идентификатором, суммой и валютой платежа, а также [с подписью](ru_platform_signature.md) к набору параметров в рамках этого объекта\). В случае отклонения оплаты пользователю следует предоставлять информацию об ошибке со стороны веб-сервиса. ``` {#codeblock_ctr_ztl_wgc .language-json} { // Общие сведения о пользователе customer_first_name:"Arthur", customer_last_name:"McDonald", customer_phone:"447700900123", customer_email:"mcdonald@space.com" // Сведения об адресе проживания пользователя customer_country:"GB", customer_city:"Belfast", customer_address:"14A Cosmos Crescent, Flat 25", customer_zip:"BT99 0ZZ", // Сведения о расчётном адресе пользователя billing_country:"GB", billing_city:"Belfast", billing_address:"14A Cosmos Crescent, Flat 25", billing_postal:"BT99 0ZZ", // Сведения об адресе пользователя, используемом для проверки Address Verification Service avs_street_address:"14A Cosmos Crescent, Flat 25", avs_post_code:"BT99 0ZZ", // Сведения для возвращения пользователя к веб-сервису redirect_success_url:"https://cosmoshop.jupiter.example/pages/success", redirect_success_mode:"parent_page", redirect_fail_url:"https://cosmoshop.jupiter.example/pages/failed", redirect_fail_mode:"parent_page", }; ``` ``` {#codeblock_znb_khr_1jc .language-json} { "project_id":22, "payment_id":"X03936", "payment_amount":131960, "payment_currency":"USD", "customer_id":"customer_112", "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=", "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"", "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w==" } ``` 4. Если в запросе на открытие платёжной формы в составе объекта `shipping` были указаны сведения о допустимых способах доставки товара или услуги пользователю — обеспечить проверку и подтверждение \(либо отклонение\) возможности доставки. Для этого следует использовать функции `onCheckShippingAddress` и `onCheckShippingMethod` библиотеки merchant.js, с помощью которых можно реагировать на указание пользователем адреса и способа доставки соответственно. При работе с этими функциями стоит учитывать, что последовательность указания адреса и способа может меняться с учётом особенностей используемого сервиса, а проверка возможности доставки может итеративно повторяться при изменении указываемой пользователем информации. Также рекомендуется выстраивать сообщения об ошибках, связанных с доставкой, таким образом, чтобы обеспечивать достаточный уровень информирования и удобства пользователей и предупреждать последующие ошибки с их стороны. Чтобы обеспечить проверку возможности доставки, при каждом изменении пользователем параметров доставки следует: - В отношении адреса доставки — проверять возможность доставки на адрес, указанный пользователем, и вызывать актуальную функцию: - `onCheckShippingAddress.resolve` — для подтверждения возможности доставки, с обязательным указанием суммы платежа с учётом этой доставки и, если актуально, с обновлением сведений о параметрах доставки \(в массиве `shipping_methods`\); - `onCheckShippingAddress.reject` — для отклонения возможности доставки, с обязательным указанием суммы платежа без учёта доставки и, если актуально, с указанием текстов сообщений, которые следует отобразить пользователю, включая общее сообщение об ошибке и частные пояснения по любым из параметров доставки. ``` {#codeblock_w41_dkk_dhc .language-json} { "region":"Belfast City", "city":"Belfast", "country_code":"GB", "postal_code":"BT99 0ZZ" } ``` ``` {#codeblock_y5q_ttn_jhc .language-javascript} errors = { "fields": { "country_code": "Supported shipping countries: GB, DE, IT", "region": "This region is not supported", "city": "Only Dublin is available", "postal_code": "The range of postal address 10060 - 100150", }, "message": "Cannot ship to the provided address" } ``` - В отношении способа доставки — проверять возможность доставки тем способом, который указал пользователь, и вызывать актуальную функцию: - `onCheckShippingMethod.resolve` — для подтверждения возможности доставки, с обязательным указанием суммы платежа с учётом этой доставки; - `onCheckShippingMethod.reject` — для отклонения возможности доставки, с обязательным указанием суммы платежа без учёта доставки и, если актуально, с указанием текстов сообщений, которые следует отобразить пользователю. ``` {#codeblock_n4l_zlk_dhc .language-json} { "identifier":"cosmo-shipping-012" } ``` ``` {#codeblock_bv1_pwn_jhc .language-javascript} errors = { "message": "This shipping option cannot be selected for this address", } ``` 5. Если актуально подтверждение оплаты \(с учётом выбранного адреса и способа доставки или других сведений, указанных пользователем на стороне используемого сервиса\) — проверить корректность итоговых сведений, касающихся оплаты. Для этого следует использовать функцию `onConfirmation` библиотеки merchant.js, с помощью которой можно получать такие сведения. После проверки их корректности следует вызвать актуальную функцию: - `onConfirmation.resolve` — для подтверждения оплаты, с указанием итоговых сведений со стороны веб-сервиса. К таким сведениям относятся: - идентификатор проекта, идентификатор, сумма и валюта платежа, а также другие актуальные сведения \(по мере необходимости, включая информацию о товарных позициях и дополнительную информацию о платеже для её учёта на стороне веб-сервиса\) и [подпись](ru_platform_signature.md) к этому набору параметров — в объекте `payment_update`; - сведения о пользователе и адреса для перенаправления \(при необходимости указания или обновления таких сведений\) — в объекте `additional_parameters`. - `onConfirmation.reject` — для отклонения оплаты, с обязательным указанием суммы платежа и, если актуально, с указанием текста для сообщения об ошибке, которое следует отобразить пользователю. ``` {#codeblock_am1_wnk_dhc .language-json} { "customer":{ "email":"mcdonald@space.com", "first_name":"Arthur", "last_name":"McDonald", "phone":"447700900123" }, "billing_address":{ "address":"14A Cosmos Crescent, Flat 25", "city":"Belfast", "region":"Belfast City", "country_code":"GB", "postal_code":"BT99 0ZZ" }, "shipping_address":{ "address":"Dock 7, Innovation Hangar", "city":"Belfast", "region":"Belfast City", "country_code":"GB", "postal_code":"BT99 1XY", "first_name":"Arthur", "last_name":"McDonald", "phone":"447700900321" } } ``` ``` {#codeblock_ugm_wnk_dhc .language-javascript} { "project_id":22, "payment_id":"X03936", "payment_amount":131960, "payment_currency":"USD", "customer_id":"customer_112", "receipt_data":"eyJwb3NpdGlvbnMiOiBbeyJxdWFudGl0eSI6IDMsICJhbW91bnQiOiAxMDAwMCwgInRheCI6IDE4LCAidGF4X2Ftb3VudCI6IDE4MDAsICJkZXNjcmlwdGlvbiI6ICJEZXNpZ24gZnJhbWUifV0sICJ0b3RhbF90YXhfYW1vdW50IjogMTgwMCwgImNvbW1vbl90YXgiOiAxOH0=", "merchant_data":"{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"", "signature":"OoyvuCort6RIe8jofbUwZMWhkTaIIr7iIDFwry3bKc0iWGRMqPB1/8jVK4yJX+dv2AZDrNU7Ip4TMcqMG8AD8w==" } ``` ``` {#codeblock_wfp_fc2_fhc .language-json} {"billing_country": "GB", "customer_email": "mcdonald@space.com", "avs_post_code": "BR1 1AA", "redirect_success_url":"https://cosmoshop.jupiter.example/order?id=123"} ``` ``` {#codeblock_c3g_tlg_nhc .language-javascript} errors = { "fields": { "country_code": "Supported shipping countries: GB, DE, IT", "region": "This region is not supported", "city": "Only Dublin is available", "postal_code": "The range of postal address 10060 - 100150", }, "message": "Cannot ship to the provided address" } ``` Дополнительно на стороне веб-сервиса мерчанта можно управлять отображением страницы ожидания, а также получать информацию об ошибках и о результатах проведения платежей с помощью функций для обработки интерфейсных событий: - `onShowLoader` — для отображения страницы ожидания веб-сервиса; - `onHideLoader` — для скрытия страницы ожидания веб-сервиса \(в случае необходимости отображать пользователю страницы платёжной формы Payment Page\); - `onPaymentSubmitResult` — для получения информации об идентификаторе запроса на проведения платежа \(в случае необходимости отслеживать статус платежа\); - `onError` — для получения информации об ошибках на стороне платежной формы. Для контроля результатов проведения платежей можно использовать также [серверные оповещения](ru_platform_callbacks.md). В целом HTML-страница клиентской части веб-сервиса с возможностью проведения платежей с использованием кнопок может выглядеть следующим образом. ``` {#codeblock_fd1_mxx_1hc .language-javascript} const expressButtons = EPayWidget.runEmbedded({ payment_amount: 131960, payment_currency: "USD", project_id: "22", payment_id: "X03936", force_payment_group: "one_click_buttons", payment_methods_options: {"google_pay_host": {"billing_contact_fields": ["name", "email", "phone", "billing_address"]}}, target_element: "widget-container-one-click-buttons", merchant_domain: cosmoshop.jupiter.example, signature: "abcYWb6Z30hfTIjaCCsVIDEF123", onShowLoader: merchantPage.showMerchantLoader, onHideLoader: merchantPage.hideMerchantLoader, onCheckSubmit: async function (data, resolve, reject) { if (await merchantAPI.canStartPayment(merchantPage.cart)) { return resolve(); } return reject(); }, onCheckShippingAddress: async function (data, resolve, reject) { const {addressIsAvailable, newPaymentAmount, newShippingMethods, errors} = await merchantAPI.validateShippingAddress(data); if (addressIsAvailable) { return resolve({payment_amount: newPaymentAmount, shipping_methods: newShippingMethods}); } else { return reject({payment_amount: newPaymentAmount, errors}); } }, onCheckShippingMethod: async function (data, resolve, reject) { const {addressIsAvailable, newPaymentAmount} = await merchantAPI.saveShippingMethod(orderId, data.identifier); if (addressIsAvailable) { return resolve({payment_amount: newPaymentAmount}); } else { return reject({payment_amount: newPaymentAmount}); } }, onConfirmation: async function (data, resolve, reject) { const { orderId, paymentUpdate, additionalParameters, errors } = await merchantAPI.placeOrder(merchantPage.cart, merchantPage.customerInfo); if (orderId) { return resolve({payment_update: paymentUpdate, additional_parameters: additionalParameters}); } else { return reject({errors}) } }, onPaymentSubmitResult: async function (data) { await merchantAPI.saveTransactionId(data.request_id) }, onError: async function ({ messages }) { await merchantAPI.log("Payment error occurred " + messages) if (messages.includes("invalid payment_id")) { merchantPage.redirectToContactSupportPage(); } }, }); ``` **На уровень выше:**[Payment Page](ru_PP_about.md) ## Используемые параметры {#ru_pp_embedded_payment_buttons_parameters} ### Общие параметры {#section_hht_xgx_mhc .section} Для открытия платёжной формы в виде кнопок может использоваться набор параметров, представленных в следующей таблице. |Параметр|Описание| |--------|--------| |`avs_post_code` string, optional |Почтовый индекс пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Пример: `BT99 0ZZ` | |`avs_street_address` string, optional |Адрес пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Включает в себя номер дома и название улицы. Пример: `14A Cosmos Crescent, Flat 25` | |`billing_address` string, optional |Номер дома \(с обозначением корпуса или строения, где это актуально\) и название улицы в расчётном адресе пользователя. Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `14A Cosmos Crescent, Flat 25` | |`billing_city` string, optional |Название города в расчётном адресе пользователя. Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `Belfast` | |`billing_country` string, optional |Код страны в расчётном адресе пользователя \(в формате ISO 3166-1 alpha-2\). Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `GB` | |`billing_postal` string, optional |Почтовый индекс в расчётном адресе пользователя. Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `BT99 0ZZ` | |`billing_region` string, optional |Название региона \(штата, провинции или иной территориальной области\) в расчётном адресе пользователя. Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `Belfast City` | |`billing_region_code` string, optional |Внутренний код региона \(штата, провинции или иной территориальной области\) в расчётном адресе пользователя. Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, и является применимым в тех случаях, когда передаётся в одном запросе с кодом страны в значении параметра `billing_country`. Для сбора сведений о расчётном адресе пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `BFS` | |`customer_address` string, optional |Название улицы и номер дома \(с обозначением корпуса или строения, где это актуально\) в адресе проживания пользователя, с использованием разделительной запятой. Представляет собой строку длиной не более 255 символов. Пример: `14A Cosmos Crescent, Flat 25` | |`customer_birthplace` string, optional |Название места рождения пользователя \(города или иного населённого пункта\). Представляет собой строку длиной не более 255 символов. Пример: `York` | |`customer_city` string, optional |Название города \(или иного населённого пункта\) в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Belfast` | |`customer_country` string, optional |Код страны в адресе проживания пользователя. Указывается в формате ISO 3166-1 alpha-2. Пример: `GB` | |`customer_day_of_birth` string, optional |Дата рождения пользователя. Представляет собой строку в формате `ДД-ММ-ГГГГ`. Пример: `12-03-1986` | |`customer_email` string, optional |Адрес электронной почты пользователя. Представляет собой строку длиной не более 255 символов, состоящую из локального адреса и доменного имени, разделённых символом «@». Для сбора сведений об электронной почте пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `mcdonald@space.com` | |`customer_first_name` string, optional |Имя пользователя. Представляет собой строку длиной не более 255 символов. Для сбора сведений об имени пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `Arthur` | |`customer_id` string, optional |Идентификатор пользователя в рамках проекта \(указанного в значении параметра `project_id`\). Должен быть однозначно сопоставим с учётной записью пользователя в веб-сервисе, в том числе для корректной работы с рисками и борьбы с мошенническими операциями. Пример: `customer_112` | |`customer_last_name` string, optional |Фамилия пользователя. Представляет собой строку длиной не более 255 символов. Для сбора сведений о фамилии пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `McDonald` | |`customer_middle_name` string, optional |Отчество \(или второе или среднее имя\) пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Rhys` | |`customer_phone` string, optional |Номер телефона пользователя. В общем случае должен быть полным, с кодом страны, хотя в отдельных случаях допустимо указание и без кода страны. Должен содержать не менее 4 и не более 24 цифр. Для сбора сведений о телефоне пользователя на стороне сервисов Apple Pay и Google Pay следует использовать параметр `payment_methods_options`. Пример: `447700900123` | |`customer_state` string, optional |Название региона \(штата, провинции или иной территориальной области\) в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Belfast City` | |`customer_street` string, optional |Название улицы в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Cosmos Crescent` | |`customer_zip` string, optional |Почтовый индекс в адресе проживания пользователя. Представляет собой строку длиной не более 10 символов. Пример: `BT99 0ZZ` | |`force_payment_method` string, required\* |В рамках проведения платежей с использованием встроенных кнопок может принимать одно из следующих значений: - `apple_pay_core` — для отображения кнопки метода Apple Pay, - `google_pay_host` — для отображения кнопки метода Google Pay. При каждом вызове платёжной формы должен указываться один из параметров, `force_payment_method` или `force_payment_group`, но не оба этих параметра. Пример: `google_pay_host` | |`force_payment_group` string, required\* |В рамках проведения платежей с использованием кнопок может принимать значение `one_click_buttons`. В этом случае отображаются кнопки обоих методов, Apple Pay и Google Pay. При каждом вызове платёжной формы должен указываться один из параметров, `force_payment_method` или `force_payment_group`, но не оба этих параметра. Пример: `one_click_buttons` | |`merchant_data` string, optional |Дополнительная информация для учёта на стороне веб-сервиса. Состав сведений, передаваемых в значении этого параметра, может быть произвольным, но должен предварительно согласовываться и настраиваться для корректной обработки в платформе и представления в оповещениях и карточках платежей \([подробнее](ru_pp_additional_data.md)\). В согласованных случаях может представлять собой JSON-объект, при передаче которого методом POST требуется экранировать символ `"` \(двойной штрих, U+0022\) путём постановки перед ним символа `\` \(косой обратной черты, U+005C\). ``` {#codeblock_hnr_wvd_wdc .language-json} "merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" ``` | |`merchant_domain` string, required |Доменное имя веб-сервиса, в котором необходимо открыть платёжную форму. Пример: `cosmoshop.jupiter.example` | |`mode` string, required |Указатель режима работы Payment Page. В рамках проведения платежей с использованием кнопок должен принимать значение `purchase`. Пример: `purchase` | |`payment_amount` integer, required |Сумма платежа. Приводится в дробных единицах валюты без десятичного разделителя. Пример: `131960` \(для суммы 1319,60 при использовании валюты с двумя дробными разрядами\) | |`payment_currency` string, required |Трёхбуквенный код валюты платежа. Указывается в формате ISO-4217 alpha-3, согласно [справочнику](ru_currency_codes.md). Пример: `USD` | |`payment_id` string, required |Идентификатор платежа. Должен задаваться на стороне веб-сервиса и представлять собой строку длиной не более 255 символов с обеспечением регистронезависимости и уникальности в рамках используемого проекта. Пример: `X03936` | |`payment_methods_options` string, optional |Дополнительные сведения, актуальные при работе с отдельными платёжными методами и сторонними сервисами. Могут содержать параметры, описанные [далее](ru_pp_embedded_payment_buttons.md#section_ltd_zgx_mhc) | |`project_id` integer, required |Идентификатор проекта взаимодействия веб-сервиса с платёжной платформой, полученный от Ecommpay при интеграции \([подробнее](ru_glossary.md)\). Пример: `22` | |`receipt_data` string, optional |Информация о товарных позициях оплачиваемого заказа. Может использоваться для отправки пользователю \([подробнее](ru_PP_receipt_data.md)\). Представляют собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64. Этот объект может включать в себя различные сведения из числа допустимых. - `positions`, array — массив, в котором можно перечислить до 300 товарных позиций; для каждой товарной позиции указывается следующее: - `amount`, integer — стоимость товара - `quantity`, integer — количество товарных единиц - `tax`, integer — ставка налога на добавленную стоимость \(НДС\), если она отличается для разных товарных позиций - `tax_amount`, integer — сумма налога на добавленную стоимость \(НДС\) - `description`, string — произвольное описание товара - `total_tax_amount`, integer — общая сумма НДС за всю покупку - `common_tax`, integer — ставка налога на добавленную стоимость \(НДС\), если она одинаковая для всех товарных позиций ``` {#codeblock_jg4_sj2_wdc .language-json} { "receipt_data":{ "positions":[ { "quantity":3, "amount":10000, "tax":18, "tax_amount":1800, "description":"Рамка с дизайном" } ], "total_tax_amount":1800, "common_tax":18 } } ``` ``` {#codeblock_trx_sj2_wdc} receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgICAg ICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI6MTgsCiAg ICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiLQoNCw0LzQutCwING BINC00LjQt9Cw0LnQvdC+0LwiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAs CiAgICAgICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ" ``` | |`redirect_fail_url` string, optional |Адрес для автоматического итогового возвращения пользователя к веб-сервису при отклонении оплаты. Пример: `https://cosmoshop.jupiter.example/pages/failed` | |`redirect_success_url` string, optional |Адрес для автоматического итогового возвращения пользователя к веб-сервису при проведении оплаты. Пример: `https://cosmoshop.jupiter.example/pages/success` | |`signature` string, required |Цифровая подпись к параметрам запроса. Должна составляться после указания всех целевых параметров в соответствии с заданным алгоритмом \([подробнее](ru_platform_signature.md)\). | |`target_element` string, required |Идентификатор элемента iframe \(в рамках HTML-страницы веб-сервиса\), в котором необходимо открыть платёжную форму. Пример: `widget-container-one-click-buttons` | ### Специальные параметры для работы с методами Apple Pay и Google Pay {#section_ltd_zgx_mhc .section} При работе со встроенными кнопками в параметре `payment_methods_options` допустимо указывать дополнительные сведения, актуальные для работы с тем или иным методом, представленные в следующей таблице. |Параметр|Описание| | |--------|--------|--| |`express_checkout` object, optional |Дополнительные сведения, актуальные при работе со всеми методами|29-3| |`buttons` object, optional |Параметры отображения брендированных кнопок. Пример: `"buttons":{"max_column":1, "height": 40, "radius": 100 }` |29-3-129-3| |`height` integer, optional |Высота кнопки, в пикселях. Применяется в отношении каждой используемой кнопки. Может принимать значения от 40 до 55 пикселей. Значение по умолчанию — 44 пикселя. Пример: `40` |29-3-1-129-3-1| |`border_radius` integer, optional |Радиус скругления углов кнопки, в пикселях. Применяется в отношении каждой используемой кнопки. Может принимать значения от 0 до 100 пикселей. Значение по умолчанию — 4 пикселя. Пример: `100` |29-3-1-229-3-1| |`max_columns` integer, optional |Указатель варианта компоновки кнопок в используемом элементе iframe. Применяется в ситуациях, когда ширина элемента, в который встроены кнопки, превышает 1047 пикселей. В остальных случаях значение этого параметра игнорируется и в одном ряду отображается строго одна кнопка. Может принимать одно из следующих значений: - `0` — отображение максимально возможного количества кнопок в одном ряду \(*гибкая компоновка*; используется по умолчанию\); - `1` — отображение строго по одной кнопке в одном ряду \(*компоновка строго в один столбец*\); - `2` — отображение по возможности по две кнопки в одном ряду \(*компоновка по возможности в два столбца*\). Пример: `1` |29-3-1-329-3-1| |`shipping` object, optional |Сведения о доставке товара или услуги пользователю|29-3-229-3| |`shipping_fields` array, optional |Сведения об адресе доставки, которые необходимо собрать на стороне сервиса Apple Pay или Google Pay. Представляют собой массив с перечнем запрашиваемых сведений, в числе которых могут быть: - `phone` — номер телефона получателя доставки, - `name` — имя и фамилия получателя доставки, - `shipping_address` — адрес доставки. Пример: `"shipping_fields":["shipping_address"]` |29-3-2-129-3-2| |`shipping_methods` array, optional |Сведения о доступных способах доставки. Способ доставки, указанный первым, отображается в сервисе Apple Pay или Google Pay выбранным по умолчанию|29-3-2-329-3-2| |`label` string, required\* |Название способа доставки, которое следует отображать пользователю. Должно указываться при передаче массива `shipping_methods`. Пример: `Warp drive shipping` |29-3-2-3-129-3-2-3| |`detail` string, required\* |Описание способа доставки, которое следует отображать пользователю. Должно указываться при передаче массива `shipping_methods`. Пример: `Instant shipping` |29-3-2-3-229-3-2-3| |`amount` integer, required\* |Стоимость доставки. Приводится в дробных единицах валюты платежа, указанной в параметре `payment_currency`, без десятичного разделителя. Должна указываться при передаче массива `shipping_methods`. Пример: `2999` \(для суммы 29,99 при использовании валюты с двумя дробными разрядами\) |29-3-2-3-329-3-2-3| |`identifier` string, required\* |Служебный идентификатор способа доставки, заданный на стороне веб-сервиса. Должен указываться при передаче массива `shipping_methods`. Пример: `cosmo-shipping-012` |29-3-2-3-429-3-2-3| |`billing_contact_fields` array, optional |Сведения о расчётном адресе пользователя, которые необходимо собрать на стороне сервиса Apple Pay или Google Pay. Представляют собой массив с перечнем запрашиваемых сведений, в числе которых могут быть: - `email` — адрес электронной почты пользователя, - `name` — имя и фамилия пользователя, - `phone` — номер телефона пользователя, - `postal_code` — почтовый индекс в адресе пользователя, - `billing_address` — расчётный адрес пользователя. Пример: `"billing_contact_fields":["email","phone"]` |29-3-329-3| |`google_pay_host` object, optional |Дополнительные сведения, актуальные при работе с платёжным методом Google Pay|29-2| |`shipping` object, optional |Сведения о доставке товара или услуги пользователю|29-2-129-2| |`allowed_country_codes` array, optional |Сведения о странах, для которых доступна доставка. Если эти сведения не указаны, доступными считаются все страны. Представляют собой массив с перечнем кодов стран в формате ISO 3166-1 alpha-2. Пример: `"allowed_country_codes":["GB","IE"]` |29-2-1-129-2-1| |`button` object, optional |Параметры оформления кнопки. Пример: `"button":{"theme":"black","type":"checkout","border_type": "no_border" }` |29-2-329-2| |`border_type` string, optional |Указатель необходимости обрисовки контура кнопки \([подробнее](https://developers.google.com/pay/api/web/guides/brand-guidelines#custom-button)\). Может принимать следующие значения: - `default_border` — с обрисовкой контура, - `no_border` — без обрисовки контура. Значение по умолчанию — `default_border`. Пример: `no_border` |29-2-3-129-2-3| |`color` string, optional |Указатель варианта цветового оформления кнопки \([подробнее](https://developers.google.com/pay/api/web/guides/brand-guidelines#custom-button)\). Может принимать одно из следующих значений: - `black` — для тёмного варианта оформления, - `white` — для светлого варианта оформления. По умолчанию применяется тёмный вариант оформления. Пример: `black` |29-2-3-229-2-3| |`type` string, optional |Указатель варианта текстового наполнения кнопки в соответствии с документацией Google Pay \([подробнее](https://developers.google.com/pay/api/web/guides/brand-guidelines#style)\). Так, при указании варианта `donate` должна использоваться кнопка с названием **Donate with **, рекомендуемая для внесения взносов и пожертвований. Пример: `checkout` |29-2-3-329-2-3| |`apple_pay_core` object, optional |Дополнительные сведения, актуальные при работе с платёжным методом Apple Pay|29-1| |`button` object, optional |Параметры оформления кнопки. Пример: `"button":{"theme":"black","type":"buy" }` |29-1-329-1| |`theme` string, optional |Указатель варианта цветового оформления кнопки \([подробнее](https://developer.apple.com/design/human-interface-guidelines/apple-pay#Button-styles)\). Может принимать одно из следующих значений: - `black` — для тёмного варианта оформления без обрисовки контура кнопки, - `white` — для светлого варианта оформления без обрисовки контура, - `white-outline` — для светлого варианта оформления с обрисовкой контура. По умолчанию применяется тёмный вариант оформления. Пример: `black` |29-1-3-129-1-3| |`type` string, optional |Указатель варианта текстового наполнения кнопки в соответствии с документацией Apple Pay \([подробнее](https://developer.apple.com/documentation/applepayontheweb/applepaybuttontype)\). Так, при указании варианта `contribute` должна использоваться кнопка с названием с **Contribute with **, рекомендуемая для внесения взносов и пожертвований. Пример: `buy` |29-1-3-229-1-3| --- # Управление формой {#ru_pp_ux_configuration} статьи о способах работы основной редакции платёжной формы Payment Page, включая способы её открытия, перенаправления от неё к сторонним сервисам и возвращения к веб-сервису, а также о возможностях управления этими способами работы Материалы о разных способах работы платёжной формы и управления ими: - [Способы открытия платёжной формы](ru_PP_Integration.md)— о вариантах открытия платёжной формы, в том числе в отдельной вкладке, модальном окне и объекте iframe. - [Способы перенаправления пользователей к сторонним сервисам](ru_PP_pm_redirect_mode.md)— о вариантах открытия вспомогательных страницпри работе с разными платёжными методами. - [Способы возвращения пользователей к веб-сервису](ru_PP_redirect_modes.md)— о вариантах перенаправления пользователей с платёжной формы к веб-сервису по заданным адресам. - **[Способы открытия платёжной формы](ru_PP_Integration.md)** статьи о вариантах открытия основной редакции платёжной формы Payment Page, в отдельной вкладке, в модальном окне и в элементе iframe - **[Способы перенаправления пользователей к сторонним сервисам](ru_PP_pm_redirect_mode.md)** статья о вариантах открытия вспомогательных страниц сторонних сервисов при работе с разными платёжными методами - **[Способы возвращения пользователей к веб-сервису](ru_PP_redirect_modes.md)** статья о вариантах перенаправления пользователей от платёжной формы к веб-сервису по заданным адресам **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Способы открытия платёжной формы {#ru_PP_Integration .concept} статьи о вариантах открытия основной редакции платёжной формы Payment Page, в отдельной вкладке, в модальном окне и в элементе iframe Платёжную форму Payment Page можно открывать на пользовательских устройствах разными способами: в отдельной вкладке браузера, в модальном окне и непосредственно на странице веб-сервиса, в элементе iframe. Управление этими способами осуществляется со стороны веб-сервиса, при этом могут учитываться разные факторы, и, например, для мобильных устройств может автоматически использоваться открытие в отдельной вкладке браузера, в то время как для остальных — в модальном окне. Чтобы сконфигурировать на стороне веб-сервиса открытие Payment Page необходимым образом, вместе с решением общих вопросов [по организации взаимодействия](ru_pp_interaction_organisation.md) можно обращаться к статьям этого подраздела. - [Открытие в виде отдельной HTML-страницы](ru_PP_method_NewTab.md) - [Открытие в модальном окне](ru_PP_method_ModalWindow.md) - [Открытие в элементе iframe HTML-страницы](ru_PP_method_Embedded.md) - **[Открытие в виде отдельной HTML-страницы](ru_PP_method_NewTab.md)** статья о порядке открытия платёжной формы Payment Page в виде отдельной HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений - **[Открытие в модальном окне](ru_PP_method_ModalWindow.md)** статья о порядке открытия платёжной формы Payment Page в модальном окне HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений - **[Открытие в элементе iframe HTML-страницы](ru_PP_method_Embedded.md)** статья о порядке открытия платёжной формы Payment Page в элементе iframe HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений **На уровень выше:**[Управление формой](ru_pp_ux_configuration.md) --- # Открытие в виде отдельной HTML-страницы {#ru_PP_method_NewTab .concept} статья о порядке открытия платёжной формы Payment Page в виде отдельной HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений **На уровень выше:**[Способы открытия платёжной формы](ru_PP_Integration.md) ## Общая информация {#ru_pp_opening_html_overview} При открытии в виде отдельной HTML-страницы платёжная форма Payment Page отображается в отдельной вкладке браузера.С учётом того, как настроена работа браузера, это может быть уже использовавшаяся для веб-сервиса или новая вкладка, но в любом из этих случаев взаимодействие пользователя с веб-сервисом прерывается и он перенаправляется к другой странице, которая фокусирует его на оплате. При этом по завершении оплаты пользователь может быть снова перенаправлен от платёжной формы к веб-сервису \([подробнее](ru_PP_redirect_modes.md)\). ![](images/ecommpay/ru_pp_general_3.svg) Чтобы открывать платёжную форму таким способом, на стороне веб-сервиса следует: 1. Определить события, при наступлении которых должна открываться платёжная форма\(например, переход по кнопке оплаты\). 2. Обеспечить вызов платёжной формы по требуемым событиям, с использованием собственных решений или JavaScript-библиотеки от Ecommpay, расположенной по адресу `https://paymentpage.ecommpay.com/shared/merchant.js`. Помимо прочего, эта библиотека позволяет использовать автоматическое открытие Payment Page в виде отдельной страницы на мобильных устройствах и открытие одним из других способов на других устройствах. ## Вызов с использованием собственных решений {#ru_pp_opening_html_via_in_house_solutions} Для открытия Payment Page в виде отдельной HTML-страницы достаточно перенаправить пользователя по ссылке следующего формата: ``` https://paymentpage.ecommpay.com/payment? ``` В этой ссылке `` представляет собой строку данных в виде пар названий и значений параметров \(в том числе подписи\) со знаком `&` в качестве разделителя. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). ``` https://paymentpage.ecommpay.com/payment?project_id=42&customer_id=123&payment_id=4438&payment_amount=1000&payment_currency=EUR&signature=AE5hmtzdP0Dt7qGTg... ``` ## Вызов с использованием JavaScript-библиотеки Ecommpay {#ru_pp_opening_html_via_javascript_library} Предоставляемая Ecommpay JavaScript-библиотека, прежде всего, призвана упрощать открытие платёжной формы [в модальном окне](ru_PP_method_ModalWindow.md) и [в элементе iframe](ru_PP_method_Embedded.md). Вместе с тем, она может использоваться и для открытия формы в виде отдельной HTML-страницы. Например, это может быть актуально для открытия формы в виде отдельной страницы на мобильных устройствах и в модальном окне на любых других. Для открытия Payment Page в виде отдельной страницы с использованием JavaScript-библиотеки `merchant.js` от Ecommpay необходимо подключить эту библиотеку в клиентской части веб-сервиса и использовать соответствующие обращения к объекту `EPayWidget`. Кроме того, если планируется использовать JavaScript-библиотеку `merchant.js` и для других способов открытия Payment Page, следует подключить также CSS-библиотеку, расположенную по адресу `https://paymentpage.ecommpay.com/shared/merchant.css`. **Внимание:** Следует учитывать, что для корректной работы платёжной формы CSS- и JavaScript-библиотеки от Ecommpay должны подключаться через сеть доставки содержимого \(Content Delivery Network, CDN\); локальное хранение этих библиотек не допускается. При обращениях к объекту `EPayWidget` в объекте `configObj` должен указываться один из следующих параметров: - `redirect_on_mobile` со значением `true` — для открытия платёжной формы в виде отдельной HTML-страницы только на мобильных устройствах; - `redirect` со значением `true` — для открытия платёжной формы в виде отдельной HTML-страницы на всех устройствах. Если эти параметры не указываются или неприменимы для используемого устройства, платёжная форма открывается иным способом: в модальном окне или в элементе iframe \(если это задано через соответствующий параметр `target_element`\). **Прим.:** При одновременном использовании в параметрах вызова платёжной формы указателей на открытие в отдельной вкладке и в элементе iframe более приоритетным считается открытие в отдельной вкладке. В остальном работа с объектом `EPayWidget` для открытия Payment Page в отдельной вкладке соответствует общим условиям, актуальным и для других способов открытия: 1. Каждое обращение может осуществляться одним из двух методов: - `bind` \(`EPayWidget.bind`\) — если платёжную форму необходимо открывать по щелчку кнопки \(с указанием её идентификатора, ``\); - `run` \(`EPayWidget.run`\) — если платёжную форму необходимо открывать по какому-либо другому событию в пользовательском интерфейсе. 2. В каждом обращении должен указываться JavaScript-объект `configObj`с параметрами вызова платёжной формы и с подписью к ним. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). 3. При необходимости в любом обращении может также указываться HTTP-метод отправки запроса \(`method`\)— POST или GET. Если он не указывается, по умолчанию применяется метод GET. 4. Дополнительно в любом обращении могут указываться функции-обработчики для сбора информации о действиях пользователя. Информация о таких функциях представлена в статье [Контроль интерфейсных событий](ru_pp_ui_monitoring.md). ```language-javascript EPayWidget.bind('', configObj, method); EPayWidget.run(configObj, method); ``` ```language-javascript EPayWidget.bind('pay_button_id', // Идентификатор кнопки { project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа redirect_on_mobile: true, // Указатель открытия в виде отдельной HTML-страницы // на мобильных устройствах signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` ```language-javascript EPayWidget.run( { project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа redirect_on_mobile: true, // Указатель открытия в виде отдельной HTML-страницы // на мобильных устройствах signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` HTML-код страницы веб-сервиса при этом может выглядеть следующим образом. ```language-xml ``` --- # Открытие в модальном окне {#ru_PP_method_ModalWindow .concept} статья о порядке открытия платёжной формы Payment Page в модальном окне HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений **На уровень выше:**[Способы открытия платёжной формы](ru_PP_Integration.md) ## Общая информация {#ru_pp_opening_modal_overview} При открытии в модальном окне платёжная форма Payment Page отображается поверх страницы веб-сервиса.Такой вариант прерывает взаимодействие пользователя с веб-сервисом, но при этом сохраняет контекст, фокусирует на оплате и не ведёт к переходу на другую страницу. ![](images/ecommpay/ru_pp_general_2.svg) Чтобы открывать платёжную форму в модальном окне, на стороне веб-сервиса следует: 1. Подключить в клиентской части CSS-библиотеку от Ecommpay, обеспечивающую корректное отображение платёжной формы. Эта библиотека расположена по адресу `https://paymentpage.ecommpay.com/shared/merchant.css`. 2. Настроить политику обеспечения безопасности контента с помощью директив Content Security Policy, указав в HTTP-заголовке `Content-Security-Policy` адреса источников, необходимых для корректной работы платёжной формы \([подробнее](ru_pp_interaction_organisation.md#section_m5x_m2v_njc)\). ``` {#codeblock_ejr_n4k_mjc} Content-Security-Policy: script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com; style-src https://paymentpage.ecommpay.com; img-src https://applepay.cdn-apple.com; frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com ``` 3. Определить события, при наступлении которых должна открываться платёжная форма\(например, переход по кнопке оплаты\). 4. Обеспечить вызов платёжной формы по требуемым событиям, с использованием собственных решений или JavaScript-библиотеки от Ecommpay, расположенной по адресу `https://paymentpage.ecommpay.com/shared/merchant.js`. **Внимание:** Следует учитывать, что для корректной работы платёжной формы CSS- и JavaScript-библиотеки от Ecommpay должны подключаться через сеть доставки содержимого \(Content Delivery Network, CDN\); локальное хранение этих библиотек не допускается. Для работы с платёжным методом Apple Pay при таком варианте открытия Payment Page необходимо также предварительно зарегистрировать рабочие домены веб-сервиса в сервисе Apple Pay \([подробнее](ru_dbl_projects.md)\). ## Вызов с использованием собственных решений {#ru_pp_opening_modal_via_in_house_solutions} Для открытия Payment Page в модальном окне с использованием собственных решений необходимо подготовить соответствующий скрипт, обеспечивающий вызовы формы с указанием требуемых параметров и подписи к ним. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). ## Вызов с использованием JavaScript-библиотеки Ecommpay {#ru_pp_opening_modal_via_javascript_library} Для открытия Payment Page в модальном окне с использованием JavaScript-библиотеки `merchant.js` от Ecommpay необходимо подключить эту библиотеку в клиентской части веб-сервиса и использовать соответствующие обращения к объекту `EPayWidget`. Поскольку этот вариант открытия платёжной формы является базовым для библиотеки `merchant.js`, при работе с объектом `EPayWidget` в таких случаях не требуется указывать специализированные параметры, характеризующие способ открытия, идостаточно соблюдения общих условий: 1. Каждое обращение может осуществляться одним из двух методов: - `bind` \(`EPayWidget.bind`\) — если платёжную форму необходимо открывать по щелчку кнопки \(с указанием её идентификатора, ``\); - `run` \(`EPayWidget.run`\) — если платёжную форму необходимо открывать по какому-либо другому событию в пользовательском интерфейсе. 2. В каждом обращении должен указываться JavaScript-объект `configObj` с параметрами вызова платёжной формы и с подписью к ним. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). 3. При необходимости в любом обращении может также указываться HTTP-метод отправки запроса \(`method`\)— POST или GET. Если он не указывается, по умолчанию применяется метод GET. 4. Дополнительно в любом обращении могут указываться функции-обработчики для сбора информации о действиях пользователя. Информация о таких функциях представлена в статье [Контроль интерфейсных событий](ru_pp_ui_monitoring.md). ```language-javascript EPayWidget.bind('', configObj, method); EPayWidget.run(configObj, method); ``` ```language-javascript EPayWidget.bind('pay_button_id', // Идентификатор кнопки { project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` ```language-javascript EPayWidget.run( { project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` HTML-код страницы веб-сервиса при этом может выглядеть следующим образом. ```language-xml ``` ## Управление размерами страниц сторонних сервисов {#ru_pp_opening_modal_customisation} При открытии платёжной формы в модальном окне и последующем перенаправлении к сторонним сервисам, таким как сервисы банков,платёжных систем и провайдеров, размеры окна по умолчанию автоматически подстраиваются под размеры отображаемых страниц. Вместе с тем, для дополнительной подстройки под различные ситуации \(в том числе с учётом размеров экранов пользователей\) можно указывать желаемые размеры страниц таких сервисов — тогда для страниц сторонних сервисов используются указанные размеры, за исключением случаев, когда эти страницы открываются в виде отдельных HTML-страниц. Чтобы задавать размеры страниц, используемые при переходах к сторонним сервисам, при вызове платёжной формы в составе параметра `payment_methods_options` необходимо передавать требуемые значения высоты и ширины таких страниц, определяемые как `redirect_window_height` и `redirect_window_width`. Эти параметры можно указывать двумя способами: - непосредственно в составе параметра `payment_methods_options`, как актуальные для всех сторонних сервисов, если не задано иное; - в качестве параметров для отдельных платёжных методов, указываемых через их коды \(согласно [справочнику](ru_pm_codes.md)\) в соответствии с приведённой в примере структурой. ```language-json payment_methods_options:"{ "redirect_window_height":1200, "redirect_window_width":1200, "card":\{"redirect\_window\_height":600, "redirect\_window\_width":900\}, "neteller-wallet":\{"redirect\_window\_height":900, "redirect\_window\_width":1200\} \}" ``` В приведённом примере указаны размеры, которые должны использоваться по умолчанию для всех сторонних сервисов, и размеры для отдельных платёжных методов. Эти размеры применяются следующим образом: - для всех методов, кроме `card`и `neteller-wallet`, задаются высота 1200 пикселей и ширина 1200 пикселей; - для метода `card` — задаются высота 600 пикселей и ширина 900 пикселей; - для метода `neteller-wallet` — задаются высота 900 пикселей и ширина 1200 пикселей. --- # Открытие в элементе iframe HTML-страницы {#ru_PP_method_Embedded .concept} статья о порядке открытия платёжной формы Payment Page в элементе iframe HTML-страницы с использованием JavaScript-библиотеки Ecommpay и собственных решений **На уровень выше:**[Способы открытия платёжной формы](ru_PP_Integration.md) ## Общая информация {#ru_pp_opening_iframe_overview} При открытии в элементе iframe платёжная форма Payment Page отображается как встроенная в HTML-страницу веб-сервиса.Такой вариант может не фокусировать пользователя на оплате, но при этом сохраняет контекст, не прерывает взаимодействие с веб-сервисом и не ведёт к переходу на другую страницу. ![](images/ecommpay/ru_pp_general_1.svg) **Прим.:** Размеры элемента iframe для корректного отображения платёжной формы должны составлять не менее 320 пикселей по ширине и 600 пикселей по высоте— при меньших размерах форма не отображается полностью. Версия формы для настольных устройств применяется при ширине от 480 пикселей и адаптируется к ширине элемента iframe. Ограничений по максимальным размерам не предусматривается. Чтобы открывать платёжную форму в элементе iframe, на стороне веб-сервиса следует: 1. Подключить в клиентской части CSS-библиотеку от Ecommpay, обеспечивающую корректное отображение платёжной формы. Эта библиотека расположена по адресу `https://paymentpage.ecommpay.com/shared/merchant.css`. 2. Настроить политику обеспечения безопасности контента с помощью директив Content Security Policy, указав в HTTP-заголовке `Content-Security-Policy` адреса источников, необходимых для корректной работы платёжной формы \([подробнее](ru_pp_interaction_organisation.md#section_m5x_m2v_njc)\). ``` {#codeblock_ejr_n4k_mjc} Content-Security-Policy: script-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com; style-src https://paymentpage.ecommpay.com; img-src https://applepay.cdn-apple.com; frame-src https://paymentpage.ecommpay.com https://applepay.cdn-apple.com ``` 3. Определить события, при наступлении которых должна открываться платёжная форма\(например, переход по кнопке оплаты\). 4. Обеспечить вызов платёжной формы по требуемым событиям, с использованием собственных решений или JavaScript-библиотеки от Ecommpay, расположенной по адресу `https://paymentpage.ecommpay.com/shared/merchant.js`. **Внимание:** Следует учитывать, что для корректной работы платёжной формы CSS- и JavaScript-библиотеки от Ecommpay должны подключаться через сеть доставки содержимого \(Content Delivery Network, CDN\); локальное хранение этих библиотек не допускается. Для работы с платёжным методом Apple Pay при таком варианте открытия Payment Page необходимо также предварительно зарегистрировать рабочие домены веб-сервиса в сервисе Apple Pay \([подробнее](ru_dbl_projects.md)\). ## Вызов с использованием собственных решений {#ru_pp_opening_iframe_via_in_house_solutions} Для открытия Payment Page в элементе iframe с использованием собственных решений необходимо подготовить соответствующий скрипт, обеспечивающий вызовы формы с указанием требуемых параметров и подписи к ним. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). ## Вызов с использованием JavaScript-библиотеки Ecommpay {#ru_pp_opening_iframe_via_javascript_library} Для открытия Payment Page в элементе iframe с использованием JavaScript-библиотеки `merchant.js` от Ecommpay необходимо подключить эту библиотеку в клиентской части веб-сервиса и использовать соответствующие обращения к объекту `EPayWidget`. При этих обращениях должен указываться идентификатор используемого элемента iframe — в параметре `target_element` объекта `configObj`. Если этот параметр не указывается, платёжная форма открывается иным способом: в модальном окне или в виде отдельной HTML-страницы \(если это задано через параметр `redirect` или `redirect_on_mobile`\). **Прим.:** При одновременном использовании в параметрах вызова платёжной формы указателей на открытие в отдельной вкладке и в элементе iframe более приоритетным считается открытие в отдельной вкладке. В остальном работа с объектом `EPayWidget` в таких случаях соответствует общим условиям, актуальным и для других способов открытия: 1. Каждое обращение может осуществляться одним из двух методов: - `bind` \(`EPayWidget.bind`\) — если платёжную форму необходимо открывать по щелчку кнопки \(с указанием её идентификатора, ``\); - `run` \(`EPayWidget.run`\) — если платёжную форму необходимо открывать по какому-либо другому событию в пользовательском интерфейсе. 2. В каждом обращении должен указываться JavaScript-объект `configObj` с параметрами вызова платёжной формы и с подписью к ним. Информация о применяемых параметрах и их подписывании представлена в отдельных статьях: [Спецификация Payment Page API](ru_PP_Parameters.md) и [Работа с подписью к данным](ru_platform_signature.md). 3. При необходимости в любом обращении может также указываться HTTP-метод отправки запроса \(`method`\)— POST или GET. Если он не указывается, по умолчанию применяется метод GET. 4. Дополнительно в любом обращении могут указываться функции-обработчики для сбора информации о действиях пользователя. Информация о таких функциях представлена в статье [Контроль интерфейсных событий](ru_pp_ui_monitoring.md). ```language-javascript EPayWidget.bind('', configObj, method); EPayWidget.run(configObj, method); ``` ```language-javascript EPayWidget.bind('pay_button_id', // Идентификатор кнопки { target_element: 'widget-container', // Идентификатор элемента project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` ```language-javascript EPayWidget.run( { target_element: 'widget-container', // Идентификатор элемента project_id: 42, // Идентификатор проекта customer_id: '17008', // Идентификатор пользователя payment_id: '18641868', // Идентификатор платежа payment_amount: 8855, // Сумма платежа payment_currency: 'USD', // Код валюты платежа signature: 'YWb6Z20ByxpQ30hfTI' }, // Подпись 'post') ``` HTML-код страницы веб-сервиса при этом может выглядеть следующим образом. ```language-xml
...
``` ## Управление размерами страниц сторонних сервисов {#ru_pp_opening_iframe_customisation} Чтобы задавать размеры страниц, используемые при переходах пользователя от Payment Page к сторонним сервисам, при вызове платёжной формы в составе параметра `payment_methods_options` необходимо передавать требуемые значения высоты и ширины таких страниц, определяемые как `redirect_window_height` и `redirect_window_width`. Эти параметры можно указывать двумя способами: - непосредственно в составе параметра `payment_methods_options`, как актуальные для всех сторонних сервисов, если не задано иное; - в качестве параметров для отдельных платёжных методов, указываемых через их коды \(согласно [справочнику](ru_pm_codes.md)\) в соответствии с приведённой в примере структурой. Следует учитывать, что указываемые размеры не применяются в случаях, когда страницы сторонних сервисов открываются в отдельной вкладке. ```language-json payment_methods_options:"{ "redirect_window_height":1200, "redirect_window_width":1200, "card":\{"redirect\_window\_height":600, "redirect\_window\_width":900\}, "neteller-wallet":\{"redirect\_window\_height":900, "redirect\_window\_width":1200\} \}" ``` В приведённом примере указаны размеры, которые должны использоваться по умолчанию для всех сторонних сервисов, и размеры для отдельных платёжных методов. Эти размеры применяются следующим образом: - для всех методов, кроме `card`и `neteller-wallet`, задаются высота 1200 пикселей и ширина 1200 пикселей; - для метода `card` — задаются высота 600 пикселей и ширина 900 пикселей; - для метода `neteller-wallet` — задаются высота 900 пикселей и ширина 1200 пикселей. --- # Способы перенаправления пользователей к сторонним сервисам {#ru_PP_pm_redirect_mode} статья о вариантах открытия вспомогательных страниц сторонних сервисов при работе с разными платёжными методами ## Общая информация {#section_ufh_2nd_c5b .section} При проведении платежей может требоваться перенаправлять пользователей со страниц платёжной формы к сервисам третьих сторон, таких какбанки, платёжные системыи провайдеры.Это может быть необходимымдля аутентификации пользователей, подтверждения ими платежей и выполнения иных действийи может выглядеть следующим образом. ![](images/ecommpay/ru_pp_pm_redirect_mode_1.svg "Автоматическое перенаправление") ![](images/ecommpay/ru_pp_pm_redirect_mode_2.svg "Перенаправление с подтверждением") В платёжной платформе Ecommpay поддерживаются различные способы таких перенаправлений: с открытием страниц сторонних сервисовв объекте iframe, в используемой или в новой вкладке браузера\(новая вкладка может открываться автоматически, без подтверждения пользователем, или с таким подтверждением: по щелчку кнопки или по истечении заданного времени\). По умолчанию для каждого метода, с учётом его специфики, в платформе используется один из этих способов. Вместе с тем, при подключении метода в рамках конкретного проекта можно согласовать со специалистами технической поддержки применение иного способа\(из числа доступных для этого метода\). И наконец, для отдельных платежей можно задавать перенаправление в отдельной вкладке через параметры вызова Payment Page. ## Формат запросов {#section_spp_fnd_c5b .section} Если для отдельного платежа требуется указать способ открытия страницы стороннего сервиса в новой вкладке браузера, игнорируя способ, заданный для методав целом, в запросе необходимо передать булевый параметр `force_acs_new_window` со значением `1`.\(Использование этого параметра со значением `0` не влияет на способы перенаправления.\) В следующем примере для проведения оплаты предварительно указан метод Open Banking in Romania, а также задан способ открытия страницы банка Banca Comerciala Romana, поддерживающего оплату этим методом — в отдельной вкладке. ```language-json { payment_id: "X03936", payment_amount: 1000, payment_currency: "EUR", project_id: 123, customer_id: "customer1", force_payment_method: "online-romanian-banks", payment_methods_option: { "online_romanian_banks": { "banks_id": [55941] } }, force_acs_new_window: 1, // способ открытия страницы банка signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg==" } ``` ```language-json { payment_id: "X03936", payment_amount: 1000, payment_currency: "EUR", project_id: 123, customer_id: "customer1", force_payment_method: "online-romanian-banks", payment_methods_option: { "online_romanian_banks": { "banks_id": [55941] } }, force_acs_new_window: 1, // способ открытия страницы банка signature: "kUi2x9dKHAVNU0FYldJrxh4...zUCwX6R\/ekpZhkIQg==" } ``` ## Дополнительные материалы {#section_v5y_gnd_c5b .section} При работе с различными перенаправлениями пользователей могут быть полезны следующие материалы: - [Способы возвращения пользователей к веб-сервису](ru_PP_redirect_modes.md)— с информацией о перенаправлении пользователей со страниц платёжной формы к веб-сервису. - [Методы](ru_pm_about.md)— с информацией о платёжных методах и работе с ними. - [Спецификация Payment Page API](ru_PP_Parameters.md)— с описанием параметров, которые могут использоваться в запросах на открытие Payment Page. **На уровень выше:**[Управление формой](ru_pp_ux_configuration.md) --- # Способы возвращения пользователей к веб-сервису {#ru_PP_redirect_modes .concept} статья о вариантах перенаправления пользователей от платёжной формы к веб-сервису по заданным адресам **На уровень выше:**[Управление формой](ru_pp_ux_configuration.md) ## Общая информация {#ru_pp_redirect_modes_overview} После открытия платёжной формы могут быть актуальны разные варианты возвращения пользователя к веб-сервису. При работе с Payment Page эти варианты делятся на три вида: - *предварительное возвращение из платёжной формы* — когда пользователю по какой-либо причине надо вернуться к веб-сервису до подтверждения платежа в платёжной форме, а затем, возможно, назад к форме, чтобы продолжить работу с ней; - *промежуточное возвращение из сторонних сервисов* — когда пользователю по какой-либо причине надо вернуться к веб-сервису после подтверждения платежа в платёжной форме и перенаправления к стороннему сервису, не завершив свои действия там; - *итоговое возвращение* — когда пользователю надо вернуться к веб-сервису после выполнения всех необходимых действий для проведения платежа. Со стороны мерчанта можно предоставлять пользователям различные возможности для возвращения\(используя только необходимые варианты или не используя вовсе никаких\) и сочетать такие возможности с индивидуальным оформлением платёжной формы \([подробнее](ru_PP__design_customisation.md)\) иразными способами открытия страниц веб-сервиса при перенаправлениях к нему.Это позволяет гибко подстраиваться под специфику бизнеса и разнообразных платёжных сценариев. ## Варианты возвращения {#ru_pp_redirect_modes_options} ### Предварительное возвращение из платёжной формы {#ru_pp_redirect_modes_before_payment} #### Общая информация {#section_wm2_4cw_k5b .section} Для предварительного возвращения пользователей к веб-сервисусо страниц платёжной формы используется ссылка, которая задаётся через параметры вызова и отображается как дополнительный элемент формы. ![](images/ecommpay/ru_pp_redirect_modes_1.svg) Если при вызове Payment Page задаётся возможность предварительного возвращения из формы, то по умолчанию для этого применяются следующие способы: - при открытии Payment Page в отдельной вкладке перенаправление выполняется в этой же вкладке; - при открытии Payment Page в модальном окне это модальное окно закрывается; - при открытии Payment Page в объекте iframe перенаправление не выполняется, при этом на стороне веб-сервиса доступна обработка интерфейсных событий \([подробнее](ru_pp_ui_monitoring.md)\). Если необходимо задействовать иные способывозвращения, со стороны веб-сервисаможно использовать соответствующие параметры, описанные далее,в разделе [Управление доступностью и способами возвращения](ru_PP_redirect_modes.md) этой статьи. Также, применяя возможность предварительного возвращениясо страниц платёжной формы, необходимо учитывать следующие особенности: - Пользователь может вернуться к веб-сервису по отображаемой ссылке только до того, как он подтвердит платёж в платёжной форме\(выбрав метод и указав требуемую информацию\). После подтверждения платежа ссылка в форме не отображается, поскольку подтверждение ведёт к проведению платежа в платформе и выбранной платёжной системе и это может требовать участия пользователя. - При ограничении времени работы с платёжной формой\([подробнее](ru_pp_time_limit.md)\) обратный отсчёт начинается с момента первичного открытия формы и не останавливается при возвращении пользователя к веб-сервису. #### Формат запросов {#section_itp_zjw_k5b .section} Адрес для предварительного возвращения к веб-сервису со страниц платёжной формыуказывается в запросах на открытие Payment Page в значении параметра `merchant_return_url`. ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", // адрес для предварительного возвращения "merchant_return_url": "https://example.com", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ### Промежуточное возвращение из сторонних сервисов {#ru_pp_redirect_modes_intermediate} #### Общая информация {#section_vdw_1sr_stb .section} Возвращение к веб-сервису со страниц сторонних сервисов, таких как сервисы банковили платёжных систем, возможно только когда это поддерживается с их стороны. Кроме того, в разных сервисах такая функциональность может реализовываться по-разному и может допускать или не допускать обратных возвращений пользователя. С учётом таких особенностей, а также потенциально негативного влияния на проходимость платежей применение возвращений со страниц сторонних сервисов следует предварительно согласовывать с курирующим менеджером Ecommpay. ![](images/ecommpay/ru_pp_redirect_modes_2.svg) После согласования и подключения такой возможности адреса для возвращения пользователей можно указывать в запросах на открытие Payment Page.Иначе эти адреса игнорируются. #### Формат запросов {#section_dsy_hsr_stb .section} Адрес для промежуточного возвращения к веб-сервису со страниц сторонних сервисовуказывается в запросах на открытие Payment Page в значении параметра `redirect_return_url`. ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", // адрес для промежуточного возвращения "redirect_return_url": "https://your/bank/example.com", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ### Итоговое возвращение {#ru_pp_redirect_modes_final} #### Общая информация {#section_lbc_qtr_stb .section} При работе с Payment Page итоговое возвращение пользователя к веб-сервису — по результатам проведения платежа — может реализовываться с отображением итоговой страницы платёжной формы, содержащей кнопку для возвращения к веб-сервису *по решению пользователя*, и *автоматически*, минуя итоговую страницу платёжной формы и с информированием о результате оплаты сразу на стороне веб-сервиса.При этом автоматическое возвращение не позволяет предоставить пользователю повторные попытки оплаты \([подробнее](ru_PP_Try_Again.md)\). Также, если итоговое возвращение не актуально, можно отображать пользователю итоговую страницу Payment Page без кнопки для возвращения к веб-сервису. ![](images/ecommpay/ru_pp_redirect_modes_3.svg "Итоговое возвращение по решению пользователя") ![](images/ecommpay/ru_pp_redirect_modes_4.svg "Итоговое автоматическое возвращение") ![](images/ecommpay/ru_pp_redirect_modes_5.svg "Вариант работы без возможности возвращения") Адреса и способы итогового возвращения могут задаваться как общие для всех платежей в рамках проекта и частные для отдельных платежей. Для указания общих адресов и способов необходимо использовать интерфейс Dashboard \(и инструменты карточки **Ссылки для перенаправления** в разделе **Проекты**\), для указания частных адресов и способов — параметры запросов на открытие Payment Page \(описанные далее, в пункте [Формат запросов](ru_PP_redirect_modes.md#section_yft_gvr_stb) этого раздела и в разделе [Управление доступностью и способами возвращения](ru_PP_redirect_modes.md) этой статьи\). По умолчанию в случаях, когда используется итоговое возвращение, для него применяются следующие способы: - *Возвращение по решению пользователя* выполняется в используемой вкладке браузера, с закрытием модального окна, если платёжная форма была открыта в нём. - *Автоматическое возвращение* выполняется в том же элементе интерфейса, в которым была открыта платёжная форма.Так, если форма была открыта в отдельной вкладке браузера, то возвращение выполняется в этой же вкладке, а если форма была открыта в модальном окне или в объекте iframe, то возвращение выполняется в этом же окне или объекте. #### Формат запросов {#section_yft_gvr_stb .section} *Для возвращения по решению пользователя* можно задавать адреса в значениях следующих параметров: - `merchant_success_url` — для возвращения при проведении оплаты, - `merchant_fail_url` — для возвращения при отклонении оплаты. ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", // адреса для итогового возвращения по решению пользователя "merchant_success_url": "https://example.com/complete-redirect?id=success", "merchant_fail_url": "https://example.com/complete-redirect?id=decline", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." ``` *Для автоматического возвращения* можно задавать адреса в значениях следующих параметров: - `redirect_success_url` — для возвращения при проведении оплаты, - `redirect_fail_url` — для возвращения при отклонении оплаты, - `redirect_tokenize_url` — для возвращения при формировании токена платёжных данных в режиме `card_tokenize` \([подробнее](ru_pp_token.md)\). ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": "131970", "customer_id": "customer_12", // адреса для автоматического итогового возвращения "redirect_success_url": "https://example.com/complete-redirect?id=success", "redirect_fail_url": "https://example.com/complete-redirect?id=decline", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." ``` ## Управление доступностью и способами возвращения {#ru_pp_redirect_modes_opening_pages} При работе с предварительным и итоговым возвращениями пользователейот платёжной формы к веб-сервису можно управлять доступностью и способами этих возвращений в рамках отдельных вызовов Payment Page. Для этого используются параметры групп `enabled` и `mode`. - `merchant_return_enabled` — доступность предварительного возвращениясо страниц платёжной формы, - `merchant_success_enabled` — доступность итогового возвращения при проведении оплаты, - `merchant_fail_enabled` — доступность итогового возвращения при отклонении оплаты. Для каждого из этих параметров допустимы следующие значения: - `0` — отсутствие доступа к возможности возвращения; - `1` — частичная доступность возвращения, в рамках которой при открытии Payment Page в объекте iframe или модальном окне перенаправление к веб-сервису не выполняется, а при открытии Payment Page в отдельной вкладке браузера способ открытия страницы веб-сервиса определяется через параметр группы `mode`; - `2` — полная доступность возвращения, используемая по умолчанию и сочетаемая со способом открытия страницы веб-сервиса, указанным в параметре группы mode. - `merchant_return_redirect_mode` — способ предварительного возвращениясо страниц платёжной формы, - `merchant_success_redirect_mode` — способ итогового возвращения по решению пользователя при проведении оплаты, - `merchant_fail_redirect_mode` — способ итогового возвращения по решению пользователя при отклонении оплаты, - `redirect_success_mode` — способ автоматического итогового возвращения при проведении оплаты, - `redirect_fail_mode` — способ автоматического итогового возвращения при отклонении оплаты. Для каждого из этих параметров допустимы следующие значения: - `iframe` — открытие страницы в объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницы в используемой вкладке; - `blank_page` — открытие страницы в новой вкладке. В следующих примерах приведены данные из запросов на открытие Payment Page, согласно которым возвращение к веб-сервису должно выполняться разными способами. ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", // адрес страницы веб-сервиса "merchant_success_url": "https://example.com/complete-redirect?id=success", "merchant_success_redirect_mode": "blank_page", // способ открытия страницы "merchant_success_enabled": 2, // доступность возвращения "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." ``` ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", // адрес страницы веб-сервиса "merchant_success_url": "https://example.com/complete-redirect?id=success", "merchant_success_redirect_mode": "parent_page", // способ открытия страницы "merchant_success_enabled": 1, // доступность возвращения "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." ``` С вопросами о работе с этими параметрами, как и с другими вопросамио способах возвращения пользователей к веб-сервису, можно обращаться к специалистам технической поддержки Ecommpay. --- # Основные действия {#ru_pp_basic_actions} статьи об основных действиях, которые можно выполнять с помощью платёжной формы, с описанием пользовательских сценариев, а также форматов запросов и оповещений, актуальных при работе с классическими карточными платежами Материалы об основных действиях, которые можно выполнять с помощью платёжной формы, с описанием логических моделей, пользовательских сценариев и форматов запросов и оповещений: - [Проведение платежей](ru_platform_payment_model.md)— о типах платежей, которые можно проводить через Payment Page, схемах их проведения и возможных статусах платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о проведении оплат с незамедлительным списанием средств. - [Блокировка средств](ru_pp_purchase_auth.md)— о выполнении блокировки средств в рамках двухстадийной оплаты. - [Регистрация повторяемых оплат](ru_pp_recurring.md)— о регистрации оплат с последующими списаниями. - [Проведение выплат](ru_pp_payout.md)— о проведении выплат. - [Проверка платёжных инструментов](ru_pp_account_verification.md)— о выполнении условного списания или блокировки средств с целью проверки действительности платёжного инструмента. - [Формирование токенов](ru_pp_token.md)— о вызове платёжной формы для регистрации платёжных данных и формировании их токена. - **[Проведение оплат](ru_pp_purchase.md)** статья о порядке проведения через Payment Page одностадийных оплат с незамедлительными списаниями - **[Блокировка средств](ru_pp_purchase_auth.md)** статья о порядке выполнения через Payment Page предварительных блокировок средств в рамках двухстадийных оплат с последующими списаниями - **[Регистрация повторяемых оплат](ru_pp_recurring.md)** статья о порядке регистрации через Payment Page оплат с сериями повторяемых списаний - **[Проведение выплат](ru_pp_payout.md)** статья о порядке проведения через Payment Page выплат - **[Проверка платёжных инструментов](ru_pp_account_verification.md)** статья о порядке проверки через Payment Page действительности платёжных инструментов с условными списаниями или временными блокировками средств - **[Формирование токенов](ru_pp_token.md)** статья о порядке вызова платёжной формы для регистрации платёжных данных и формирования их токенов **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Проведение оплат {#ru_pp_purchase} статья о порядке проведения через Payment Page одностадийных оплат с незамедлительными списаниями **Прим.:** Эта статья посвящена тому, как проводить разовые оплаты в одну стадию через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с разовыми оплатами в одну стадию могут быть полезны: - статья [Разовая оплата в одну стадию](ru_platform_sms_model.md) модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в одну стадию в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить разовые оплаты в одну стадию через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. ## Общая информация {#section_rgf_sbq_4lb .section} *Разовая оплата в одну стадию*, или *разовая одностадийная оплата* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один \(разовый\) перевод денежных средств от пользователя к мерчанту. Операция возврата средств пользователю в рамках разовой одностадийной оплаты осуществляется с помощью интерфейсов [Gate](ru_Gate_Refund.md) или [Dashboard](ru_dbl_payments.md). С помощью Payment Page можно проводить разовые оплаты в одну стадию с использованием платёжных картили других платёжных инструментов, в том числе оплаты Mail Order/Telephone Order \(MO/TO\), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. При добавлении новой карты для проведения оплаты сохраняются её платёжные данные и формируется токен платёжной карты, если это настроено для проекта мерчанта \(подробнее — в разделе [Формирование токенов](ru_pp_token.md)\). Для выполнения этих операций используется режим работы платёжной формы Purchase. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача параметра `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_pp_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. Базовыми действиями пользователя при проведении разовой одностадийной оплаты с использованием Payment Page могут быть выбор платёжного инструмента, указание его реквизитов и ожидание уведомления о результате платежа. ![](images/ecommpay/ru_pp_purchase_1.svg) При проведении одностадийной оплаты через Payment Page платёжные данные могут быть указаны одним из следующих способов: - *Через ввод на форме.* В этом случае пользователь обязательно заполняет на форме все требуемые поля. Для карт из числа обязательных полей можно исключить имя держателя карты, по согласованию с курирующим менеджером Ecommpay, после анализа и оценки рисков. - *Через выбор или ввод на форме.* В этом варианте, когда при вызове Payment Page был указан идентификатор пользователя, пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем. В дополнение к выбранным реквизитам для некоторых инструментов требуется подтверждение, такое как ввод проверочного кода \(CVC, CVV, CID\) при работе с платёжными картами. - *Через выбор до вызова формы.* В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты, и платёжная форма открывается с указанием всех реквизитов кроме проверочного кода \(CVC, CVV, CID\), который необходимо указать непосредственно на форме. ![](images/ecommpay/ru_pp_purchase_2.svg) *Payment Page при разных способах указания платёжных данных: при заполнении через ввод на форме, выборе из уже сохранённых данных и выборе конкретной карты до вызова формы, соответственно.* ## Схема работы {#section_ifd_3dq_4lb .section} Для проведения оплаты с помощью Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page. 2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы. При проведении оплаты могут выполняться вспомогательные процедуры: - *Аутентификация 3‑D Secure*, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\). - *Аутентификация по инициативе мерчанта*, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения. - *Дополнение информации о платеже*, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме. Такие процедуры выполняются без участия веб-сервиса мерчанта, но, как правило, требуют участия пользователя. Информация о форматах запросов и оповещений при проведении оплат с прямым использованием платёжных карт представлена далее, а о форматах запросов и оповещений при проведении оплат с использованием других платёжных методов, в разделе — [Методы](ru_pm_about.md). ## Формат запросов {#section_cwk_krt_rlb .section} Формат запроса на открытие Payment Page для проведения одностадийной оплаты с использованием платёжной карты соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. В запросе должны использоваться следующие обязательные параметры: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `customer_id` — идентификатор пользователя, уникальный в рамках проекта; - `payment_amount` — сумма платежа в дробных единицах валюты; - `payment_currency` — код валюты платежа в формате ISO 4217 alpha-3; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для проведения одностадийной оплаты в случае, если по запросу мерчанта в рамках проекта по умолчанию настроена блокировка средств, в запросе дополнительно необходимо использовать параметр `operation_type` \([подробнее](ru_PP_Parameters.md)\)со значением `sale`; иначе использование этого параметра не требуется. 3. Для указания обязательных сведений о пользователе в случае, если не используется возможность указания таких сведений самим пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\), в запросе дополнительно необходимо использовать по крайней мере один из следующих параметров: `customer_email` и `customer_phone`. 4. Для предварительного выбора платёжной карты в запросе дополнительно необходимо использовать параметр `account_token`, в котором необходимо передать токен платёжной карты. 5. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\). 6. Для добавления описания платежа в запросе дополнительно необходимо использовать параметр `payment_description`, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа. 7. Для проведения оплаты Mail Order \(MO\) в запросе дополнительно необходимо использовать параметр `moto_type` со значением `1`, а для проведения оплаты Telephone Order \(TO\) — со значением `2`. 8. Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Purchase. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, корректный запрос на проведение оплаты с использованием платёжной карты должен содержать идентификаторы проекта, пользователя и платежа, подпись, код валюты и сумму платежа. Остальные параметры также могут использоваться в запросах, но не являются обязательными. ```language-json { "project_id": "42", "payment_id": "456789", "payment_currency": "USD", "payment_amount": "131970", "customer_id": "customer_12", "customer\_phone": "44991234567", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." // при проведении оплаты по предварительно выбранной карте: "account_token":"959c664ad6045679d71d89caff6c242a0..." } ``` ```language-json https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&customer_id=customer_12&customer\_phone=44991234567&project_id=42&payment_amount=131970&payment_id=456789&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB... ``` ## Формат оповещений {#section_i4t_vcn_slb .section} Формат оповещения о результатах проведения оплат в одну стадию с использованием платёжных карт соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` была проведена оплата в одну стадию в размере `1 319,70 USD` с использованием платёжной карты `431422******0056`. ```language-json { "account": { "number": "431422****0056", "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type": "visa", "card_holder": "JOHN SMITH", "id": 45678, "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2019-01-11T13:02:42+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 131970, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2019-01-11T13:02:42+0000", "created_date": "2019-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 131970, "currency": "USD" }, "sum_converted": { "amount": 131970, "currency": "USD" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2019-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении оплаты. Оплата отклонена из-за ввода некорректных данных карты. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "decline", "date": "2019-01-11T14:11:33+0000", "method": "card", "sum": { "amount": 131970, "currency": "USD" }, "description": "" }, "account": { "number": "431422****0056", "type": "visa", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 13300000004505, "type": "sale", "status": "decline", "date": "2019-01-11T14:11:33+0000", "created_date": "2019-01-11T14:11:00+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 131970, "currency": "USD" }, "sum_converted": { "amount": 131970, "currency": "USD" }, "provider": { "id": 12, "payment_id": "48219213050", "auth_code": "", "endpoint_id": 12 }, "code": "10102", "message": "Incorrect data entered", "eci": "05" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Блокировка средств {#ru_pp_purchase_auth} статья о порядке выполнения через Payment Page предварительных блокировок средств в рамках двухстадийных оплат с последующими списаниями **Прим.:** Эта статья посвящена тому, как выполнять первую стадию оплат в две стадии \(блокировку средств\) через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с разовыми оплатами в две стадии могут быть полезны: - статья [Разовая оплата в две стадии](ru_platform_dms_model.md) модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в две стадии в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как выполнять первую стадию оплат в две стадии \(блокировку средств\) через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. ## Общая информация {#section_gjj_gnh_bmb .section} *Оплата в две стадии*, или *разовая двухстадийная оплата* — это вариант проведения разовой оплаты, в рамках которого для перевода денежных средств от пользователя к мерчанту сначала, на основании исходного запроса, осуществляется предварительная блокировка, а затем, на основании подтверждающего запроса или по истечении заданного периода, — списание заблокированных средств или отмена блокировки. **Прим.:** В случае открытия платёжной формы для блокировки средств \(при указании значения `auth` параметра `operation_type`\) пользователю отображаются только те платёжные методы, для которых поддерживаются оплаты в две стадии \([подробнее](ru_pm_about.md)\). С использованием Payment Page можно выполнять первую стадию оплат в две стадии — блокировку средств пользователя, в том числе с использованием возможности Mail Order/Telephone Order \(MO/TO\). Для этого используется режим работы платёжной формы Purchase. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача параметра `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_pp_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. Базовыми действиями пользователя при выполнении первой стадии разовой двухстадийной оплаты с использованием Payment Page могут быть: выбор платёжного инструмента, указание его реквизитов и ожидание уведомления о результате платежа. ![](images/ecommpay/ru_pp_purchase_auth_1.svg) Для выполнения второй стадии — списания заблокированных средств или отмены блокировки — следует использовать [Gate](ru_gate_payment_auth.md)или [Dashboard](ru_dbl_payments.md), либо настроить автоматическое выполнение этой стадии по истечении заданного срока. По вопросам настройки данной функциональности следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com). При выполнении блокировки средств платёжные данные могут быть указаны одним из следующих способов: - *Через ввод на форме.* В этом случае пользователь обязательно заполняет на форме все требуемые поля. Для карт из числа обязательных полей можно исключить имя держателя карты, по согласованию с курирующим менеджером Ecommpay, после анализа и оценки рисков. - *Через выбор или ввод на форме.* В этом варианте, когда при вызове Payment Page был указан идентификатор пользователя, пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем. В дополнение к выбранным реквизитам для некоторых инструментов требуется подтверждение, такое как ввод проверочного кода \(CVC, CVV, CID\) при работе с платёжными картами. - *Через выбор до вызова формы.* В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты, и платёжная форма открывается с указанием всех реквизитов кроме проверочного кода \(CVC, CVV, CID\), который необходимо указать непосредственно на форме. ![](images/ecommpay/ru_pp_purchase_auth_2.svg) *Payment Page при разных способах указания платёжных данных: при заполнении через ввод на форме, выборе из уже сохранённых данных и выборе конкретной карты до вызова формы соответственно.* ## Ограничения {#section_cmc_b3s_1mb .section} При выполнении блокировки средств необходимо учитывать, что в соответствии с требованиями платёжных систем Visa, Mastercard и American Express срок, на который можно заблокировать средства пользователя, ограничивается. И для различных типов карт этот срок определяется с учётом разных условий: - Для карт платёжной системы Visa: 1. если блокировка средств выполняется в рамках повторяемой оплаты или с её регистрацией — 5 дней; 2. если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code \(MCC\) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 30 дней; 3. в других случаях — 10 дней. - Для карт Maestro и Cirrus — 6 дней. - Для другихкарт платёжной системы Mastercard — 28 дней. - Для карт платёжной системы American Express: 1. если в соответствии с присвоенным мерчанту кодом Merchant Category Code \(MCC\) его деятельность относится к гостиничному бизнесу, аренде автомобилей или организации круизов — на весь срок проживания, аренды или круиза соответственно; 2. в других случаях — 7 дней. Максимально допустимый срок блокировки средств отсчитывается от момента формирования в платёжной платформе Ecommpay операции блокировки \(`auth`\). За полчаса до истечения этого срока в зависимости от параметров, указанных сотрудниками Ecommpay, автоматически выполняется одна из следующих операций: списание заблокированных средств пользователя \(`capture`\) или отмена блокировки средств \(`cancel`\). После этого к веб-сервису направляется оповещение о списании средств. Для уточнения информации и изменения типа операции следует обратиться к курирующему менеджеру Ecommpay. Исключением являются блокировки с использованием карт платёжной системы American Express, максимально допустимый срок для которых соответствует сроку проживания, аренды или круиза: для таких блокировок автоматическое списание не выполняется. В случаях, когда в платёжной платформе настроено автоматическое списание или отмена блокировки средств в указанный со стороны мерчанта срок, но этот срок превышает максимально допустимый, списание или отмена выполняются в соответствии с максимально допустимым сроком.Допустим, в соответствии с пожеланиями мерчанта настроена автоматическая отмена блокировки по истечении десяти дней. Тогда для блокировки средств, выполненной с использованием карты Maestro \(с максимально допустимым сроком в шесть дней\), по истечении шести дней выполняется автоматическая отмена. ## Схема работы {#section_d1w_tb4_slb .section} Для выполнения блокировки средств с помощью Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page. 2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы. При выполнении блокировки средств со стороны платёжной платформы может быть инициировано выполнение вспомогательных процедур, требующих участия пользователя: - *Аутентификация 3‑D Secure*, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\). - *Аутентификация по инициативе мерчанта*, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения. - *Дополнение информации о платеже*, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме. Информация о форматах запросов и оповещений при выполнении блокировки средств с прямым использованием платёжных карт представлена далее, а о форматах запросов и оповещений при выполнении блокировки средств с использованием других платёжных методов, представлена в разделе [Методы](ru_pm_about.md). ## Формат запросов {#section_nz2_tg4_slb .section} Формат запроса на открытие Payment Page для выполнения блокировки соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. В запросе должны использоваться следующие обязательные параметры: - `operation_type` — тип операции для проведения оплаты; если по запросу мерчанта в рамках проекта по умолчанию настроена оплата, в параметре необходимо указывать значение `auth`\([подробнее](ru_PP_Parameters.md)\); - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `customer_id` — идентификатор пользователя, уникальный в рамках проекта; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_amount` — сумма платежа в дробных единицах валюты; - `payment_currency` — код валюты платежа в формате ISO 4217 alpha-3; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для указания обязательных сведений о пользователе в случае, если не используется возможность указания таких сведений самим пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\), в запросе дополнительно необходимо использовать по крайней мере один из следующих параметров: `customer_email` и `customer_phone`. 3. Для предварительного выбора платёжной карты в запросе дополнительно необходимо использовать параметр `account_token`, в котором необходимо передать токен платёжной карты. 4. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\). 5. Для добавления описания платежа в запросе дополнительно необходимо использовать параметр `payment_description`, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа. 6. Для проведения оплаты Mail Order \(MO\) в запросе дополнительно необходимо использовать параметр `moto_type` со значением `1`, а для проведения оплаты Telephone Order \(TO\) — со значением `2`. 7. Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Purchase. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, корректный запрос на проведение оплаты в две стадии должен содержать идентификаторы проекта, пользователя и платежа, тип платёжной операции `auth`, код валюты платежа, сумму платежа и подпись. Остальные параметры также могут использоваться в запросах, но не являются обязательными. ```language-json { "operation_type": "auth", "project_id": 42, "payment_id": "456789", "customer_id": "customer_12", "payment_currency": "USD", "payment_amount": "2000", "customer\_phone": "44991234567", "signature": "TSzdE5rJZaA9VyJtnfRI3620jOp2hf4RKwmKoWYjTYAK2MxF...", // при проведении оплаты по предварительно выбранной карте: "account_token":"959c664ad64b8caa54bb7836ddc737fd1a679242a039..." } ``` ```language-json https://https://paymentpage.ecommpay.com/payment?payment_currency=USD&language_code=en&project_id=42&payment_amount=2000&payment_id=456789&operation_type=auth&customer_id=customer_12&customer\_phone=44991234567&signature=xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhZLxEzkgcoZr... ``` ## Формат оповещений {#section_kjt_kt4_slb .section} Формат оповещения о результатах выполнения блокировок соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` заблокированы средства в размере `2 000,00 USD` с использованием платёжной карты `541333******0019`. ```language-json { "project_id": 42, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "id": "456789", "type": "purchase", "status": "awaiting capture", "date": "2019-01-11T13:00:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "USD" }, "description": "" }, "account": { "number": "541333****0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "operation": { "id": 2777000002350, "type": "auth", "status": "success", "date": "2020-01-11T13:00:40+0000", "created_date": "2020-01-11T13:00:37+0000", "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9", "sum_initial": { "amount": 200000, "currency": "USD" }, "sum_converted": { "amount": 200000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "224750650", "date": "2020-01-11T13:00:39+0000", "result_code": "000", "result_message": "Approved", "auth_code": "505050", "endpoint_id": 120 }, "code": "0", "message": "Success", "description": "SUCCESS", "eci": "00" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` В следующем примере блокировка средств была отклонена из-за ввода некорректной даты окончания срока действия карты. ```language-json { "project_id": 42, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "id": "456789", "type": "purchase", "status": "decline", "date": "2020-01-11T13:00:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "USD" }, "description": "" }, "account": { "number": "541333****0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "operation": { "id": 6304000002973, "type": "auth", "status": "decline", "date": "2020-01-11T13:00:40+0000", "created_date": "2019-01-11T13:00:34+0000", "request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c", "sum_initial": { "amount": 200000, "currency": "USD" }, "sum_converted": { "amount": 200000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "239689120", "date": "2020-01-11T13:00:36+0000", "result_code": "101", "result_message": "Decline, expired card", "auth_code": "", "endpoint_id": 120 }, "code": "10106", "message": "Card expired", "description": "Bank cards. Operation was declined due to incorrect card expiry date entry", "eci": "00" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` В следующем примере содержится информация о том, что в рамках проекта `42` с платёжной карты `№555555******4445` пользователя `customer_12` списаны заблокированные ранее средства в размере `2 000,00 USD`. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "success", "date": "2020-01-11T15:54:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "USD" }, "description": "" }, "account": { "number": "541333****0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 7178000006597, "type": "capture", "status": "success", "date": "2020-01-11T15:54:40+0000", "created_date": "2019-01-11T15:54:39+0000", "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0", "sum_initial": { "amount": 200000, "currency": "USD" }, "sum_converted": { "amount": 200000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "227307324", "date": "2020-01-11T15:54:40+0000", "auth_code": "919372", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` отменена блокировка средств в размере `2 000,00 USD` на платёжной карте `№555555******4445`. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "canceled", "date": "2020-01-11T15:54:40+0000", "method": "card", "sum": { "amount": 200000, "currency": "USD" }, "description": "" }, "account": { "number": "541333****0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 18289000007021, "type": "cancel", "status": "success", "date": "2020-01-11T15:54:40+0000", "created_date": "2020-01-11T15:54:40+0000", "request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c", "sum_initial": { "amount": 200000, "currency": "USD" }, "sum_converted": { "amount": 200000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "239672146", "auth_code": "", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` В следующем примере отмена блокировки средств была отклонена из-за ввода некорректных данных карты. ```language-json { "account": { "number": "541333****0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2020-01-11T15:54:40+0000", "id": "456789", "method": "card", "status": "decline", "sum": { "amount": 10000, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 18397000002376, "type": "cancel", "status": "decline", "date": "2020-01-11T15:54:40+0000", "created_date": "2020-01-11T15:54:35+0000", "request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "248013808", "date": "2020-01-10T22:37:10+0000", "auth_code": "876856", "endpoint_id": 120 }, "code": "10102", "message": "Incorrect data entered" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm..." } ``` **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Регистрация повторяемых оплат {#ru_pp_recurring} статья о порядке регистрации через Payment Page оплат с сериями повторяемых списаний **Прим.:** Эта статья посвящена тому, как регистрировать повторяемые оплаты через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с повторяемыми оплатами могут быть полезны: - статьи [Повторяемая оплата со списаниями по запросам](ru_platform_recurring_model.md) и [Повторяемая оплата с автоматическими списаниями](ru_platform_sheduled_recurring_model.md) модели проведения платежей с описанием того, как в целом проводятся повторяемые оплаты в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как регистрировать повторяемые оплаты через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. ## Общая информация {#section_ibx_bdh_zlb .section} Платёжная платформа Ecommpay позволяет регистрировать повторяемые оплаты разными способами, в том числе при проведении платежей через интерфейсы Payment Page, Gate \([подробнее](ru_gate_payment_recurring_registration.html)\) и Dashboard \([подробнее](ru_dbl_payments.md)\), а также при переносе информации о повторяемых оплатах от стороннего эквайера \([подробнее](ru_gate_data_migration.md)\). В этом разделе представлена информация о регистрации повторяемых оплат с использованием Payment Page в рамках проведения оплат и проверки действительности платёжного инструмента. *Повторяемая оплата* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется повторяемый перевод денежных средств от пользователя к мерчанту. При этом для проведения платежа используются сохранённые платёжные данные, а подтверждение подлинности платёжного инструмента пользователя \(такое, как ввод кода проверки подлинности карты\) не требуется. Использование повторяемой оплаты может быть актуальным при выстраивании долгосрочных отношений с пользователями, когда важно предоставлять им возможность удобной оплаты без дополнительных действий с их стороны. **Прим.:** В случае открытия платёжной формы для регистрации повторяемой оплаты пользователю отображаются только те платёжные методы, для которых поддерживается такая регистрация \([подробнее](ru_pm_about.md)\). Базовыми действиями пользователя при регистрации повторяемых оплат с использованием Payment Page могут быть выбор платёжного инструмента, указание его реквизитов и ожидание уведомления о результате платежа. ![](images/ecommpay/ru_pp_recurring.svg) В платёжной платформе поддерживаются следующие категории повторяемых оплат: - *Экспресс-оплаты*. Списания в рамках таких оплат инициируются пользователем и выполняются без привязки к расписанию или сумме платежа. Например, пользователь онлайн-кинотеатра может оплатить прокат одного или нескольких фильмов с использованием сохранённых данных карты. - *Автооплаты*. Списания в рамках таких оплат инициируются мерчантом и выполняются нерегулярно или на различные суммы. Например, когда остаток средств на счёте пользователя становится ниже заданного, выполняется списание средств с его платёжной карты для пополнения этого счёта. - *Регулярные оплаты*. Списания в рамках таких оплат инициируются мерчантом по заданному графику и на фиксированную сумму. График таких списаний может храниться как на стороне веб-сервиса, так и на стороне платёжной платформы. Например, с пользователя онлайн-кинотеатра может ежемесячно списываться фиксированная сумма для оплаты доступа к просмотру всех фильмов кинотеатра. Для регистрации любой повторяемой оплаты, вне зависимости от категории, необходимо получить согласие пользователя на хранение его платёжных данных и их дальнейшее использование на определённых условиях. Для регистрации повторяемых оплат используются режимы работы платёжной формы Purchase или Card Verify. Для инициирования проведения повторяемой оплаты, изменения условий её проведения или её отмены, а также для выполнения возврата средств пользователю можно использовать [Gate](ru_Gate__payments_on_saved_data.md) \(для всех типов повторяемых оплат\) и [Dashboard](ru_dbl_payments.md) \(для регулярных оплат\). При изменениях в настройках системы провайдера может требоваться новая регистрация повторяемых оплат. В таких случаях от службы технической поддержки Ecommpay мерчанту направляется письмо со списком идентификаторов повторяемых оплат, по которым следует выполнить регистрацию заново. Для этой регистрации необходимо уведомить пользователей о прекращении прежних списаний и необходимости инициирования новых, предварительно отвязав сохранённую карту, после чего инициировать регистрацию в платформе. Каждая вновь зарегистрированная повторяемая оплата получает новый идентификатор, который отправляется мерчанту в оповещении об успешной регистрации. ## Схема работы {#section_erl_5qh_zlb .section} Для регистрации повторяемых оплат с помощью Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page. 2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы. При регистрации повторяемых оплат может потребоваться выполнение вспомогательных процедур: - *Аутентификация 3‑D Secure*, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\). - *Аутентификация по инициативе мерчанта*, при выполнении которой пользователю отображается дополнительная страница, на которой необходимо ввести проверочный код, полученный в SMS-сообщении или банковской выписке, при этом для аутентификации выполняется временная блокировка согласованной небольшой суммы. Такая аутентификация может использоваться в качестве замены аутентификации 3‑D Secure или для её дополнения. - *Дополнение информации о платеже*, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме. Такие процедуры выполняются без участия веб-сервиса мерчанта, но, как правило, требуют участия пользователя. Информация о форматах запросов и оповещений для регистрации повторяемых оплат с прямым использованием платёжных карт представлена далее, а о форматах запросов и оповещений с использованием других платёжных методов представлена в разделе [Методы](ru_pm_about.md). ## Формат запросов {#section_fjz_4yy_1mb .section} Формат запроса на открытие Payment Page для регистрации повторяемой оплаты соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `customer_id` — идентификатор пользователя уникальный в рамках проекта; - `payment_amount` — сумма платежа в дробных единицах валюты; для регистрация повторяемой оплаты в рамках проверки действительности платёжного инструмента необходимо передавать значение `0`; - `payment_currency` — код валюты платежа в формате ISO 4217 alpha-3; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для регистрации повторяемой оплаты при проверке действительности платёжного инструмента необходимо дополнительно использовать параметр `mode` — индикатор режима работы Payment Page, для которого необходимо передавать значение `card_verify`. 3. Для указания свойств повторяемой оплаты необходимо передавать параметр `recurring` — в виде объекта JSON, если для вызова платёжной формы используется JavaScript-библиотека Ecommpay, или в виде строки, полученной в результате кодирования URL-encoding, если платёжная форма вызывается иным способом. Параметр `recurring` должен содержать основные сведения о регистрации повторяемой оплаты: - `register`, boolean — указатель необходимости зарегистрировать повторяемую оплату; - `type`, string — категория регистрируемой повторяемой оплаты, с одним из следующих значений: - `C` — для экспресс-оплаты; - `U` — для автооплаты; - `R` — для регулярной оплаты; - `period`, string — указатель базового периода списаний \(для регулярной оплаты\), с одним из следующих значений: - `D` — ежедневно; - `W` — еженедельно; - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\); - `Q` — ежеквартально; - `Y` — ежегодно; - `interval`, integer — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`; - `time`, string — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`. 4. Для указания свойств регулярной оплаты в параметре `recurring` также могут использоваться и другие сведения: - `amount`, integer — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты; - `start_date`, string — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`; - `expiry_day`, integer илиstring — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\); - `expiry_month`, integer илиstring — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\); - `expiry_year`, integer — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\); **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. - `scheduled_payment_id`, string — идентификатор платежа, в рамках которого следует выполнять списания, должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта \(также не стоит путать его с идентификатором серии списаний, передаваемым в параметре `id` объекта `recurring` оповещения о регистрации повторяемой оплаты\). **Внимание:** Если идентификаторы платежа, который необходимо присвоить повторяемой оплате \(`scheduled_payment_id`\), и платежа, в рамках которого эта оплата регистрируется \(`payment_id`\), совпадают, запрос на регистрацию отклоняется. 5. Для указания обязательных сведений о пользователе в случае, если не используется возможность указания таких сведений самим пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\), в запросе дополнительно необходимо использовать по крайней мере один из следующих параметров: `customer_email` и `customer_phone`. 6. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\). 7. Для добавления описания платежа можно использовать параметр `payment_description`, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа. 8. Дополнительно могут использоваться любые другие параметры, применимые в режимах работы Purchase и Card Verify платёжной формы Payment Page. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, запрос на регистрацию повторяемых оплат должен содержать: - при проведении проверки действительности платёжного инструмента — параметры запроса на открытие Payment Page для проверки действительности платёжного инструмента и параметр `recurring` с данными о регистрации повторяемых оплат; - при проведении оплаты — параметры запроса на открытие Payment Page для проведения оплаты и параметр `recurring` с данными о регистрации повторяемых оплат. ```language-json { "register": true, //регистрация повторяемой оплаты "type": "R", //регистрация регулярной оплаты "amount": 400, "expiry_day": 1, "expiry_month": 8, "expiry_year": 2025, //последнее списание 1-го августа 2025 года "interval": 10, "period": "D", //списания каждые 10 дней "time": "10:00:00", //выполнение списаний в 10:00:00 "start_date": "14-05-2019", "scheduled_payment_id": "A2323" } ``` ``` "recurring": "%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22 expiry_day%22%3A1%2C%22expiry_month%22%3A8%2C%22expiry_year% 22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C% 22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019% 22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D" ``` ``` EPayWidget.run( { payment_id: '567890', payment_amount: '400', customer_id: 'customer1', payment_currency: 'USD', project_id: 42, force_payment_method: 'card', recurring: '{"register":true,"type":"R","amount":400,"expiry_day":1,"expiry_month":8,"expiry_year":2025,"interval": 10,"period":"D","time": "10:00:00","start_date":"14-05-2019","scheduled_payment_id":"A2323"}', signature: 'qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...' }, 'post') ``` ```language-json https://paymentpage.ecommpay.com/payment?signature=qlgcPujhcUcul5ZpMyR0%2BEtDUmSFJeLUCI1...&payment_id=567890&payment_amount=400&payment_currency=USD&project_id=42&customer_id=customer_1®ion_code=GB&language_code=en&force_payment_method=card&recurring=%7B%22register%22%3Atrue%2C%22type%22%3A%22R%22%2C%22amount%22%3A400%2C%22expiry\_day%22%3A1%2C%22expiry\_month%22%3A8%2C%22expiry_year%22%3A2025%2C%22interval%22%3A10%2C%22period%22%3A%22D%22%2C%22time%22%3A%2210%3A00%3A00%22%2C%22start_date%22%3A%2214-05-2019%22%2C%22scheduled_payment_id%22%3A%22A2323%22%7D ``` ## Формат оповещений {#section_mbv_cmk_1mb .section} Формат оповещения о выполнении оплаты или проверке действительности с регистрацией повторяемой оплаты соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_1` зарегистрировано проведение повторяемых оплат с использованием платёжной карты `431422******0056`. ```language-json { "project_id": 42, "payment":{ "id": "567890", "type": "purchase", "status": "success", "date": "2019-05-14T12:52:45+0000", "method": "card", "sum":{ "amount": 400, "currency": "USD" }, "description": "" }, "account":{ "number": "431422******0056", "token": "d927d3f006008edf5c07661", "type": "visa", "card_holder": "JUDY DOE", "expiry_month": "08", "expiry_year": "2025" }, "customer":{ "id": "customer_1" }, "recurring":{ "id": 1001648059, // Идентификатор записи о серии списаний "currency": "USD", "valid_thru": "2019-05-20T00:00:00+0000" }, "scheme\_id":"MCS38A0790706", "operation":{ "id": 22136002040, "type": "sale", "status": "success", "date": "2019-05-14T12:52:45+0000", "created_date": "2019-05-14T12:52:42+0000", "request_id": "8c77279053d011-1160421d51e11f87d2c", "sum_initial":{ "amount": 400, "currency": "USD" }, "sum_converted":{ "amount": 400, "currency": "USD" }, "provider":{ "id": 414, "payment_id": "00200011764", "date": "2019-05-14T12:52:55+0000", "auth_code": "231567", "endpoint_id": 414 }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm..." } ``` **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Проведение выплат {#ru_pp_payout} статья о порядке проведения через Payment Page выплат ## Общая информация {#section_nrq_x34_1bc .section} В платёжной платформе Ecommpay поддерживается возможность проводить выплаты на счета, ассоциированные с платёжными картами, с использованием платёжной формы Payment Page: с предварительной регистрацией каждой такой выплаты через Gate API и с последующим вызовом платёжной формы в режиме работы Payout.При этом отправителями выплат могут выступать как сам мерчант, так и физические лица, а при проведении выплат могут использоваться сервисы Mastercard MoneySend и Visa Direct. **Прим.:** Возможность проведения выплат поддерживается только в платёжной форме Payment Page 5-го поколения. Для регистрации выплаты необходимо отправить соответствующий запрос к платформе через Gate API и принять оповещение о результате этой регистрации.Если выплата зарегистрирована, в оповещении передаётся специальный идентификатор \(`uuid`\), который необходимо указать при вызове Payment Page. При этом важно учитывать, что срок действия идентификатора составляет 30 минут и при открытии платёжной формы на её страницах отображается таймер с остающимся временем до подтверждения выплаты пользователем.В случае, если пользователь не подтвердил выплату в заданное время, ему отображается соответствующее уведомление, и для проведения выплаты со стороны веб-сервиса требуется зарегистрировать её повторно, с указанием нового идентификатора платежа \(`payment_id`\). Выплаты с использованием Payment Page выполняются с их подтверждением пользователями с помощью проверочных кодов. Такие коды отправляются от платёжной платформы на адрес электронной почты пользователя, указанный при регистрации выплаты. ![](images/ecommpay/ru_pp_payout_code.svg "Пример письма с проверочным кодом") Со стороны пользователя для проведения выплаты с использованием Payment Page следует выбрать платёжный инструмент, указать его реквизиты, затем указать проверочный код и получить уведомление о результате. При этом платёжные данные могут быть указаны одним из следующих способов: - *Через ввод на странице формы.*В этом случае пользователь обязательно заполняет на страницах формы все требуемые поля. - *Через выбор или ввод на странице формы.* В этом варианте пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем. - *Через выбор до вызова формы.*В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты и платёжная форма открывается с указанием необходимых реквизитов. По результатам проведения выплат могут формироваться токены платёжных карт— в случаях, когда данные этих карт не были сохранены ранее и такая возможность подключена для используемого проекта мерчанта \([подробнее](ru_pp_token.md)\). ## Пользовательский сценарий {#section_tgk_kx4_1bc .section} Допустим, пользователь Prostetnik Jeltz занял третье место в конкурсе Millstone Jennings Poetry с призом, равным 70 EUR.Чтобы получить выплату, пользователь указывает данные платёжного инструмента и свои имя и фамилию, после чего подтверждает выплату и ожидает результата её проведения. ![](images/ecommpay/ru_pp_payout_1.svg "Указание платёжных данных") ![](images/ecommpay/ru_pp_payout_2.svg "Указание проверочного кода") ## Ограничения {#section_dkx_x34_1bc .section} Проведение выплат с использованием Payment Page возможно с учётом следующих ограничений: - Возможность проведения выплат должна быть подключена для используемого проекта. В случае отправки запроса на регистрацию выплаты в рамках проекта, для которого не подключена такая возможность, от платёжной платформы к веб-сервису направляется оповещение с кодом ошибки `317` \([подробнее](ru_platform_payment_info_codes.md)\). - Для отправки запросов на регистрацию выплат должны использоваться IP-адреса, предоставленные специалистам технической поддержки Ecommpay и добавленные ими в список разрешённых. В случае отправки запроса с IP-адреса, не добавленного в список разрешённых, от платёжной платформы к веб-сервису направляется ответ с кодом ошибки `403` \([подробнее](ru_gate_interaction_organisation.md)\). - Должны соблюдаться установленные ограничения для платёжной карты получателя выплаты, в том числе на количество зачислений, их общую сумму и сумму однократного зачисления. В случае превышения одного из таких ограничений выплата отклоняется, пользователю отображается страница платёжной формы с информацией об отклонении платежа и к веб-сервису направляется оповещение с соответствующим кодом ошибки. - Остаток средств на счёте мерчанта должен быть достаточным для проведения выплаты. Если средств недостаточно, выплата отклоняется, пользователю отображается страница платёжной формы с информацией об отклонении платежа и к веб-сервису направляется оповещение с соответствующим кодом ошибки. Информацию об остатке средств можно получать через Dashboard \([подробнее](ru_dbl_balances.md)\) и Data API \([подробнее](ru_dbl_api_protocol.md)\), при этом с вопросами можно обращаться к курирующему менеджеру Ecommpay. - Должны соблюдаться требования платёжных систем и программ, в рамках которых проводится выплата, а также специфические требования и условия, характерные для отдельных регионов, платёжных систем и провайдеров. Так, для разных программ может требоваться указывать различные сведения об отправителе или получателе выплаты в запросах на открытие платёжной формы. **Прим.:** Такие требования могут касаться, в частности, следующих случаев: - для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, должны указываться имя и фамилия получателя, а также имя и фамилия, основной идентификатор используемого платёжного инструмента и информация о местонахождении отправителя — если эти сведения не указаны в запросе на открытие платёжной формы, выплата отклоняется; - для выплат в рамках программы Money Transfer платёжной системы Visa должна указываться информация о местонахождении получателя, если карта получателя выпущена в Канаде — если эти сведения не указаны в запросе на открытие платёжной формы, пользователю отображается дополнительная страница с полями для их указания. С вопросами о специфике проведения выплат в различных регионах и с учётом различных факторов можно обращаться к курирующему менеджеру Ecommpay. - При вызове платёжной формы не должна использоваться возможность ограничения времени работы с ней \([подробнее](ru_pp_time_limit.md)\); время работы с платёжной формой при проведении выплат ограничено по умолчанию и соответствует времени, остающемуся до окончания срока действия идентификатора `uuid`. Если в запросе на открытие платёжной формы указаны дата и время завершения работы с ней, пользователю отображается страница платёжной формы с информацией об ошибке. ## Подключение {#section_txr_bgp_1bc .section} Чтобы подключить возможность проведения выплат с использованием Payment Page, со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpay подключение этой возможности, необходимость её тестирования и применение ограничений в каждом конкретном случае. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить работу платёжной формыс использованием этой возможности и сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении возможности. ## Схема работы {#section_gyn_lx4_1bc .section} Для проведения выплаты с использованием Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на регистрацию выплаты. 2. Принять от платформы оповещение о регистрации выплаты. 3. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page в режиме Payout. 4. Принять от платформы оповещение о результате платежа. При проведении выплат может выполняться *дополнение информации о платеже*, в рамках которого пользователю отображаются дополнительные поля, которые требуется заполнить здесь же, в платёжной форме. Эта процедура выполняется без участия веб-сервиса мерчанта, но требует участия пользователя. ![UML-scheme](images/ecommpay/ru_payout_pp_uml.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на регистрацию выплаты. 3. Запрос на регистрацию выплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запросас проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности\([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняется обработка запроса. 7. От платёжной платформы к веб-сервису направляется оповещение с указанием идентификатора выплаты. 8. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты с использованием Payment Page. 9. Запрос на проведение выплаты поступает в платёжную платформу. 10. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 11. Осуществляется подготовка Payment Pageсогласно параметрам проекта и вызова. 12. Пользователю отображается платёжная формас индикатором остающегося времени работы с ней. 13. Пользователь выполняет необходимые действия и подтверждает выплату. 14. В платёжную платформу передаётся запрос на проведение выплаты. 15. В платёжной платформе выполняются обработка полученного запроса и его отправка в платёжную среду. 16. В платёжной среде выполняется обработка платежа. 17. От платёжной среды к платформе направляется информация о результате выплаты. 18. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 19. От платёжной платформы к Payment Page направляется информация о результате выплаты. 20. Информация о результате выплаты отображается пользователю на Payment Page. ## Формат запроса на регистрацию выплаты {#section_hww_lx4_1bc .section} При работе с запросами на регистрацию выплат необходимо учитывать следующее: 1. Для регистрации каждый выплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/payout/registration](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-payout-registration). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `email` — адрес электронной почты пользователя; - `phone` — номер телефона пользователя; - `ip_address` — IP-адрес пользователя, актуальный для регистрируемой выплаты. Таким образом, корректный запрос на регистрацию выплаты должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, контактные данные пользователя \(адрес электронной почты и номер телефона\), а также подпись. ```language-json "general": { "project_id": 91348, "payment_id": "cosmoshop_payout_1323", "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA==" }, "customer": { "id": "16061314", "email": "p.jeltz@mail.com", "phone": "44991234567", "ip_address": "93.47.230.225" }, "payment": { "amount": 7000, "currency": "EUR" } } ``` ## Формат оповещения о результате регистрации выплаты {#section_ayp_gtp_1bc .section} При проведении каждой выплаты с использованием Payment Page необходимо принять промежуточное оповещение от платёжной платформы о результате регистрации выплаты и использовать идентификатор, передаваемый в параметре `uuid`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\). В следующем примере содержится информация о том, что в рамках проекта `91348` для пользователя `16061314` была зарегистрирована выплата. ```language-json { "general": { "project_id": "91348", "payment_id": "cosmoshop_payout_1323", "signature": "V2mxcUcGUcCtAE51lgesBefZgfG9NHpQEbfdI2X1Q==" }, "request_id": "50715", "payment": { "id": "cosmoshop_payout_1323", "type": "payout", "status": "awaiting_payout_completion", }, "operation": { "id": "500359719", "type": "payout", "status": "awaiting_payout_completion" }, "customer": { "id": "16061314" }, "sum_request": { "amount": "7000", "currency": "EUR" }, "transaction": { "type": "payout" }, "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==", "uuid_expired_at": "2024-04-24T13:50:37+0000" } ``` ## Формат запроса на открытие платёжной формы {#section_cmq_3fp_1bc .section} Формат запроса на открытие Payment Page для проведения выплаты с использованием платёжной карты соответствует описанному в статье [Организация взаимодействия](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. В запросе должны использоваться следующие обязательные параметры: - `mode` — индикатор режима работы Payment Page, для которого следует указывать значение `payout`; - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта; **Внимание:** Идентификаторы платежа \(`payment_id`\) в запросах на регистрацию выплаты и на открытие платёжной формы должны совпадать; в случае, если идентификаторы не совпадают, платёжная форма не открывается и пользователю отображается сообщение об ошибке. - `uuid` — идентификатор выплаты, полученный в оповещении о результате регистрации; - `customer_id` — идентификатор пользователя, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта; - `customer_email` — адрес электронной почты пользователя, соответствующий указанному в запросе на регистрацию выплаты; - `payment_amount` — сумма платежа, соответствующая указанной в запросе на регистрацию выплаты, в дробных единицах валюты; - `payment_currency` — код валюты платежа, соответствующий указанному в запросе на регистрацию выплаты, в формате ISO 4217 alpha-3; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для использования токена платёжной карты, предварительно выбранной пользователем в веб-сервисе, этот токен должен указываться в параметре `account_token`. 3. Для указания сведений об отправителе выплаты могут использоваться следующие параметры: - `sender_wallet_id` — номер \(идентификатор\) кошелька отправителя. - `sender_first_name` — имя отправителя. - `sender_last_name` — фамилия отправителя. - `sender_country` — код страны местонахождения отправителя в формате ISO 3166-1 alpha-2. - `sender_state` — внутренний код территории местонахождения отправителя\(штата, провинции, региона или иной территориальной области\). Этот код представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. Например, `ON` для провинции Онтарио в Канаде \(с международным кодом `CA-ON`\). - `sender_city` — название города местонахождения отправителя. - `sender_address` — название улицы и номер дома местонахождения отправителя. - `sender_zip` — почтовый индекс местонахождения отправителя. 4. Для указания сведений о получателе выплаты могут использоваться следующие параметры: - `recipient_first_name` — имя получателя. - `recipient_last_name` — фамилия получателя. - `recipient_country` — код страны местонахождения получателя в формате ISO 3166-1 alpha-2. - `recipient_state` — внутренний код территории местонахождения получателя\(штата, провинции, региона или иной территориальной области\). Этот код представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. Например, `ON` для провинции Онтарио в Канаде \(с международным кодом `CA-ON`\). - `recipient_city` — название города местонахождения получателя. - `recipient_address` — название улицы и номер дома местонахождения получателя. В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, из них обязательны к указанию сведения о местоположении получателя: код страны \(`recipient_country`\), название города \(`recipient_city`\), название улицы и номер дома \(`recipient_address`\) и, если код страны получателя соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), код штата, провинции или территории \(`recipient_state`\). 5. Для отображения пользователю платёжной формы на заданном языке код этого языка в формате ISO 639-1 alpha-2 должен указываться в параметре `language_code`. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию;[подробнее](ru_PP_WigetLanguages.md)\). 6. Для добавления описания платежа, отображаемого пользователю на странице с информацией о результате выплаты и доступного специалистам мерчанта через оповещения и интерфейс Dashboard, в запросе следует использовать параметр `payment_description`. 7. Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Payout. Полный список параметров вызова Payment Page представлен в статье [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, корректный запрос на проведение выплаты должен содержать идентификаторы проекта, пользователя и платежа, идентификатор из оповещения о регистрации выплаты, адрес электронной почты пользователя, подпись, код валюты и сумму платежа. Вместе с тем, в запросах могут использоваться и другие параметры. ```language-json { "project_id": "91348", "payment_id": "cosmoshop_payout_1323", "payment_currency": "EUR", "payment_amount": "7000", "customer_id": "16061314", "customer_email": "p.jeltz@mail.com", "mode": "payout", "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5...", "signature": "xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB..." // при проведении выплаты по предварительно выбранной карте: "account_token":"959c664ad6045679d71d89caff6c242a0..." } ``` ## Формат оповещения о результате выплаты {#section_bh5_mx4_1bc .section} Формат оповещения о результатах проведения выплат с использованием платёжных карт соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Проверка платёжных инструментов {#ru_pp_account_verification} статья о порядке проверки через Payment Page действительности платёжных инструментов с условными списаниями или временными блокировками средств **Прим.:** Эта статья посвящена тому, как проверять действительность платёжных инструментов через Payment Page и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с проверкой действительности могут быть полезны: - статья [Проверка действительности платёжного инструмента](ru_platform_account_verification_model.md) модели проведения платежей с описанием того, как в целом проверяется действительность платёжных инструментов через платёжную платформу Ecommpay и какие статусы при этом могут использоваться; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проверять действительность платёжных инструментов через Payment Page при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. Информацию о возможности проверки действительности для используемых проектов и методов можно уточнять у курирующего менеджера Ecommpay. ## Общая информация {#section_rsp_vys_mlb .section} *Проверка действительности платёжного инструмента* — это тип платежа, в рамках которого для проверки возможности использования платёжного инструмента на основании одного исходного запроса осуществляется один условный \(нулевой\) перевод денежных средств от пользователя к мерчанту или одна реальная \(ненулевая\) блокировка средств пользователя с последующей отменой. При этом сумма блокировки может согласовываться с мерчантом, а срок отмены блокировки может составлять до 45 дней. Это может быть актуальным, когда необходимо подтвердить подлинность конкретного платёжного инструмента без немедленного списания средств, например перед проведением выплаты илидля регистрации в сервисе с бесплатным пробным периодом и последующими списаниями \(подробнее о работе с такими случаями — в статье [Регистрация повторяемых оплат](ru_pp_recurring.md)\). В Payment Page для проверки действительности платёжных инструментов используется отдельный режим Card Verify,при работе с которым доступны возможности указания реквизитов, получаемых от пользователей через средства связи \(Mail Order / Telephone Order; MO/TO\), а также возможности сохранения предоставленных реквизитов в платформе. Базовыми действиями пользователя при выполнении проверки действительности платёжного инструмента с использованием Payment Page могут быть указание реквизитов платёжного инструмента, сохранение реквизитов для выполнения последующих платежей и ожидание уведомления о результате. ![](images/ecommpay/ru_pp_account_verification.svg) ## Схема работы {#section_erl_xys_mlb .section} Для проверки действительности платёжного инструмента через Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page. 2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы. При проверке действительности платёжного инструмента могут выполняться вспомогательные процедуры: - *Аутентификация 3‑D Secure*, при выполнении которой происходит перенаправление пользователя к сервису эмитента, где необходимо подтвердить свою подлинность кодом из SMS-сообщения или иным способом, либо отображается страница ожидания \(в то время, пока эмитент подтверждает подлинность без участия пользователя\). - *Дополнение информации о платеже*, при выполнении которой пользователю отображаются соответствующее уведомление и дополнительные поля, которые требуется заполнить здесь же, на платёжной форме. Эти процедуры выполняются без участия веб-сервиса мерчанта, но, как правило, требуют участия пользователя. Информация о форматах запросов и оповещений для выполнения проверки действительности платёжных карт представлена далее. ## Формат запросов {#section_zk4_zb2_plb .section} Формат запроса на открытие Payment Page для проверки действительности платёжного инструмента соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. Должны использоваться следующие обязательные параметры: - `mode` — индикатор режима работы Payment Page, для которого необходимо передавать значение `card_verify`; - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_amount` — сумма платежа в дробных единицах валюты, необходимо передавать значение `0`; - `payment_currency` — код валюты платежа в формате ISO 4217 alpha-3; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для регистрации повторяемой оплаты дополнительно необходимо использовать параметр `recurring` со сведениями об этой повторяемой оплате \(подробнее — в статье [Регистрация повторяемых оплат](ru_pp_recurring.md)\). 3. Для сохранения данных платёжного инструмента дополнительно необходимо использовать параметр `customer_id` — идентификатор пользователя, уникальный в рамках проекта. 4. Для проведения проверки по токену инструмента необходимо использовать параметр `account_token` — токен, полученный от Ecommpay. 5. Для отображения пользователю платёжной формы на заданном языке дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\). 6. Для добавления описания платежа дополнительно необходимо использовать параметр `payment_description`, представляющий собой строку, которая отображается пользователю на странице с информацией о результате выполнения операции и мерчанту в интерфейсе Dashboard, а также передаётся мерчанту в составе оповещения о результате платежа. 7. Для указания реквизитов, получаемых от пользователей через средства связи, дополнительно должен указываться параметр `moto_type` — со значением `1` при использовании почтовой связи \(Mail Order\) и `2` при использовании телефонной связи \(Telephone Order\). 8. Дополнительно могут использоваться любые другие параметры, доступные при работе в режиме Card Verify. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, корректный запрос на открытие Payment Page для проверки действительности платёжного инструмента должен содержать индикатор режима работы Payment Page, идентификаторы проекта и платежа, подпись, валюту и сумму платежа. Для сохранения данных платёжного инструмента в запросе дополнительно необходимо передать идентификатор пользователя в веб-сервисе мерчанта, а для регистрации повторяемых оплат — строку с соответствующим набором параметров. ```language-json { "mode": "card_verify", "project_id": 874, "payment_id": "15538406111", "payment_currency": "EUR", "payment_amount": 0, "signature": "TSzdE5rJpfXriFf82MxF...", // при сохранении данных платёжного инструмента: "customer_id": "customer_10", // при проведении проверки по токену карты: "account_token": "42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021", // при регистрации повторяемых оплат: "recurring": { "register": "true", "type": "R", ... } } ``` ```language-json https://paymentpage.ecommpay.com/payment?payment_currency=EUR&language_code=en&mode=card_verify&project_id=874&payment_amount=0&payment_id=15538406111&css_modal_wrap=standart&signature=Z0QkrvLe%2Fl6Vdyxb4%2F0zwcPT8E... ``` ## Формат оповещений {#section_x3c_5zd_plb .section} Формат оповещения о результате проверки действительности платёжного инструмента соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что платёжная карта `431422******0056` пользователя `customer_10` действительна — может использоваться при проведении платежей — и зарегистрирована для проведения повторяемых оплат. ```language-json { "project_id": 874, "payment":{ "id": "15538406111", "type": "account_verification", "status": "success", "date": "2020-06-10T13:45:59+0000", "method": "card", "sum":{ "amount": 0, "currency": "EUR" }, "description": "Добавить карту" }, "account":{ "number": "431422******0056", "token": "844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f", "type": "visa", "card_holder": "JOHN SMITH", "id": 8861226, "expiry_month": "09", "expiry_year": "2021" }, "customer":{ "id": "customer_10" }, "recurring":{ "register": "true", "type": "R" }, "operation":{ "id": 42209000002431, "type": "account verification", "status": "success", "date": "2020-06-10T13:45:59+0000", "created_date": "2020-06-10T13:45:57+0000", "request_id": "5cb898347e62b2c1-52dac6c8c", "sum_initial":{ "amount": 0, "currency": "EUR" }, "sum_converted":{ "amount": 0, "currency": "EUR" }, "provider":{ "id": 120, "payment_id": "306449667", "date": "2020-06-10T13:45:59+0000", "auth_code": "188591", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "P9g0U+eF2QWs2A..." } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении проверки действительности. Проведение платежа отклонено платёжной системой без указания причины. ```language-json { "project_id": 874, "payment":{ "id": "15538406111", "type": "account_verification", "status": "decline", "date": "2020-06-16T06:06:53+0000", "method": "card", "sum":{ "amount": 0, "currency": "EUR" }, "description": "Добавить карту" }, "account":{ "number": "431422******0056", "type": "visa", "card_holder": "JOHN SMITH", "expiry_month": "09", "expiry_year": "2021" }, "customer":{ "id": "customer_10" }, "operation":{ "id": 40975000002863, "type": "account verification", "status": "decline", "date": "2020-06-16T06:06:53+0000", "created_date": "2020-06-16T06:06:47+0000", "request_id": "9120271eb02-83e0e70fc0a0a3c1b4d", "sum_initial":{ "amount": 0, "currency": "EUR" }, "sum_converted":{ "amount": 0, "currency": "EUR" }, "provider":{ "id": 120, "payment_id": "308822001", "date": "2020-06-16T06:06:49+0000", "auth_code": "", "endpoint_id": 120 }, "code": "10100", "message": "Declined by external provider" }, "signature": "P9g0U+eaZ9EeNiWiaQWs2A..." } ``` **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Формирование токенов {#ru_pp_token} статья о порядке вызова платёжной формы для регистрации платёжных данных и формирования их токенов ## Общая информация {#section_vpr_b1h_nlb .section} При работе с Payment Page можно формировать токены, которые в дальнейшем хранятся на стороне веб-сервиса мерчанта и могут использоваться при проведении оплат через Payment Pageи [Gate](ru_Gate_Token.md#section_tz1_wrs_5bb), а также выплат через [Gate](ru_Gate_payout.md). *Токен* — это идентификатор, представляющий собой случайную последовательность из 64 символов и ассоциированный в рамках платёжной платформы с определённой платёжной картой. Формирование токенов выполняется на основании данных платёжных карт пользователей \(таких как номер карты, имя и фамилия её держателя и дата окончания срока действия этой карты\) и возможно в следующих случаях: - при выполнении запроса на открытие Payment Page в режиме Card Tokenize; - при проведении первой успешной оплаты с сохранением платёжных данных карты в режиме Purchase, если такая настройка доступна для проекта мерчанта; - при проведении первой успешной оплатыили выплаты с использованием платёжной карты, если такая настройка доступна для проекта мерчанта. По вопросам добавления возможности автоматической генерации токенов следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com). В каждом из этих случаев для отдельной платёжной карты формируется один токен со сроком действия, соответствующим сроку действия этой карты, и этому токену присваивается статус `active`. При истечении срока действия токена этот статус изменяется на статус `expiry`, а при удалении токена по запросу со стороны веб-сервиса — на статус `revoke`. И в обоих случаях проведение платежей по этому токену становится недоступным. Процедуры удаления токена, а также получения реквизитов платёжной карты по токену выполняются через интерфейс Gateи представлены в разделе [Использование токенов](ru_Gate_Token.md). Базовыми действиями пользователя при формировании токенов с использованием Payment Page могут быть указание реквизитов платёжной карты и ожидание уведомления о результате. После успешного формирования токена данные платёжной карты, с которой он ассоциирован, отображаются пользователю на странице выбора способа оплаты в общем списке сохранённых инструментов. ![](images/ecommpay/ru_pp_token.svg) В этом разделе представлена информация о формировании токенов с использованием Payment Page в режиме Card Tokenize. Информация о формировании токенов при проведении оплаты представлена в разделе [Проведение оплат](ru_pp_purchase.md). ## Схема работы {#section_uh2_dgh_nlb .section} Для формирования токена через Payment Page со стороны веб-сервиса необходимо: 1. Сформировать и отправить в платёжную платформу запрос на открытие Payment Page. 2. Принять оповещение о результате выполнения запроса со стороны платёжной платформы. ## Формат запросов {#section_rgv_yr2_plb .section} Формат запроса на открытие Payment Page для формирования токена соответствует описанному в разделе [Формат запроса](ru_pp_interaction_organisation.md). При формировании такого запроса необходимо учитывать следующее: 1. В запросе должны использоваться следующие обязательные параметры: - `mode` — индикатор режима работы Payment Page, для которого необходимо передавать значение `card_tokenize`. - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `customer_id` — идентификатор пользователя в веб-сервисе мерчанта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). 2. Для отображения пользователю платёжной страницы на заданном языке в запросе дополнительно необходимо использовать параметр `language_code` — код языка в формате ISO 639-1 alpha-2. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию; [подробнее](ru_PP_WigetLanguages.md)\). 3. Дополнительно в запросах могут использоваться любые другие параметры, используемые для работы Payment Page в режиме Card Tokenize. Полный список параметров вызова Payment Page представлен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). Таким образом, корректный запрос на формирование токена должен содержать индикатор режима работы Payment Page, идентификатор проекта, подпись, а таже идентификатор пользователя. ```language-json { "mode": "card_tokenize", "project_id": 112, "customer_id": "cust_123", "signature": "TSzdE5rJZaA9VyJtnfRI362oGpfXriFf82MxF..." } ``` ```language-json https://paymentpage.ecommpay.com/payment?signature=A%2Fqqxsl59tRrtACreixy8sieSfxR%2BC...&mode=card_tokenize&project_id=112&customer_id=cust_123®ion_code=GB&language_code=en ``` ## Формат оповещений {#section_x3c_5zd_plb .section} Для оповещения о формировании токена используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `112` для пользователя `cust_123` сформирован токен \(`token`\). Также для этого токена указаны дата и время его создания \(`token_created_at`\) и текущий статус \(`token_status`\). ```language-json { "general": { "project_id": 112, "customer_id": "cust_123", "signature": "mTHcy5wvpOYkl9S5eLJZ..." }, "request": { "id": "3c7f53fdbb5b8c96f9707457d75f", "action": "tokenize", "status": "success" }, "token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1", "token_created_at":"2020-03-28 13:30:57", "token_status":"active" } ``` **На уровень выше:**[Основные действия](ru_pp_basic_actions.md) --- # Вспомогательные процедуры и дополнительные возможности {#ru_PP_Additional .concept} статьи о вспомогательных процедурах и дополнительных возможностях Payment Page, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг В этом подразделе представлены материалы *о различных процедурах*, которые могут автоматически выполняться при работе с Payment Page для проведения отдельных платежей и влиять на пользовательские сценарии работы, а также *о различных возможностях*, которые могут применяться по инициативе мерчанта для улучшения предоставляемого сервиса. ## Повышение проходимости платежей {#section_ll2_kt4_jbb .section} Материалы о том, что помогает обеспечивать высокую проходимость платежей: - [Аутентификация 3‑D Secure](ru_pp_3ds.md)— о процедуре аутентификации пользователей для проведения платежей с использованием карт. - [Проверка Address Verification Service](ru_PP_avs.md)— о процедуре указания почтовых индексов и адресов пользователей для проведения платежей с использованием карт American Express,Mastercard и Visa. - [Дополнение информации о платежах](ru_pp_clarification.md)— о процедуре указания дополнительных данных, которые могут запрашиваться платёжными системами в некоторых случаях. - [Повторные попытки проведения платежей](ru_PP_Try_Again.md)— о возможности предоставлять пользователям дополнительные попытки проведения платежей \(при отклонении предшествующих попыток\), с выбором способа оплаты. - [Каскадное проведение платежей](ru_pp_cascading.md)— о возможности выполнять дополнительные попытки проведения платежей \(когда это актуально\), без изменения способа оплаты. - [Сбор данных о пользователях](ru_PP_Gathering_customer_data.md)— о возможности получать и использовать дополнительную информацию о пользователях, позволяющую минимизировать применение вспомогательных процедур. ## Улучшение пользовательского опыта {#section_unt_bl3_btb .section} Материалы о том, что можно использовать для подстройки платёжных сценариев под разные ситуации: - [Управление языком платёжной формы](ru_PP_WigetLanguages.md)— о возможностях задавать язык, используемый при отображении платёжной формы. - [Предварительный выбор платёжных методов](ru_PP__PreselectingPS.md)— о возможности задавать конкретный платёжный метод при вызове платёжной формы. - [Фильтрация платёжных методов](ru_pp_methods_availability.md)— о возможности отображать пользователям не все, а только актуальные платёжные методы, из числа доступных для проекта. - [Ранжирование платёжных методов](ru_pp_methods_order.md)— о возможностях ранжировать платёжные методы для представления их пользователям в оптимальном порядке. - [Сохранение платёжных данных пользователей](ru_PP_saved_data.md)— о возможностях сохранять и использовать платёжные данные пользователей при работе с платёжной формой. - [Проведение оплат по токенам](ru_PP_Payment_by_token.md)— о возможности применять токены платёжных данных для сокращения пользовательских платёжных сценариев. - [Конвертация валют](ru_pp_currency_conversion.md)— о возможностях проводить платежи с применением разных валют и встроенной в процесс конвертацией. - [Выбор валюты пользователем](ru_pp_currency_choice.md)— о возможности предоставлять пользователям выбор удобных для них валют. - [Поддержка экологических взносов](ru_pp_ekko_earth.md) — о возможности добавлять в пользовательские сценарии внесение добровольных экологических взносов через партнёрский сервис [ekko](https://ekko.earth/). ## Поддержка специфичных сценариев работы {#section_eph_4jr_ctb .section} Материалы о том, как можно адаптировать платёжную форму к специфике различных отраслей, видов бизнеса и частных случаев: - [Погашение задолженностей](ru_PP_debt_repayments.md)— о возможности применять платёжную форму для платежей по кредитам или займам. - [Ограничение времени работы с платёжной формой](ru_pp_time_limit.md)— о возможности устанавливать время, до истечения которого можно совершить оплату. - [Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса](ru_pp_additional_data.md)— о возможности фиксировать сопутствующую информацию о проводимых оплатах для её внутреннего использования. ## Контроль работы с формой {#section_i3t_rb4_btb .section} Материал о возможностях получать и обрабатывать информацию о различных интерфейсных событиях, связанных с платёжной формой и действиями пользователя в ней — [Контроль интерфейсных событий](ru_pp_ui_monitoring.md). ## Информирование пользователей {#section_fd2_j1j_btb .section} Материалы о том, что можно использовать для информирования пользователей: - [Использование сведений о мерчанте при проведении платежей](ru_pp_descriptor.md)— о возможностях опосредованного предоставления пользователям различных сведений о мерчантах через сервисы эмитентов. - [Отправка чеков и оповещений пользователям](ru_PP_receipt_data.md)— о возможностях прямого информирования пользователей о проведении платежей и других событиях через электронную почту. - **[Аутентификация 3‑D Secure](ru_pp_3ds.md)** статья о процедуре аутентификации пользователей с применением протокола 3‑D Secure при проведении через Payment Page карточных платежей - **[Проверка Address Verification Service](ru_PP_avs.md)** статья о процедуре проверки почтовых индексов и адресов пользователей при проведении через Payment Page платежей с использованием карт American Express, Mastercard и Visa - **[Дополнение информации о платежах](ru_pp_clarification.md)** статья о процедуре указания дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Payment Page - **[Повторные попытки проведения платежей](ru_PP_Try_Again.md)** статья о возможности предоставлять пользователям дополнительные попытки проведения платежей через Payment Page при отклонении предшествующих попыток, с доступностью выбора платёжных методов - **[Каскадное проведение платежей](ru_pp_cascading.md)** статья о возможности инициировать дополнительные попытки проведения платежей через Payment Page при отклонении предшествующих попыток, без изменения исходно выбранных платёжных методов - **[Сбор данных о пользователях](ru_PP_Gathering_customer_data.md)** статья о возможности получать и использовать при работе с Payment Page дополнительную информацию о пользователях, позволяющую минимизировать применение вспомогательных процедур - **[Управление языком платёжной формы](ru_PP_WigetLanguages.md)** статья о возможностях задавать язык, используемый при отображении платёжной формы - **[Предварительный выбор платёжных методов](ru_PP__PreselectingPS.md)** статья о возможности задавать конкретный платёжный метод при вызове платёжной формы - **[Фильтрация платёжных методов](ru_pp_methods_availability.md)** статья о возможности управлять наборами платёжных методов, актуальными для конкретных вызовов платёжной формы - **[Ранжирование платёжных методов](ru_pp_methods_order.md)** статья о возможностях ранжировать платёжные методы, чтобы представлять их пользователям в платёжной форме в оптимальном порядке - **[Сохранение платёжных данных пользователей](ru_PP_saved_data.md)** статья о возможностях сохранять и использовать платёжные данные пользователей при работе с платёжной формой - **[Проведение оплат по токенам](ru_PP_Payment_by_token.md)** статья о возможности применять в работе с Payment Page токены платёжных данных для сокращения пользовательских платёжных сценариев - **[Конвертация валют](ru_pp_currency_conversion.md)** статья о возможностях проводить через Payment Page платежи с применением разных валют и встроенной в этот процесс конвертацией - **[Выбор валюты пользователем](ru_pp_currency_choice.md)** статья о возможности предоставлять пользователям выбор удобных для них валют непосредственно в платёжной форме - **[Поддержка экологических взносов](ru_pp_ekko_earth.md)** статья о возможности добавлять в пользовательские сценарии с применением платёжной формы внесение добровольных экологических взносов через партнёрский сервис ekko - **[Погашение задолженностей](ru_PP_debt_repayments.md)** статья о возможности применять платёжную форму для платежей по кредитам и займам - **[Ограничение времени работы с платёжной формой](ru_pp_time_limit.md)** статья о возможности устанавливать время, до истечения которого можно совершать платежи в рамках отдельных вызовов платёжной формы - **[Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса](ru_pp_additional_data.md)** статья о возможности фиксировать при работе через Payment Page сопутствующую информацию о проводимых оплатах для её внутреннего использования в работе мерчантов - **[Контроль интерфейсных событий](ru_pp_ui_monitoring.md)** статья о возможностях получать и обрабатывать информацию о различных интерфейсных событиях, связанных с платёжной формой и действиями пользователя в ней - **[Использование сведений о мерчанте при проведении платежей](ru_pp_descriptor.md)** статья о возможностях опосредованно предоставлять пользователям сведения о мерчантах через сервисы эмитентов при работе через Payment Page - **[Отправка чеков и оповещений пользователям](ru_PP_receipt_data.md)** статья о возможностях прямо информировать пользователей о проведении платежей и других событиях через электронную почту при работе через Payment Page **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Аутентификация 3‑D Secure {#ru_pp_3ds} статья о процедуре аутентификации пользователей с применением протокола 3‑D Secure при проведении через Payment Page карточных платежей ## Общая информация {#section_yky_cln_njc .section} Аутентификация пользователя с использованием протокола 3‑D Secure \(Three-Domain Secure\) предназначена для безопасного проведения интернет-оплат с использованием платёжных карт. Такая аутентификация, как правило, обязательна для проведения классических карточных оплат и может выполняться по-разному: как с необходимостью пользователя выполнить определённые действия для подтверждения своей личности, так и без такой необходимости. **Прим.:** В настоящее время как со стороны платёжных систем American Express, Mastercard и Visa, так и со стороны Ecommpay поддерживается вторая версия протокола — 3‑D Secure 2. И представленная в этой статье информация относится к данной версии протокола. Аутентификация 3‑D Secure может выполняться в следующих вариантах: - Аутентификация с подтверждением пользователем своей личности \(*challenge flow*\). В этом случае подтверждение личности пользователя выполняется, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом. - Аутентификация без участия пользователя \(*frictionless flow*\). В этом случае личность пользователя подтверждается исходя из информации, которой располагает эмитент. ![](images/3ds2_flow.svg) Со стороны мерчанта выбирать варианты аутентификации нельзя — можно лишь указывать предпочтения по такому выбору для конкретных платежей, но итоговое решение каждый раз принимается на стороне эмитента. Также, помимо указания предпочтений, в запросах на проведение платежей можно передавать ряд других необязательных параметров, применение которых может повышать вероятность выбора варианта аутентификации frictionless flow и, как следствие, способствовать повышению проходимости и улучшению пользовательского опыта. Информация о таких параметрах представлена [далее](ru_pp_3ds.md). **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) ## Особенности {#ru_pp_3ds_special_aspects} ### Область применения {#section_s45_tgy_jjc .section} Выполнение аутентификации 3‑D Secure, как правило, обязательно для платежей с прямым использованием платёжных карт. Это связано с требованиями второй директивы о платёжных услугах \(Payment Services Directive 2, PSD2\), включающими в себя необходимость выполнения строгой аутентификации пользователя \(Strong Customer Authentication, SCA\) при проведении таких платежей. К платежам, на которые не распространяются требования PSD2 к строгой аутентификации, относятся: - Оплаты с использованием платёжных карт, выпущенных за пределами Европейской экономической зоны. - Оплаты с использованием анонимных предоплаченных платёжных карт, например с использованием подарочной карты или виртуальной карты с предоплаченной стоимостью. - Оплаты категории Mail Order/Telephone Order \(MO/TO\). - Оплаты, инициируемые мерчантом \(Merchant-initiated transactions, MIT\), к которым в платёжной платформе Ecommpay относятся регулярные оплаты и автооплаты \(с типом платежа `recurring`\), а также операции по изменению суммы предварительной блокировки \(с типом операции `incremental`\). - Оплаты с использованием большинства альтернативных платёжных методов. В платёжной платформе Ecommpay поддерживается определение таких платежей, и аутентификация для них не выполняется. ### Допустимые исключения {#section_f33_5gy_jjc .section} Среди тех платежей, на которые распространяются базовые требования к строгой аутентификации, директива PSD2 допускает наличие исключений \(SCA Exemptions\), при которых аутентификация может не выполняться по решениям эмитентов. Такими исключениями могут выступать платежи следующих категорий: - Платежи на незначительные суммы \(Low value\) — оплаты на суммы до 25 фунтов стерлингов \(в пределах Великобритании\) или 30 евро \(в пределах Европейской экономической зоны\), в случаях, когда с момента последней успешной аутентификации было проведено не более пяти платежей и общая сумма этих платежей не превышает 85 фунтов стерлингов или 100 евро соответственно. - Платежи с низким уровнем риска \(Transaction Risk Analysis\) — оплаты, проводимые эквайером, уровень мошенничества в платёжном трафике которого соответствует порогам PSD2. - Платежи доверенным мерчантам \(Trusted beneficiaries\) — оплаты в пользу тех мерчантов, которые по инициативе или с согласия держателя карты занесены в список доверенных. - Безопасные корпоративные платежи \(Corporate payments\) — оплаты, инициируемые юридическими лицами с использованием процессов и протоколов, обеспечивающих высокий уровень защиты от мошенничества \(таких как Electronic Banking Internet Communication Standard, EBICS\). В платёжной платформе Ecommpay поддерживается работа с исключениями для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa в рамках первых двух категорий \(на незначительные суммы и с низким уровнем риска\). ### Работа с допустимыми исключениями {#section_lcr_5gy_jjc .section} Применение исключений может уменьшать количество действий со стороны пользователей и положительно влиять на проходимость платежей. При этом ответственность за возможные мошеннические действия для таких платежей возлагается на мерчанта. Если эта возможность подключена, то применение соответствующих исключений инициируется автоматически, кроме тех случаев, когда со стороны мерчанта указано предпочтительное выполнение аутентификации. При этом следует учитывать, что в случае проведения платежа, который относится к исключениям, итоговое решение о необходимости аутентификации так же остаётся за эмитентом. С его стороны может быть направлен „мягкий отказ“ \(soft decline\), означающий необходимость выполнения аутентификации. В случае получения такого отказа аутентификация для искомого платежа выполняется стандартно, без применения исключений, и, как правило, в варианте *challenge flow*. Кроме того, исключения не могут применяться при регистрации повторяемых оплат — в таких случаях выполнение аутентификации 3‑D Secure обязательно. Информация о применённых исключениях передаётся в оповещениях о результатах платежей и отображается в карточках платежей в интерфейсе Dashboard. По вопросам, касающимся подключения возможности применения исключений, можно обращаться к курирующему менеджеру Ecommpay. ## Пользовательские сценарии {#ru_pp_3ds_user_scenarios} Со стороны пользователя проведение оплаты с аутентификацией 3‑D Secure может выглядеть следующим образом: 1. На стороне веб-сервиса мерчанта пользователь подтверждает готовность перейти к оплате. 2. Пользователю отображается платёжная форма с учётом параметров её вызова, после чего он выполняет необходимые действия, подтверждает оплату и ему отображается страница ожидания Payment Page. 3. Если эмитентом выбран вариант аутентификации challenge flow, пользователю отображается страница аутентификации \(ACS\), после чего он выполняет необходимые действия и ему отображается страница ожидания Payment Page. 4. Пользователю отображается страница Payment Page с информацией о результате оплаты. ![](images/ecommpay/ru_pp_3ds.svg) ## Подключение {#ru_pp_3ds_implementation} Аутентификация 3‑D Secure подключается для проекта специалистами Ecommpay вместе с подключением карточных платежей, дополнительных действий со стороны мерчанта не требуется. ## Форматы данных {#ru_pp_3ds_data_formats} ### Обязательные параметры {#section_q1t_whf_ldc .section} В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, за исключением запросов на проверку действительности \(режим работы платёжной формы Card Verify\), вместе с обязательными для соответствующего типа платежа параметрами необходимо передавать один из следующих параметров. |Параметры|Описание| |---------|--------| |`customer_email` string |Адрес электронной почты пользователя. Необходимо передавать, если не передан номер телефона пользователя| |`customer_phone` string |Номер телефона пользователя. Необходимо передавать, если не передан адрес электронной почты пользователя| ### Рекомендуемые параметры {#section_mll_xhf_ldc .section} В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, рекомендуется передавать ряд необязательных параметров, указание которых может повышать вероятность выбора эмитентами варианта аутентификации frictionless flow, без участия пользователя. Это может быть, например, информация о предпочтительном варианте аутентификации, выбранном способе доставки, расчётном адресе пользователя и его контактных данных. Такую информацию можно собирать любым удобным способом, в том числе непосредственно в платёжной форме \(с использованием возможности [сбора данных о пользователях](ru_PP_Gathering_customer_data.md)\), и указывать в следующих параметрах. |Параметр|Описание| | |--------|--------|--| |`payment_merchant_risk` string |Дополнительные сведения об оплате товара или услуги пользователем и о предпочтительном для мерчанта варианте аутентификации 3‑D Secure. Представляют собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64. ``` {#codeblock_oxy_r32_wdc .language-json} { "payment":{ "reorder":"01", "preorder_purchase":"01", "preorder_date":"11-10-2022", "challenge_indicator":"01", "challenge_window":"01", "gift_card":{ "amount":12345, "currency":"USD", "count":1 } } } ``` ``` {#codeblock_gjg_s32_wdc} eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9== ``` |2| |`challenge_indicator` string |Индикатор предпочтения по использованию варианта аутентификации challenge flow, который может принимать одно из следующих значений: - `01` — без предпочтений - `02` — предпочтительно не использовать - `03` — предпочтительно использовать - `04` — обязательно использовать - `05` — не использовать, анализ рисков выполнен на стороне мерчанта - `06` — не использовать, применить сценарий Data Only - `07` — не использовать, Strong Customer Authentication уже выполнена иным способом - `08` — не использовать, мерчант включен в список доверенных для этого пользователя - `09` — обязательно использовать, предпочтительно предложить пользователю добавить мерчанта в список доверенных |2-12| |`challenge_window` string |Индикатор размера окна для открытия страницы аутентификации, который может принимать одно из следующих значений: - `01` — 250 x 400 пикселей - `02` — 390 x 400 пикселей - `03` — 500 x 600 пикселей - `04` — 600 x 400 пикселей - `05` — полноэкранный режим |2-22| |`preorder_date` string |Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`|2-32| |`preorder_purchase` string |Индикатор предварительного заказа, который может принимать одно из следующих значений: - `01` — не является предварительным заказом - `02` — является предварительным заказом |2-42| |`reorder` string |Индикатор первичной или повторной покупки данного товара или услуги пользователем, который может принимать одно из следующих значений:- `01` — первичная покупка - `02` — повторная покупка |2-52| |`gift_card` object |Объект со сведениями о покупке предоплаченных или подарочных карт|2-62| |`amount` integer |Сумма покупки, в дробных единицах валюты, указанной в параметре `currency` этого же объекта|2-6-12-6| |`currency` string |Код валюты для суммы покупки в формате ISO 4217 alpha-3 \(например, `GBP`\)|2-6-22-6| |`count` integer |Количество приобретаемых предоплаченных или подарочных карт|2-6-32-6| |`customer_account_info` string |Информация об учётной записи пользователя на стороне веб-сервиса и о его контактных данных. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64. ``` {#codeblock_ekv_1mh_vdc .language-json} { "customer":{ "address_match":"Y", "home_phone":"44991234567", "work_phone":"44997654321", "account":{ "additional":"gamer12345", "age_indicator":"01", "date":"01-10-2022", "change_indicator":"01", "change_date":"01-10-2022", "pass_change_indicator":"01", "pass_change_date":"01-10-2022", "purchase_number":12, "provision_attempts":16, "activity_day":22, "activity_year":222, "payment_age_indicator":"01", "payment_age":"01-10-2022", "suspicious_activity":"01", "auth_method":"01", "auth_time":"01-10-202213:12", "auth_data":"login_0102" } } } ``` ``` {#codeblock_h4d_bmh_vdc} eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI3OTEwNTIxMTExMSIsCiAgICAid29ya19waG9uZSI6Ijc0OTU1MjExMTExIiwKICAgICJhY2NvdW50Ijp7IAogICAgICAiYWRkaXRpb25hbCI6ImdhbWVyMTIzNDUiLAogICAgICAiYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImRhdGUiOiIwMS0xMC0yMDIyIiwKICAgICAgImNoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJjaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicGFzc19jaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGFzc19jaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicHVyY2hhc2VfbnVtYmVyIjoxMiwKICAgICAgInByb3Zpc2lvbl9hdHRlbXB0cyI6MTYsCiAgICAgICJhY3Rpdml0eV9kYXkiOjIyLAogICAgICAiYWN0aXZpdHlfeWVhciI6MjIyMiwKICAgICAgInBheW1lbnRfYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBheW1lbnRfYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJzdXNwaWNpb3VzX2FjdGl2aXR5IjoiMDEiLAogICAgICAiYXV0aF9tZXRob2QiOiIwMSIsCiAgICAgICJhdXRoX3RpbWUiOiIwMS0xMC0yMDIyMTM6MTIiLAogICAgICAiYXV0aF9kYXRhIjoibG9naW5fMDEwMiIKICAgIH0KICB9Cn0== ``` |3| |`address_match` string |Указатель совпадения расчётного адреса пользователя с адресом доставки, указанным в параметре `customer_shipping`, который может принимать одно из следующих значений: - `Y` — адреса совпадают - `N` — адреса не совпадают |3-13| |`home_phone` string |Номер домашнего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44991234567`\)|3-23| |`work_phone` string |Номер рабочего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44997654321`\)|3-33| |`account` object |Объект со сведениями об учётной записи пользователя на стороне веб-сервиса мерчанта|3-43| |`additional` string |Дополнительная информация об учётной записи пользователя, например её идентификатор, в произвольном формате с использованием до 64 символов|3-4-13-4| |`activity_day` integer |Количество попыток проведения оплаты за последние 24 часа, в виде числа от 0 до 999 \(`999`\)|3-4-23-4| |`activity_year` integer |Количество попыток проведения оплаты за последние 365 дней, в виде числа от 0 до 999 \(`999`\)|3-4-33-4| |`age_indicator` string |Индикатор давности учётной записи, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(при инициировании платежа без аутентификации пользователя\) - `02` — при нулевой давности \(при создании учётной записи для инициирования платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |3-4-43-4| |`auth_data` string |Дополнительная информация об аутентификации на стороне веб-сервиса, в произвольном формате с использованием не более 255 символов|3-4-53-4| |`auth_method` string |Указатель способа последней аутентификации пользователя на стороне веб-сервиса, который может принимать одно из следующих значений:- `01` — отсутствие аутентификации - `02` — аутентификация с использованием данных, сохранённых на стороне веб-сервиса мерчанта - `03` — аутентификация с использованием технологии Federated Identity \(например, Google Account или Facebook\) - `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\) |3-4-63-4| |`auth_time` string |Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`|3-4-73-4| |`date` string |Дата создания учётной записи в формате `ДД-ММ-ГГГГ`|3-4-83-4| |`change_date` string |Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`|3-4-93-4| |`change_indicator` string |Индикатор давности изменений в учётной записи, за исключением изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при нулевой давности \(при изменениях в день проведения платежа\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней |3-4-103-4| |`pass_change_date` string |Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`|3-4-113-4| |`pass_change_indicator` string |Индикатор давности последнего изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(пароль не был изменён или сброшен\) - `02` — при нулевой давности \(пароль был изменён или сброшен в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |3-4-123-4| |`payment_age` string |Дата добавления реквизитов платёжного инструмента в формате `ДД-ММ-ГГГГ`|3-4-133-4| |`payment_age_indicator` string |Индикатор давности сохранения данных платёжного инструмента, используемых для проведения платежа, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(платёж проводится без аутентификации в учётной записи\) - `02` — при нулевой давности \(данные карты сохранены в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |3-4-143-4| |`provision_attempts` integer |Количество попыток сохранения реквизитов для новых платёжных инструментов за последние 24 часа, от 0 до 999 \(`999`\)|3-4-153-4| |`purchase_number` integer |Количество покупок, совершённых через учётную запись за последние 6 месяцев, от 0 до 9999 \(`9999`\)|3-4-163-4| |`suspicious_activity` string |Индикатор подозрительной активности, который может принимать одно из следующих значений:- `01` — без выявления подозрительной активности - `02` — с выявлением подозрительной активности |3-4-173-4| |`customer_shipping` string |Информация о доставке товара или услуги пользователю. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64. ``` {#codeblock_bkk_2mx_vdc .language-json} { "customer":{ "shipping":{ "type":"01", "delivery_time":"01", "delivery_email":"test@gmail.com", "address_usage_indicator":"01", "address_usage":"01-10-2022", "city":"Vilnius", "country":"LT", "address":"Dukstu street 30", "postal":"LT-071171", "region":"Vilnius County", "region_code":"VL", "name_indicator":"01" } } } ``` ``` {#codeblock_qxv_2mx_vdc} eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTW9zY293IiwKICAgICAgImNvdW50cnkiOiJSVSIsCiAgICAgICJhZGRyZXNzIjoiTGVuaW5hIHN0cmVldCAxMiIsCiAgICAgICJwb3N0YWwiOiIxMDkxMTEiLAogICAgICAicmVnaW9uX2NvZGUiOiJSVSIsCiAgICAgICJuYW1lX2luZGljYXRvciI6IjAxIgogICAgfQogIH0KfQ==== ``` |4| |`shipping` object |Объект со сведениями о доставке|4-14| |`address` string |Название улицы и номер дома в адресе доставки \(с обозначением корпуса или строения, где это актуально\), в виде строки длиной не более 150 символов|4-1-14-1| |`address_usage` string |Дата первого использования указанного адреса, в формате `ДД-ММ-ГГГГ`|4-1-24-1| |`address_usage_indicator` string |Индикатор давности первого использования указанного адреса доставки, который может принимать одно из следующих значений:- `01` — при нулевой давности \(указанный адрес используется впервые\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней |4-1-34-1| |`city` string |Название города \(или иного населённого пункта\) в адресе доставки, в виде строки длиной не более 50 символов|4-1-44-1| |`country` string |Код страны в адресе доставки в формате ISO 3166-1 alpha-2 \(например, `LT`\)|4-1-54-1| |`delivery_email` string |Адрес электронной почты в случае доставки на этот адрес, может содержать не более 255 символов|4-1-64-1| |`delivery_time` string |Индикатор срока доставки, который может принимать одно из следующих значений:- `01` — в день покупки в электронном виде - `02` — в день покупки в материальном виде - `03` — на следующий день после покупки - `04` — позднее чем на следующий день после покупки |4-1-74-1| |`name_indicator` string |Индикатор совпадения имени пользователя с именем получателя доставки, который может принимать одно из следующих значений:- `01` — имена совпадают - `02` — имена не совпадают |4-1-84-1| |`postal` string |Почтовый индекс в адресе доставки, представляет собой строку длиной не более 16 символов|4-1-94-1| |`region_code` string |Внутренний код региона в адресе доставки, представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, например `VL` для Вильнюсского уезда. При указании значения этого параметра также необходимо указать значение параметра `country` этого же объекта |4-1-104-1| |`type` string |Указатель варианта доставки, который может принимать одно из следующих значений:- `01` — доставка на расчётный адрес держателя карты - `02` — доставка на другой подтверждённый адрес - `03` — доставка на адрес, не совпадающий с расчётным и не являющийся подтверждённым - `04` — доставка в магазин мерчанта - `05` — доставка в электронном виде - `06` — отсутствие доставки - `07` — другой вариант |4-1-114-1| |`customer_mpi_result` string |Информация о предыдущей аутентификации пользователя. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64. ``` {#codeblock_er2_5jx_vdc .language-json} { "customer":{ "mpi_result":{ "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54", "authentication_flow":"01", "authentication_timestamp":"202210101050" } } } ``` ``` {#codeblock_wtq_5jx_vdc} eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0== ``` |5| |`mpi_result` object |Объект с данными о предыдущей аутентификации пользователя|5-15| |`acs_operation_id` string |Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре `acs_operation_id` оповещения о результате проведения предыдущего платежа|5-1-15-1| |`authentication_flow` string |Указатель варианта предыдущего прохождения аутентификации пользователем, полученный в параметре `authentication_flow` оповещения о результате проведения предыдущего платежа, который может принимать одно из следующих значений: - `01` — frictionless flow - `02` — challenge flow |5-1-25-1| |`authentication_timestamp` string |Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре `mpi_timestamp` оповещения о результате проведения предыдущего платежа|5-1-35-1| |`billing_address` string |Название улицы в расчётном адресе пользователя|6| |`billing_city` string |Название города в расчётном адресе пользователя|7| |`billing_country` string |Код страны в расчётном адресе пользователя в формате ISO 3166-1 alpha-2|8| |`billing_postal` string |Почтовый индекс в расчётном адресе пользователя|9| |`billing_region_code` string |Внутренний код региона \(штата, провинции или иной территориальной области\) в расчётном адресе пользователя, например `VL` для Вильнюсского уезда. Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. При указании значения этого параметра также необходимо указать значение параметра `billing_country` |10| |`customer_email` string |Адрес электронной почты пользователя|11| |`customer_phone` string |Номер телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей|12| --- # Проверка Address Verification Service {#ru_PP_avs .concept} статья о процедуре проверки почтовых индексов и адресов пользователей при проведении через Payment Page платежей с использованием карт American Express, Mastercard и Visa ## Общая информация {#section_ofb_dcx_ydb .section} **Address Verification Service** \(AVS\) — это сервис, который позволяет вам проверить, действительно ли пользователь, совершающий платеж, является владельцем банковской карты. Проверка происходит путем сверки адреса, указанного пользователем при осуществлении платежа, с адресом владельца карты по данным банка-эмитента карты. При использовании карт платёжных систем Visa и Mastercard проверка AVS обязательна для операций, совершаемых на территории Великобритании, и опциональна для США, Австралии, Канады и Новой Зеландии. При использовании карт платёжной системы American Express такая проверка обязательна для США и Канады и опциональна для других стран.Поэтому при отправке запроса на проведение платежа может потребоваться введение пользователем дополнительных обязательных параметров: почтовые индекс `avs_post_code` и адрес `avs_street_address` пользователя, подробную информацию см. в [Дополнение информации о платежах](ru_pp_clarification.md). В случае если полученные данные не проходят проверку, не переданы или не заполнены, вы получите соответствующие код и сообщение об отказе в проведении платежа. Результат проверки AVS передается в оповещении в параметре `avs_result`. **Прим.:** Требование по предоставлению полей AVS сохраняется даже если платеж осуществляется по токену или сохраненной карте. ## Результаты проверки AVS {#section_gq3_n12_pfb .section} Возможные коды параметра avs\_result и соответствующие значения и описания приведены в таблицах ниже. |Код|Значение|Описание| |---|--------|--------| |W, Z|Частичное совпадение|Почтовый индекс пользователя совпадает, адрес — нет| |A|Частичное совпадение|Адрес пользователя совпадает, почтовый индекс — нет| |X, Y|Полное совпадение|Адрес и почтовый индекс пользователя совпадают| |N|Полное несовпадение|Ни адрес, ни почтовый индекс не совпадают| |S, U|Информация недоступна|Для текущего аккаунта информация об адресе недоступна, либо банк-эмитент не поддерживает AVS| |R|Система недоступна|Система авторизации банка-эмитента на данный момент недоступна. Можно повторить попытку| |Visa|A, N, R, U, Y, Z| |MasterCard|A, N, R, S, U, W, X, Y, Z| |American Express|A, N, R, S, U, Y, Z| **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Дополнение информации о платежах {#ru_pp_clarification .concept} статья о процедуре указания дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Payment Page ## Общая информация {#section_vgn_22h_nmb .section} В общем случае для проведения платежа в запросе на открытие Payment Page достаточно передавать набор параметров, обязательных для инициирования этого платежа. Но в некоторых случаях со стороны платёжной системыили провайдера могут запрашиваться дополнительные данные, необходимые для проведения конкретного платежа. Это может быть вызвано специфическими региональными требованиями, необходимостью дополнительной проверки на мошенничество или иными факторами. При работе с Payment Page для таких ситуаций используется процедура *дополнения информации о платеже*, в рамках которой обеспечиваются уведомление пользователя о необходимости дополнить данные, сбор этих данных и переход к дальнейшей обработке платежа с учётом полученной информации. При дополнении информации о платеже никаких дополнительных действий со стороны веб-сервиса не требуется, поскольку выполнение процедуры обеспечивается за счёт взаимодействия пользователя с платёжной формой. Однако чтобы уйти от необходимости в дополнении информации о платеже, со стороны веб-сервиса в запросах на открытие Payment Page можно обеспечивать передачу данных, которые могут запрашиваться со стороны платёжных системи провайдеров для проведения платежа, в том числе необязательных. Запрашиваемые данные обычно представляют собой сведения о пользователе и его платёжном инструменте, однакопри проведении платежей с использованием альтернативных платёжных методов могут требоваться и другие параметры из числа допустимых для работы с Payment Page. К запрашиваемым данным о пользователе могут относиться: - `customer_first_name` — имя; - `customer_last_name` — фамилия; - `customer_middle_name` — отчество или среднее имя; - `customer_day_of_birth` — дата рождения; - `customer_email` — адрес электронной почты; - `customer_address` — название улицы и номер дома \(с обозначением корпуса или строения, где это актуально\) в адресе проживания пользователя; - `customer_city` — название города проживания; - `customer_country` — код страны проживания; - `customer_street` — название улицы проживания; - `customer_zip` — почтовый индекс. **Прим.:** Итоговый набор запрашиваемых данных зависит от требований конкретного провайдера или платёжной системы и может варьироваться. Для уточнения возможного набора запрашиваемых данных в зависимости от используемого платёжного метода, можно обращаться к курирующему менеджеру Ecommpay. При возникновении необходимости дополнения данных пользователь указывает запрашиваемые сведения в платёжной форме и подтверждает проведение платежа. Информация о действиях пользователя в таких случая представлена далее. ## Пользовательский сценарий {#section_hbw_wjh_nmb .section} Базовый пользовательский сценарий проведения оплаты при дополнении информации о платеже можно представить следующим образом: 1. На стороне веб-сервиса мерчанта пользователь подтверждает готовность перейти к оплате и перенаправляется к платёжной форме. При использовании ограничения времени работы с Payment Page на форме дополнительно отображается отсчёт времени. 2. Пользователь указывает данные платёжного инструмента. 3. В результате того, что в платёжной платформе выявляется необходимость в дополнении данных, в Payment Page отображается страница с уведомлением и полями для ввода дополнительных данных. Пользователь указывает запрашиваемые данные, подтверждает проведение оплаты и получает информацию о результате. ![](images/ecommpay/ru_pp_clarification_1.svg "1 — Открытие платёжной формы") ![](images/ecommpay/ru_pp_clarification_2.svg "2 — Указание данных платёжного инструмента") ![](images/ecommpay/ru_pp_clarification_3.svg "3 — Указание дополнительных данных") ## Схема работы {#section_gd4_gkh_nmb .section} Процедура дополнения информации о платеже выполняется по следующей схеме. ![](images/ru_pp_clarification_uml.svg) 1. При выявлении необходимости дополнения информации о платеже в платёжной платформе формируется набор запрашиваемых данных и передаётся в Payment Page. 2. Пользователю отображается страница ввода дополнительных данных. 3. Пользователь указывает запрашиваемые данные. 4. Эти данные передаются в платёжную платформу. 5. На стороне платёжной платформы выполняется обработка полученных данных, после чего проведение платежа продолжается обычным образом. ## Особенности применения {#section_ol1_ykh_nmb .section} При использовании ограничения времени работы с Payment Page следует учитывать, что время на дополнение информации о платеже включается в общее время работы пользователя с платёжной формой.Это означает, что при указании срока действия платёжной формы необходимо учитывать возможное выполнение процедуры дополнения информации. Если ограничение времени работы с платёжной формойне задано, время ожидания на ввод дополнительной информации устанавливается по умолчанию и составляет 30 минут с момента выявления необходимости дополнить данные. В любом из этих случаев, если время ожидания истекло и данные не переданы в платформу — платёж автоматически отклоняется. Для контроля платежей, при проведении которых выполнялась процедура дополнения информации можно использовать оповещения и сведения из карточек платежей, доступных в интерфейсе Dashboard \(подробнее — в разделе [Контроль и проведение платежей](ru_dbl_payments.md)\). В промежуточных и итоговых оповещениях, отправляемых со стороны платёжной платформы, содержится набор данных, запрошенных у пользователя во время процедуры дополнения информации о платеже. К особенностям промежуточных оповещений также можно отнести статус платежа, который присваивается платежу до момента получения данных от пользователя — `awaiting_clarification`. Так, в следующем примере в рамках дополнения информации о платеже запрашивается адрес пользователя, необходимый для дальнейшего проведения оплаты с использованием платёжной карты. ```language-json { "project_id": 1173, "payment": { "id": "15557465346", "type": "purchase", "status": "awaiting clarification", // статус платежа "date": "2020-07-30T10:20:58+0000", "method": "card", "sum": { "amount": 131970, "currency": "USD" }, "description": "" }, "account": { "number": "431422****0056", "type": "visa", "card_holder": "JOHN DOE", "expiry_month": "01", "expiry_year": "2023" }, "customer": { "id": "3b6d6827-8cdd-4040" }, "clarification_fields": { // запрашиваемые данные "avs\_data": \[ "avs\_address" \] }, "operation": { "id": 72658000000461, "type": "sale", "status": "awaiting clarification", "date": "2020-07-30T10:20:58+0000", "created_date": "2020-07-30T10:20:58+0000", "request_id": "c0f65543b97c062c8d4f975bfd397aef6aa55a71-00072659", "sum_initial": { "amount": 131970, "currency": "USD" }, "sum_converted": { "amount": 131970, "currency": "USD" }, "code": "9999", "message": "Awaiting processing", "eci": "00", "provider": { "id": 414, "payment_id": "", "endpoint_id": 414 } }, "signature": "oFcRanmZ5FrWt8zQWqHM15PPWKV5eAfIErQXBS/1uMwzF1..." } ``` **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Повторные попытки проведения платежей {#ru_PP_Try_Again .concept} статья о возможности предоставлять пользователям дополнительные попытки проведения платежей через Payment Page при отклонении предшествующих попыток, с доступностью выбора платёжных методов ## Общая информация {#section_ovx_sqn_smb .section} При работе с Payment Page пользователю, как правило, достаточно одной попытки для проведения платежа. Но в некоторых случаях, например когда пользователь указывает реквизиты платёжной карты, на которой недостаточно средств, для проведения платежа могут потребоваться дополнительные попытки. Для работы с такими ситуациями в платёжной платформе Ecommpay предусмотрена возможность выполнять повторные попытки проведения одного и того же платежа \(с одним идентификатором\) в рамках одного сеанса работы с Payment Page. В общем случае, если возможность выполнения повторных попыток не подключена, при отклонении платежа пользователю отображается итоговая страница с сообщением об ошибке, сеанс работы с Payment Page завершается, и чтобы повторить попытку, пользователю необходимо вернуться к веб-сервису и инициировать новый платёж. Если же возможность выполнения повторных попыток подключена, при отклонении платежа на итоговой странице отображается сообщение об ошибке и предложение повторить попытку \(с дополнительной кнопкой для перехода к этой попытке\). || **Прим.:** Для работы эмулятора платёжной формы необходимы файлы cookie. При отказе от их использования эмулятор не загружается. Поскольку для выполнения повторных попыток не требуется заново открывать платёжную форму, все параметры, указанные в запросе на открытие Payment Page, актуальны как для первой, так и для всех последующих попыток.Это касается в том числе и [предварительного выбора](ru_PP__PreselectingPS.md) платёжных методов и групп методов. В целом при использовании повторных попыток возможности выбора платёжного метода определяются следующим образом. |Предварительный выбор метода или группы|Первая попытка|Каждая повторная попытка| |---------------------------------------|--------------|------------------------| |–\(отсутствует\) |любой из доступных методов|в зависимости от целевого действия, выполнявшегося при первой попытке:- для оплаты — любой из методов, доступных для проведения оплаты - для блокировки средств — любой из методов, доступных для блокировки средств | |карточные платежи|карточные платежи|карточные платежи либо \(если согласовано и настроено\) Apple Pay или Google Pay| |альтернативный метод\(группа методов\) |заданный метод\(группа методов\) |заданный метод\(группа методов\) | **Прим.:** Более подробно возможности выбора платёжного метода при выполнении повторных попыток можно описать следующим образом. - В случаях, когда метод не был задан предварительно, для повторной попытки пользователь может выбрать один из методов, позволяющих выполнять операции того типа, который использовался для первой попытки. Так, если первая попытка касалась блокировки средств в рамках двухстадийной оплаты \(`auth`\), то и для каждой последующей попытки можно выбрать метод, поддерживающий двухстадийные оплаты, чтобы выполнить именно блокировку, а не списание средств \(`sale`\). - В случаях, когда предварительно были заданы карточные платежи и для используемого проекта подключена соответствующая возможность, пользователь может выбрать для повторной попытки не только карточные платежи, но и один из методов Apple Pay или Google Pay. Эта возможность подключается по согласованию с курирующим менеджером Ecommpay. - В случаях, когда в параметрах запроса указан один из альтернативных методов, все повторные попытки выполняются с использованием этого метода, без возможности выбора другого. - В случаях, когда в параметрах запроса указан токен платёжной карты, все повторные попытки выполняются с использованием этого токена, без возможности выбора другого платёжного метода или инструмента. Число дополнительных попыток и время на их выполнение ограничиваются. Эти параметры регулируются по согласованию с курирующим менеджером Ecommpayи применяются для каждого платежа в рамках проекта, для которого подключена возможность выполнения повторных попыток. ## Пользовательский сценарий {#section_ehh_2rn_smb .section} Со стороны пользователя проведение оплаты с выполнением повторных попыток выглядит следующим образом: 1. На стороне веб-сервиса мерчанта пользователь подтверждает готовность перейти к оплате. 2. Пользователю отображается Payment Pageс учётом параметров её вызова, после чего пользователь выполняет необходимые действия и ожидает информацию о результате оплаты. 3. При отклонении оплаты пользователю отображается страница с предложением повторить попытку. Он соглашается и перенаправляется к шагу 2. 4. При проведении оплаты пользователю отображается типовая итоговая страница\(без предложения повторить попытку\). ## Особенности {#section_wx1_r4h_b4b .section} При подключении повторных попыток проведения платежей необходимо учитывать следующие особенности: - *Необходимость отображения итоговой страницы*. Для поддержки возможности выполнения повторных попыток необходимо отображать пользователю итоговую страницу Payment Page. Если при работе с Payment Page применяется автоматическое перенаправление пользователя к веб-сервису \([подробнее](ru_PP_redirect_modes.md)\), то повторные попытки не могут использоваться. - *Поддержка индивидуального дизайна*. При использовании оформления платёжной формы, реализованного не на базовой модели её интерфейса, необходимо согласовать с курирующим менеджером Ecommpay добавление на итоговую страницу Payment Page дополнительного элемента — кнопки для перехода пользователя к повторным попыткам — и при необходимости предоставить соответствующий макет специалистам технической поддержки. - *Учёт времени выполнения повторных попыток*. Отсчёт времени на выполнение всех повторных попыток начинается с момента фиксации на стороне платёжной платформы первого отказа в проведении платежа и не отображается на Payment Page. Однако, если для этого же платежа ограничено время работы с Payment Page \([подробнее](ru_pp_time_limit.md)\), то пользователю отображается обратный отсчёт до завершения этого времени, а время на выполнение повторных попыток игнорируется.В любом из этих случаев, есливремя работы с Payment Page истекло и за это время ни одна попытка не привела к проведению платежа, то платёж отклоняется и пользователю отображается итоговая страница с соответствующим уведомлением. ## Подключение {#section_ahc_dph_b4b .section} Чтобы подключить возможность повторного проведения платежей, со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpay подключение этой возможности, необходимость её тестирования и применение ограничений на набор доступных платёжных методов, число дополнительных попыток и на время их выполнения.Такие ограничения действуют для каждого платежа в рамках проекта и могут настраиваться специалистами Ecommpay с учётом потребностей мерчанта. Типовые значения числа попыток и времени на их выполнение составляют 5 попыток в течение 10 минут. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить работу платёжной формы с использованием этой возможностии сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении возможности. ## Схема работы {#section_ic1_jrh_b4b .section} Повторные попытки проведения платежа выполняются согласно следующей схеме. ![](images/ru_pp_try_again_uml.svg) 1. Если попытка проведения оплаты не завершилась списаниемили блокировкой средств, то для этой оплаты в платёжной платформе проверяется возможность выполнения повторной попытки. 2. От платёжной платформы к веб-сервису направляется оповещение о возможности выполнения повторной попытки. 3. От платёжной платформы к Payment Page передаются данные о возможности выполнения повторной попытки. 4. Пользователю отображается страница с сообщением об отклонении оплаты и предложением повторить попытку. 5. Пользователь соглашается повторить попытку и выполняет необходимые действия. 6. Указанные пользователем данные передаются в платёжную платформу, после чего выполняется очередная попытка проведения платежа с их использованием. При выполнении повторных попыток статус платежа может принимать следующие значения: - `processing` — при проверке возможности выполнения дополнительной попытки в случае отклонения оплаты\(в процессе выполнения шага 1 на схеме\), а также при получении платёжных данных от пользователя в рамках дополнительной попытки\(по результатам выполнения шага 6\); - `awaiting customer` — с момента выявления в платёжной платформе возможности выполнения повторной попытки\(в рамках шага 1\) и до момента получения данных от пользователя\(по результатам выполнения шага 6\) или до момента истечения времени на выполнение повторных попыток \(после чего платежу присваивается итоговый статус `decline`\); - `success` — при выполнении целевого действия \(если одна из выполненных попыток привела к списаниюили блокировке средств\); - `decline` — в случае, если было исчерпано число дополнительных попыток или время на их выполнение и при этом ни одна из выполненных попыток не привела к списаниюили блокировке средств, а также в случае, если пользователь отказался от выполнения повторной попытки. Описание всех используемых статусов платежей представлено в разделе [Проведение платежей](ru_platform_payment_model.md). ## Работа с оповещениями {#section_ft3_qrn_smb .section} При выполнении повторных попыток проведения платежей от платёжной платформы к веб-сервису отправляются промежуточные и итоговые оповещения. *Промежуточные оповещения.* При получении информации об отклонении оплаты и выявлении возможности выполнения повторной попытки этой оплаты от платёжной платформы к веб-сервису отправляется промежуточное оповещение. К особенностям таких оповещений можно отнести наличие параметров, содержащих информацию о доступности повторных попыток \(`is_new_attempts_available`\) и оставшемся времени на их выполнение \(`timeout_attempts`; в секундах — `ss`\). В промежуточных оповещениях параметр `is_new_attempts_available` принимает значение `true`, что означает одновременное выполнение следующих условий: - ни одна попытка ещё не привела к проведению платежа; - остаются доступные попытки; - остаётся время на выполнение повторных попыток. В следующем примере содержится информация о том, что в рамках оплаты `100028024` доступны повторные попытки \(`is_new_attempts_available = true`\) и на их выполнение остаётся десять минут \(`attempts_timeout = 600`\). ```language-json { "project_id": 212, "payment": { "id": "100028024", "type": "purchase", "status": "awaiting customer", // статус платежа "date": "2020-07-21T17:51:04+0000", "method": "card", "is_new_attempts_available": true, // доступность повторных попыток "attempts_timeout": 600, // оставшееся время "sum": { "amount": 131970, "currency": "USD" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "JOHN DOE", "expiry_month": "01", "expiry_year": "2023" }, "operation": { "id": 20759000013841, "type": "auth", "status": "decline", "date": "2020-07-21T17:51:04+0000", "created_date": "2020-07-21T17:20:55+0000", "request_id": "7ba0fb24436a717d3091f7b71007891696db6e-00020760", "sum_initial": { "amount": 131970, "currency": "USD" }, "sum_converted": { "amount": 131970, "currency": "USD" }, "code": "108", "provider": { "id": 414, "payment_id": "", "endpoint_id": 414 } }, "signature":"oXlx8QWh3OC/YOqb2ib3C5jq/lHvisceI9Lqg/tRTuwcrNmj1zQ..." } ``` *Итоговые оповещения.* В случае, если платёж удалось провести или больше нет возможности для его проведения, со стороны платёжной платформы отправляется итоговое оповещение.В итоговых оповещениях параметр `is_new_attempts_available` принимает значение `false`, что означает выполнение одного из следующих условий: - по итогам последней попытки платёж был проведён; - пользователь отказался от дополнительной попытки; - все доступные попытки исчерпаны; - доступное время истекло. В следующем примере содержится информация о том, что время на выполнение повторных попыток истекло и оплата отклонена. ```language-json { "project_id": 212, "payment": { "id": "100028024", "type": "purchase", "status": "decline", // статус платежа "date": "2020-07-21T17:51:04+0000", "method": "card", "is_new_attempts_available": false, // доступность повторных попыток "attempts_timeout": 0, // оставшееся время "sum": { "amount": 131970, "currency": "USD" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "JOHN DOE", "expiry_month": "01", "expiry_year": "2023" }, "operation": { "id": 20759000013841, "type": "auth", "status": "decline", "date": "2020-07-21T17:51:04+0000", "created_date": "2020-07-21T17:20:55+0000", "request_id": "7ba0fb24436a717d3091a2bdf7891696db6e-00020760", "sum_initial": { "amount": 131970, "currency": "USD" }, "sum_converted": { "amount": 131970, "currency": "USD" }, "code": "603", "message": "Auto decline", "provider": { "id": 414, "payment_id": "", "endpoint_id": 414 } }, "signature": "oXlx8QWh3OC/YOqb2ib3C5VLPksceI9Lqg/tRTuwcrNmj1zQ..." } ``` **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Каскадное проведение платежей {#ru_pp_cascading} статья о возможности инициировать дополнительные попытки проведения платежей через Payment Page при отклонении предшествующих попыток, без изменения исходно выбранных платёжных методов **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) ## Общая информация {#ru_pp_cascading_info} Для случаев, когда проведение платежа прерывается по различным причинам, в платформе Ecommpay поддерживается возможность каскадного проведения платежей, которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеров без изменения платёжного метода. Такое проведение платежей поддерживается как для *карточных* платежей \(с прямым использованием платёжных карт\), так и для *альтернативных* \(с использованием альтернативных платёжных методов\). Однако в каждом из этих случаев есть свои особенности: при работе с альтернативными методами допускается неоднократное списание средств со счёта пользователя, поэтому инициатором дополнительных попыток может быть только пользователь, в то время как при работе с прямым использованием карт средства могут списываться однократно, поэтому инициирование дополнительных попыток осуществляется на стороне платёжной платформы. Далее в этом разделе представлена подробная информация о схемах каскадного проведения карточных и альтернативныхоплат. За более подробной информацией об особенностях каскадного проведения платежей и о подключении этой возможности рекомендуется обращаться к курирующему менеджеру Ecommpay. ## Оплаты с прямым использованием карт {#ru_pp_cascading_cards} ### Общая информация {#section_rlm_rfp_qjb .section} По различным причинам проведение платежей может прерываться. Например, на стороне провайдеров или банков причинами могут служить технические сбои, задержки в обработке платежа или же достижение лимитов, заданных для пользователя на стороне какого-либо провайдера. Для таких случаев в платформе Ecommpay поддерживается возможность каскадного проведения платежей. Каскадное проведение включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеров без изменения платёжного метода. При работе с прямым использованием карт эта возможность доступна только для разовых оплат в одну или две стадии как с поддержкой, так и без поддержки протокола 3‑D Secure. При работе с прямым использованием карт допускается только однократное списание средств, поэтому инициирование дополнительных попыток осуществляется на стороне платёжной платформы. Для поддержки такой возможности на стороне веб-сервиса не требуются какие-либо технические доработки относительно реализации стандартного проведении разовых оплат. Подробная информация о подключении и схеме каскадного проведения оплат представлена далее. ### Подключение и настройка {#section_fpy_5hcgh_qjb .section} Чтобы подключить каскадное проведение платежей, со стороны мерчанта необходимо согласовать с курирующим менеджером Ecommpay подключение этой возможности и протестировать каскадное проведение оплат совместно с сотрудниками технической поддержки Ecommpay. ### Схема проведения {#section_sb4_nvd_kkb .section} Каскадное проведение платежа начинается стандартно: от веб-сервиса к платёжной платформе отправляется запрос на оплату через Payment Page, после приёма и обработки которого пользователю отображается платёжная форма для ввода данных карты, а затем осуществляется первая попытка проведения оплаты через одного из провайдеров, при необходимости включая аутентификацию пользователя по протоколу 3‑D Secure. Если эта попытка завершается списанием средств, то от платёжной платформы к веб-сервису отправляется оповещение с итоговым статусом платежа — `success`, а иначе продолжается каскадное проведение платежа. Далее, пока ни одна из выполненных попыток не привела к успешному списанию и дополнительные попытки ещё не исчерпаны, на стороне платёжной платформы инициируется выполнение новой попытки. Если в рамках дополнительной попытки не требуется аутентификация 3‑D Secure, то попытка выполняется без взаимодействия с пользователем. Если требуется аутентификация, то на Payment Page отображаются сообщение об ошибке, введённые ранее данные карты и кнопка **Повторить попытку**. Затем с согласия пользователя продолжается выполнение этой оплаты с повторной аутентификацией. Статусу платежа присваивается одно из промежуточных значений \(`awaiting_3ds_result`, `awaiting_redirect_result` или `processing`\). Каскадное проведение платежа заканчивается стандартно: от платёжной платформы к веб-сервису отправляется оповещение с одним из итоговых статусов платежа: `success`, если одна из выполненных попыток привела к списанию средств, или `decline`, если ни одна из выполненных попыток не привела к списанию и лимит на дополнительные попытки исчерпан. Далее представлена схема каскадного проведения оплаты в контексте оплаты в одну стадию с возможной аутентификацией 3‑D Secure. ![](images/universal/cascade/ru_pp_sale_cascading.svg) \* В качестве провайдера может выступать Ecommpay. 1. От платёжной платформы к провайдеру передаётся запрос на проведение платежа. 2. На стороне провайдера выявляется необходимость в аутентификации пользователя. Если требуется аутентификация, то к платформе отправляются данные для перенаправления пользователя, а иначе отправляется запрос к эмитенту на проведение платежа. 3. От платёжной платформы к Payment Page направляется оповещение с данными для перенаправления пользователя. 4. Осуществляется взаимодействие с пользователем: - Если аутентификация первичная, то выполняется перенаправление пользователя на страницу аутентификации \(ACS URL\) эмитента. - Если аутентификация повторная, то сначала пользователю отображается страница с ранее введёнными данными карты, сообщением об ошибке и предложением повторить попытку оплаты, и далее с согласия пользователя выполняется перенаправление на страницу аутентификации \(ACS URL\) эмитента. 5. Пользователю отображается страница аутентификации, и он осуществляет требуемые действия. 6. На стороне эмитента выполняется аутентификация пользователя. 7. От эмитента к платёжной платформе передаются данные о результате аутентификации. 8. Выполняется перенаправление пользователя к Payment Page. 9. Пользователю отображается страница ожидания в платёжной форме. 10. От платёжной платформы к провайдеру отправляется запрос на продолжение проведение платежа. 11. На стороне провайдера осуществляется обработка запроса на проведение платежа. В результате от сервиса провайдера либо к платформе отправляется уведомление об отказе, и на стороне платформы инициируется дополнительная попытка, либо к эмитенту отправляется запрос на проведение оплаты, и продолжается стандартное проведение платежа. ### Формат оповещений {#section_bnh_qw4_rjb .section} При каскадном проведении оплат с прямым использованием платёжных карт от платёжной платформы к веб-сервису отправляются только итоговые оповещения стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). ## Оплаты с использованием альтернативных методов {#ru_pp_cascading_apm} ### Общая информация {#section_xv1_cjb_nmb .section} При проведении оплат с использованием альтернативных методов нередко требуется продолжить оплату в сервисе провайдера в отдельном окне. Однако на продолжение оплаты в этом сервисе могут повлиять различные факторы как субъективного \(обусловленные влиянием пользователя\), так и объективного характера \(без влияния пользователя\). Так, например, проведение платежа может быть прервано по разным причинам: - По инициативе пользователя. Как правило, это происходит после перенаправления к сервису провайдера, когда пользователь закрывает окно случайно или исходя из субъективной оценки ситуации. Результатами такой оценки могут быть боязнь вводить данные банковского счёта из-за недоверия к открывшемуся сервису провайдера, желание перезагрузить окно провайдера из-за непрогрузившихся форм для ввода данных, непонимание, что делать дальше в открывшемся окне, или иные причины. - По не зависящим от пользователя причинам. Как правило, это технические сбои, которые могут возникнуть как на стороне веб-сервиса \(не удаётся перенаправить пользователя к сервису провайдера\), так и на стороне провайдера, например превышение допустимого количества попыток ввода OTP-кода либо промедление пользователя с вводом кода, недоступность провайдера, отказ в проведении платежа из-за обрыва связи или иные причины. Для таких случаев в платформе Ecommpay поддерживается возможность каскадного проведения платежей, которое включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеров без изменения платёжного метода. При работе с альтернативными методами эта возможность доступна только для разовых оплат в одну стадию. Из-за особенностей работы с альтернативными методами допускается неоднократное списание средств в рамках одной оплаты, поэтому инициатором дополнительных попыток может быть только пользователь, подтверждающий согласие на каждую дополнительную попытку. Без согласия пользователя на стороне платёжной платформы никаких действий по инициированию дополнительной попытки не предпринимается. Нередко к неоднократному списанию средств приводит стечение обстоятельств, рассмотренное более подробно в пункте [Пример каскадного проведения оплаты](ru_pp_cascading.md#section_u4m_bzj_clb). Например, к таким обстоятельствам можно отнести: - низкое качество интернет-соединения на стороне любого участника проведения платежа, - некорректную оценку ситуации пользователем, - отсутствие информирования о списании средств на стороне пользователя либо о результате платежа на стороне провайдера как из-за технических сбоев, так и из-за особенностей реализации, а также иные обстоятельства. Для поддержки такой возможности на стороне веб-сервиса рекомендуются доработки относительно реализации стандартного проведении разовых оплат. Подробная информация о подключении и схеме каскадного проведения оплат представлена далее. ### Подключение и настройка {#section_fpy_5hc_qjb .section} Чтобы подключить каскадное проведение платежей и настроить взаимодействие с платёжной платформой, со стороны мерчанта необходимо: 1. Решить организационные вопросы. - Согласовать с курирующим менеджером Ecommpay подключение этой возможности и порядок действий при неоднократном списании средств в рамках одной оплаты. - Выбрать платёжные методы с поддержкой каскадного проведения платежей. Информацию о поддержке этой возможности можно получить в разделе [Методы](ru_pm_about.md) в описании каждого метода и у курирующего менеджера Ecommpay. - При необходимости согласовать с курирующим менеджером Ecommpay текст уведомления с предложением повторить оплату. По умолчанию задан следующий текст: *«В случае технических сложностей \(не открылось окно, произошла ошибка\) повторите попытку оплаты»*. В уведомлении рекомендуется предупреждать пользователя о возможности неоднократного списания средств в рамках одной оплаты. С примером такого уведомления можно ознакомиться на изображениях платёжных страниц в примере далее. 2. Доработать веб-сервис для использования каскадного проведения платежей. - Поддержать взаимодействие с платёжной платформой на программном уровне. Для этого необходимо учесть, что допускается отправка более одного итогового оповещения — при каждой попытке, выполненной со списанием средств. Оповещения отправляются по мере поступления информации о результатах выполнения операций в платёжную платформу, ожидание может занимать до нескольких дней. - Учесть, что логика смены промежуточного статуса платежа на итоговый отличается от стандартной. Промежуточный статус платежа `processing` меняется на итоговый `decline` или `success`, когда в платформу поступают результаты выполнения всех операций и присвоены итоговые статусы этим операциям. Такой случай продемонстрирован в примере далее. - Рекомендуется обеспечить возможность выплат через Gate для тех методов, при работе с которыми доступно проведение выплат. Эту возможность можно использовать в случае неоднократных списаний в рамках одной оплаты. 3. Отладить и протестировать возможность каскадного проведения оплат совместно с сотрудниками технической поддержки Ecommpay. ### Схема проведения {#section_jlv_4wk_kjb .section} Каскадное проведение платежа начинается стандартно: от веб-сервиса к платёжной платформе отправляется запрос на оплату через Payment Page. В платформе после приёма и обработки этого запроса пользователю отображается Payment Page для выбора метода и подтверждения оплаты, а затем осуществляется первая попытка проведения платежа через один из провайдеров с возможным перенаправлением пользователя к сервису провайдера. Если в рамках этой попытки выполняется списание средств без ощутимых задержек на стороне провайдера, то проведение платежа завершается стандартно: к веб-сервису отправляется оповещение с итоговым статусом платежа — `success`, а иначе может продолжаться каскадное проведение платежа. Далее, пока хотя бы одна из выполненных попыток проведения оплаты не привела к списанию и дополнительные попытки ещё не исчерпаны, пользователь может инициировать новую попытку. Каскадное проведение платежа заканчивается нестандартно: итоговое оповещение о результате платежа отправляется к веб-сервису в рамках каждой операции, выполненной со списанием средств. Такие оповещения отправляются по мере поступления в платёжную платформу информации о результатах выполнения операций, и их ожидание может занять до нескольких дней, поэтому на стороне веб-сервиса не рекомендуется завершать взаимодействие с платформой после приема первого оповещения, а при неоднократном списании средств на усмотрение пользователя рекомендуется осуществить возврат. Далее представлена схема каскадного проведения оплаты в контексте оплаты в одну стадию с использованием одного из методов интернет-банкинга Юго-Восточной Азии и при условии, что причиной прерывания проведения платежа являются технические сбои на стороне платёжной системы. ![](images/universal/cascade/ru_pp_sale_cascading_aps.svg) 1. Если выполнение текущей попытки не завершается стандартно: информированием всех участников о результате проведения оплаты без ощутимых задержек на стороне провайдера \(шаги 17–20\* на схеме\), пользователь инициирует дополнительную попытку проведения оплаты. 2. От Payment Page передаётся запрос на дополнительную попытку. 3. В платёжной платформе проверяется, достигнут ли лимит на дополнительные попытки. В результате проверки к Payment Page направляется ответ, который может содержать: - информацию об исчерпанном лимите — в этом случае пользователю предлагается вернуться в веб-сервис, чтобы начать оплату сначала, и взаимодействие с пользователем прекращается; - актуальный список банков — в этом случае взаимодействие с пользователем продолжается. 4. Отображение пользователю списка банков, поддерживающих работу с данным методом и доступных для выбора в рамках новой попытки. 5. Пользователь выбирает один из банков и вводит требуемые данные. 6. Отображение пользователю уведомления о необходимости подтвердить оплату. 7. Пользователь подтверждает проведение оплаты. 8. От Payment Page передаётся запрос на проведение оплаты. 9. В платёжной платформе выполняются обработка запроса и его отправка в платёжную систему. 10. На стороне провайдера выполняется обработка запроса на оплату. 11. От провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. К Payment Page направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для оплаты в сервисе провайдера. 15. На стороне сервиса провайдера выполняется обработка платежа. 16. В сервисе провайдера пользователю отображается информация о результате оплаты. При необходимости пользователь может инициировать новую попытку списания, и тогда цикл начинается с шага 1. В случае выполненного списания средств, проведение платежа завершается. 17. \* От провайдеров, участвовавших в проведении платежа, к платёжной платформе направляются уведомления о результатах обработки каждой попытки проведения оплаты \(операции в рамках платежа\). В зависимости от доступности провайдеров и их скорости обработки запросов возможна задержка \(вплоть до нескольких дней\) в отправке информации о результатах выполнения операций. 18. \* От платёжной платформы к веб-сервису направляются оповещения о результате проведения платежа, но только для тех попыток \(операций\), которые завершились списанием средств. В зависимости от доступности провайдеров и их скорости обработки запросов возможна задержка. 19. \* Пользователю отображается результат оплаты. ### Формат оповещений {#section_bnh_qw4_rjb .section} В платформе Ecommpay каждая дополнительная попытка проведения оплаты технически является отдельной операцией со своим идентификатором \(`operation_id`\), при этом идентификатор платежа \(`payment_id`\) является общим для всех таких операций, поэтому в оповещениях может содержаться информация как о самом платеже, так и об отдельной операции — попытке проведения этого платежа. При каскадном проведении оплат с использованием альтернативных инструментов используются промежуточные и итоговые оповещения стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md), а примеры таких оповещений приведены в описаниях платёжных методов в разделе [Методы](ru_pm_about.md). К особенностям итоговых оповещений в этом случае можно отнести то, что в каждом итоговом оповещении: - сумма платежа указывается с учётом всех списаний, о которых получена информация на момент отправки этого оповещения; - статус *платежа* может быть указан как промежуточный, так и итоговый, даже если статус *операции* указан итоговый. Статус платежа может оставаться промежуточным до нескольких дней либо так и не поменяться на итоговый, не взирая на то, что хотя бы одна попытка выполнена со списанием и взаимодействие с пользователем завершено. Промежуточный статус *платежа* \(как правило, `processing`\) меняется на итоговый, когда в платформу поступают результаты выполнения всех операций, и принимает одно из следующих значений: - `decline`, если итоговые статусы всех операций — `decline`; - `success`, если статус хотя бы одной из операций — `success`. Примеры итоговых оповещений представлены далее. ### Пример каскадного проведения оплаты {#section_u4m_bzj_clb .section} **Общая информация** Чтобы наглядно представлять то, как осуществляется каскадное проведение платежа через Payment Page, приведён пример, отображающий общую картину проведения оплаты с фокусировкой на действиях со стороны пользователя. Для этого в примере представлены изображения платёжных страниц, иллюстрирующих взаимодействие с пользователем. А также представлены примеры данных из итоговых оповещений с информацией о результате платежа. Моменты, на которые стоит обратить внимание в этих оповещениях, выделены комментариями. В рамках данного примера иллюстрируется случай, в котором пользователь выбирает платёжный метод «Банки Малайзии» и делает три попытки проведения оплаты, две из которых завершились списанием средств. В качестве примера может использоваться любой другой платёжный метод. **Первая попытка проведения оплаты** При проведении первой попытки в Payment Page пользователь выбирает банк Hong Leong Bank, перенаправляется к сервису провайдера в отдельном окне, закрывает это окно, не потвердив оплату \(например, из-за недоверия к провайдеру\), и соглашается на дополнительную попытку проведения оплаты. В рамках первой попытки выполняются следующие действия: 1. Инициирование оплаты. Пользователь подтверждает готовность оплатить свой заказ, и далее от веб-сервиса к платёжной платформе отправляется запрос на открытие Payment Page, где пользователь выбирает метод и банк и подтверждает платёж. ![](images/universal/cascade/img_pp_1.png) ![](images/unimethods/cascade/img_pp_2.png) ![](images/unimethods/cascade/img_pp_3.png) 2. Перенаправление к сервису провайдера. Выполняется перенаправление пользователя к сервису провайдера с открытием отдельного окна. Далее в этом примере пользователь закрывает окно, не подтвердив платёж, и возвращается к Payment Page. ![](images/unimethods/cascade/img_pp_4.png) 3. Согласие на выполнение дополнительной попытки проведения оплаты. В связи с тем, что на стороне платёжной платформы не получено ни одно итоговое оповещение об успешном списании, в Payment Page отображается уведомление с предложением повторить оплату. Далее пользователь соглашается, щёлкнув кнопку **Повторить**. ![](images/unimethods/cascade/img_pp_5.png) **Вторая попытка проведения оплаты** В отличие от первой попытки, в данном случае используется другой провайдер, для работы с которым у пользователя запрашиваются дополнительные данные и обновляется список банков, среди которых пользователь выбирает другой банк — Standard Chartered Bank. В сервисе провайдера обработка платежа занимает длительное время, из-за чего пользователь, не дождавшись конца обработки, закрывает окно провайдера, возвращается к Payment Page и соглашается на третью попытку проведения оплаты. При этом результат проведения второй попытки остаётся неизвестным во время проведения третьей. Со стороны пользователя выполнение второй попытки имеет следующий порядок: 1. Выбор банка. Пользователь выбирает банк из обновлённого списка банков. ![](images/unimethods/cascade/img_pp_6.png) 2. Предоставление дополнительных данных. На странице ввода дополнительной информации пользователь вводит необходимые данные и подтверждает платёж. Подробная информация об этой процедуре представлена в разделе [Дополнение информации о платежах](ru_pp_clarification.md). ![](images/unimethods/cascade/img_pp_7.png) ![](images/unimethods/cascade/img_pp_8.png) 3. Перенаправление к сервису провайдера. Выполняется перенаправление пользователя к сервису провайдера с открытием отдельного окна. Далее в этом примере пользователь подтверждает платёж, но, не дождавшись завершения обработки платежа, закрывает окно и возвращается к Payment Page. ![](images/universal/cascade/img_ga_9_pp_9.png) ![](images/unimethods/cascade/img_pp_10.png) 4. Согласие на выполнение дополнительной попытки проведения оплаты. В связи с тем, что на стороне платёжной платформы не получено ни одно итоговое оповещение об успешном списании, в Payment Page отображается уведомление с предложением повторить оплату. Далее пользователь соглашается, щёлкнув кнопку **Повторить**. ![](images/unimethods/cascade/img_pp_11.png) **Третья попытка проведения оплаты** В отличие от предыдущих попыток, в данном случае используется другой провайдер, и для работы с этим провайдером снова необходимо обновляется список банков, среди которых пользователь повторно выбирает банк Hong Leong Bank. В сервисе провайдера пользователь подтверждает платёж, получает информацию о списании средств и возвращается к Payment Page. Со стороны пользователя в рамках третьей попытки выполняются следующие действия: 1. Выбор банка. Пользователь выбирает банк из обновлённого списка банков и подтверждает платёж. ![](images/unimethods/cascade/img_pp_12.png) 2. Перенаправление к сервису провайдера. Выполняется перенаправление пользователя к сервису провайдера с открытием отдельного окна. Далее в этом примере пользователь подтверждает платёж и, получив информацию о списании средств, возвращается к Payment Page. ![](images/universal/cascade/img_ga_14_pp_13.png) ![](images/universal/cascade/img_ga_15_pp_14.png) **Обработка результатов платежа** От платёжной платформы к веб-сервису отправляются оповещения о результате платежа при выполнении каждого списания. В этом примере в рамках третьей попытки обработка платежа и списание средств выполняются без ощутимых задержек на стороне провайдера, поэтому от платёжной платформы к веб-сервису без задержек отправляется итоговое оповещение и информация о результате отображается пользователю в Payment Page. Затем, например спустя несколько часов, когда обработка второй попытки на стороне другого провайдера завершается списанием, от платёжной платформы к веб-сервису отправляется ещё одно итоговое оповещение. В этом оповещении, в отличие от первого, сумма платежа указывается с учётом обоих списаний. В этом случае на усмотрение пользователя можно провести возврат средств. На стороне веб-сервиса в контексте данного примера выполняются следущие действия: 1. Приём оповещения о результате третьей попытки. От платёжной платформы к веб-сервису отправляется оповещение об успешном списании средств. Так как на момент отправки этого оповещения результат по крайней мере одной попытки остаётся неизвестным, платёж остаётся в статусе `processing`, однако для текущей попытки \(операции\) указывается статус `success`. А также эта информация отображается пользователя на странице о результате платежа. ![](images/unimethods/cascade/img_pp_15.png) ```language-java { "customer": { "id": "653" }, "project_id": 200, "payment": { // информация о платеже (оплате) "payment_id": "cosmo_set_4589", // идентификатор платежа, одинаковый для всех попыток, "type": "purchase", "status": "processing", // статус платежа "date": "2020-07-20T04:37:57+0000", "method": "Malaysian banks", "sum": { "amount": 131970, // сумма платежа с учётом одного списания "currency": "MYR" }, "description": "Gagarin set" }, "operation": { // информация об операции (попытке проведения оплаты) "id": 003, // идентификатор операциии в платёжной платформе "type": "sale", "status": "success", "date": "2020-07-20T04:37:57+0000", "created_date": "2020-07-20T04:36:45+0000", "request_id": "cosmo_set_4589_request3", // идентификатор запроса,полученный в ответе // на запрос на выполнение третьей попытки проведения оплаты "sum_initial": { "amount": 131970, //сумма списания в рамках третьей попытки "currency": "MYR" }, "sum_converted": { "amount": 131970, "currency": "MYR" }, "code": "0", "message": "Success", "provider": { // информация о провайдере, обработавшем платёж "id": 1256, "payment_id": "064604207", // идентификатор платежа, заданный на стороне провайдера "auth_code": "", "date": "2020-07-20T04:36:51+0000" } }, "signature": "n3zmkj5yG..." } ``` 2. Приём итогового оповещения о результате второй попытки. Спустя продолжительное время с момента начала проведения платежа от платёжной платформы к веб-сервису отправляется ещё одно итоговое оповещение. Так как на момент отправки этого оповещения результаты всех попыток становятся известными и по крайней мере одна из попыток завершилась списанием, статус платежа меняется на итоговый — `success`, а также сумма платежа указывается с учётом двойного списания. ```language-java { "customer": { "id": "653" }, "project_id": 200, "payment": { // информация о платеже (оплате) "payment_id": "cosmo_set_4589", // идентификатор платежа, одинаковый для всех попыток, "type": "purchase", "status": "success",// статус платежа "date": "2020-07-20T07:12:04+0000", "method": "Malaysian banks", "sum": { "amount": 263940, // сумма платежа с учётом двойного списания "currency": "MYR" }, "description": "Gagarin set" }, "operation":{ // информация об операции (попытке проведения оплаты) "id": 002, // идентификатор операциии в платёжной платформе "type": "sale", "status": "success", "date": "2020-07-20T07:12:04+0000", "created_date": "2020-07-20T04:33:37+0000", "request_id": "cosmo_set_4589_request2", // идентификатор запроса,полученный в ответе // на запрос на выполнение третьей попытки проведения оплаты "sum_initial": { "amount": 131970, // сумма списания в рамках второй попытки "currency": "MYR" }, "sum_converted": { "amount": 131970, "currency": "MYR" }, "code": "0", "message": "Success", "provider": { // информация о провайдере, обработавшем платёж "id": 1589, "payment_id": "0757821", // идентификатор платежа, заданный на стороне провайдера "auth_code": "", "date": "2020-07-20T07:11:48+0000" } }, "signature": "bYNjg..." } ``` --- # Сбор данных о пользователях {#ru_PP_Gathering_customer_data .concept} статья о возможности получать и использовать при работе с Payment Page дополнительную информацию о пользователях, позволяющую минимизировать применение вспомогательных процедур ## Общая информация {#section_ivk_bpf_gdb .section} В некоторых случаях вместе с обязательными данными для проведения платежа актуально запрашивать у пользователей и дополнительные, например номера их телефонов и адреса электронной почты. Такие данные могут быть полезны для решения разных задач и позволяют, в частности: - обеспечивать дополнительный уровень безопасности за счёт сбора и проверки сведений о пользователях; - улучшать пользовательские сценарии за счёт избежания процедуры дополнения информации о платеже \(когда при проведении платежа со стороны платёжныхпровайдеров, системили банков запрашиваются дополнительные данные, [подробнее](ru_pp_clarification.md)\). Возможность собирать дополнительные данные обеспечивается непосредственно в платёжной форме Payment Page, а также, при работе с отдельными платёжными методами, в используемых платёжных сервисах \(таких, как Apple Pay\).Следует учитывать, что сбор дополнительных данных увеличивает количество требуемых от пользователя действий для проведения платежа и может негативно влиять на конверсию платёжной формы, поэтому такую возможность рекомендуется использовать только при явной необходимости. Зачастую лучшим решением является передача уже имеющейся информации о пользователях в запросах на открытие Payment Page. Для работы с дополнительными данными, указанными пользователями в платёжной форме или сторонних сервисах, можно использовать карточки платежей в интерфейсе Dashboard и итоговые оповещения о выполнении операций. Чтобы настроить передачу дополнительных данных в оповещениях, следует обратиться к специалистам технической поддержки Ecommpay. ## Пользовательские сценарии {#section_wks_zfs_jsb .section} Для сбора дополнительных данных в платёжной форме используются соответствующие поля. Эти поля могут отображаться во всех случаях или только при необходимости и могут быть обязательными и необязательными для заполнения. Также могут отличаться варианты размещения дополнительных полей: они могут отображаться на странице указания реквизитов платёжного инструмента или следующей за ней отдельной странице \(с учётом общего количества полей\). Конкретный вариант отображения каждого дополнительного поля определяется исходя из набора его свойств и состава данных в запросе на открытие Payment Page, при этом допустимы следующие варианты: - `1` — поле отображается с предварительно заполненным значением, указанным в запросе, и пользователь может изменить это значение; - `2` — поле отображается без значения, но с его названием; - `3` — поле не отображается, значение параметра может быть передано в платёжную платформу только через запрос. ![](images/ecommpay/ru_pp_gathering_customer_data.svg "Варианты отображения дополнительных полей") Выбор варианта отображения осуществляется следующим образом. |Обязательность указания данных|+|+|+|+|–|–|–|–| |Обязательность отображения поля|+|+|–|–|+|+|–|–| |Передача значения в запросе|+|–|+|–|+|–|+|–| |**Вариант отображения поля**|**`1`**|**`2`**|**`3`**|**`2`**|**`1`**|**`2`**|**`3`**|**`3`**| Для сбора дополнительных данных в сторонних сервисах, таких как сервисы Apple Pay и Google Pay, используются интерфейсы этих сервисов. С учётом их специфики при запросе данных от пользователей могут использоваться, например, ранее сохранённые пользователями сведения и другие особенности взаимодействия. При этом запрошенные сведения во всех случаях являются обязательными к заполнению, а для запроса сведений могут использоваться как свойства проекта, так и параметры отдельных запросов. Так, в каких-то случаях можно настроить сбор адресов электронной почты пользователей во всех случаях через свойства проекта и сбор других сведений только при необходимости, через параметры запросов \(подробнее — в статьях о работе с методами [Apple Pay](pm_applepay.md) и [Google Pay](pm_googlepay.md)\). Собранные таким образом данные могут передаваться к веб-сервису мерчанта в оповещениях о результатах платежей. Для этого необходимо обратиться в службу технической поддержки Ecommpay. ## Подключение {#section_ts1_3sf_gdb .section} Чтобы подключить возможность сбора дополнительных данных о пользователях, со стороны мерчанта необходимо: 1. Определить, для каких проектови каких платёжных методов по этим проектам актуально собирать дополнительные данные. И для каждого такого случая определить набор запрашиваемых данных и свойства соответствующих полей. В состав данных могут включаться различные параметры \(подробнее — [далее](ru_PP_Gathering_customer_data.md#section_jdb_1qx_tdb)\), а к свойствам каждого из требуемых полей относятся: - Обязательность заполнения и отображения. - Способ указания: через ввод с клавиатуры или через выбор из выпадающего списка. Чтобы использовать выпадающий список для конкретного параметра, например *названия страны*, необходимо сообщить все его возможные значения специалистам технической поддержки или согласовать использование значений из справочников, предоставляемых Ecommpay. - Название: по умолчанию используются типовые названия, предоставляемые Ecommpay, но можно задать и индивидуальные. При добавлении индивидуальных названий со стороны мерчанта также может понадобиться предоставить специалистам технической поддержки их перевод на все языки, актуальные в рамках проекта. 2. Передать специалистам технической поддержки информацию обо всех данных, которые требуется запрашивать у пользователей, а также информацию о том, необходимо ли получать данные, указанные пользователями в платёжной форме, в итоговых оповещениях о проведении платежей. 3. Получить от специалистов Ecommpay уведомление о подключении запрашиваемой функциональности и, при необходимости, проверить работу платёжной формы с её использованием. ## Запрашиваемые данные {#section_jdb_1qx_tdb .section} Для сбора данных о пользователях могут использоваться следующие параметры. |Параметр|Описание| |--------|--------| |customer\_address string |Название улицы и номер дома \(с обозначением корпуса или строения, где это актуально\) в адресе проживания пользователя, с использованием разделительной запятой. Представляет собой строку длиной не более 255 символов. Пример: `улица Дукшту, 30` | |customer\_birthplace string |Место рождения пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Рига` | |customer\_city string |Название города проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Вильнюс` | |customer\_country string |Код страны проживания пользователя в формате ISO 3166-1 alpha-2. Пример: `LT` | |customer\_day\_of\_birth string |Дата рождения пользователя в формате `ДД-ММ-ГГГГ`. Пример: `17-04-1989` | |customer\_email string |Адрес электронной почты пользователя. Представляет собой строку длиной не более 255 символов, состоящую из двух частей: имени пользователя и доменного имени, разделённых символом «@». Пример: `sonya@example.com` | |customer\_first\_name string |Имя пользователя. Представляет собой строку не более 255 символов. Пример: `Софья` | |customer\_last\_name string |Фамилия пользователя. Представляет собой строку не более 255 символов. Пример: `Ковалевская` | |customer\_middle\_name string |Отчество пользователя. Представляет собой строку не более 255 символов. Пример: `Васильевна` | |customer\_phone string |Полный номер телефона пользователя, с кодом страны. Должен содержать не менее 4 и не более 24 цифр, при этом, если такое допускается в рамках используемого проекта и платёжного метода, в записи номера могут использоваться знаки пунктуации и специальные символы \(подобные случаи, как правило, оговариваются отдельно\). Пример: `44997654321` | |customer\_ssn integer |Последние 4 цифры номера социального страхования налогоплательщика в США. Пример: `1312` | |customer\_state string |Название региона \(штата\) адреса проживания пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Вильнюсский уезд` | |customer\_zip string |Почтовый индекс адреса проживания пользователя. Представляет собой строку длиной не более 10 символов. Пример: `LT-071171` | |billing\_address string |Название улицы расчётного адреса пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Дукшту` | |billing\_city string |Название города расчётного адреса пользователя. Представляет собой строку  длиной не более 255 символов. Пример: `Вильнюс` | |billing\_country string |Код страны расчётного адреса пользователя в формате ISO 3166-1 alpha-2. Пример: `LT` | |billing\_postal string |Почтовый индекс расчётного адреса пользователя. Представляет собой строку длиной не более 16 символов. Пример: `LT-071171` | |billing\_region string |Название региона расчётного адреса пользователя. Представляет собой строку длиной не более 255 символов. Пример: `Вильнюсский уезд` | |billing\_region\_code string |Код региона расчётного адреса пользователя в формате ISO 3166-2. Пример: `VL` | Использование дополнительных параметров, не представленных в таблице, можно согласовывать со специалистами Ecommpay. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Управление языком платёжной формы {#ru_PP_WigetLanguages .concept} статья о возможностях задавать язык, используемый при отображении платёжной формы ## Общая информация {#section_xvl_zxc_dbb .section} Неотъемлемой частью пользовательского интерфейса Payment Page являются текстовые элементы: различные названия \(полей, кнопок и других составляющих\), подсказки и сообщения \(в том числе об ошибках\). Эти элементы обеспечивают полноту и понятность интерфейса и могут существенно влиять на пользовательский опыт и конверсию платёжной формы. ![](images/ecommpay/pp_wigetlanguages_1.svg) ## Возможности {#section_asl_ngx_nqb .section} Чтобы тексты эффективно работали в платёжной форме Payment Page, специалисты Ecommpay тщательно подбирают формулировки на разных языках и обеспечивают возможность использования любого языка из регулярно расширяемого [базового набора](ru_PP_WigetLanguages.md#section_qq2_xp5_p4b), а в самой форме поддерживается возможность выбора любого из доступных языков пользователем. Вместе с тем, для разных мерчантов могут быть актуальны разные нюансы, и для того, чтобы адаптировать Payment Page к специфике конкретного проекта, со стороны мерчанта можно согласовывать с курирующим менеджером Ecommpay возможности расширения списка доступных языков и указывать языки, актуальные для конкретных вызовов платёжной формы\(например, с учётом предпочтений пользователя при работе с веб-сервисом\). ![](images/ecommpay/pp_wigetlanguages_2.svg "Использование возможности смены языка") Помимо настройки управления языками для адаптации платёжной формы к специфике конкретного проекта может быть актуальной и настройка её оформления \(с помощью соответствующего [конструктора](ru_PP__design_customisation.md)\). ## Порядок работы {#section_hhb_qgx_nqb .section} Платёжная форма при каждом вызове открывается с возможностью смены языка пользователем на любой из базового набора и с исходным использованием следующего языка \(в порядке убывания приоритета\): 1. Языкотображения платёжной формы, указанный при еёвызове \([подробнее](ru_PP_WigetLanguages.md#section_bb1_jft_kqb)\), если он поддерживается для используемого проекта, а если этот язык не поддерживается — язык по умолчанию \(английский\). 2. Язык браузера пользователя, если его удалось определить\(через свойства браузера\) и он поддерживается для используемого проекта. 3. Английский как язык по умолчанию. ## Указание языка при вызове формы {#section_bb1_jft_kqb .section} Чтобы задать язык отображения платёжной формы для конкретного сеанса, при вызове формы необходимо передать код этого языка в параметре `language_code`. В платёжной платформе используются коды, соответствующие формату alpha-2 стандарта [ISO 639-1](https://www.iso.org/ru/iso-639-language-codes.html), и согласованные с мерчантами коды для тех языков, которые не входят в этот стандарт.Также стоит учитывать, что заданный при вызове формы язык используется и для формирования дополнительных уведомлений о событиях, связанных с этим платежом \(если для проекта подключена соответствующая возможность; [подробнее](ru_gate_receipts.md)\). ``` {#codeblock_u1r_b5d_4jc .language-json} { "project_id": 93211, "payment_id": "423289", "payment_currency": "EUR", "payment_amount": 131970, "customer_id": "customer_772", "language_code": "de", // код языка "signature": "TSzdE5rJZaA9TYAWEKoGpfXriFf82MxF..." } ``` При таком способе задания языка он применяется для открытия платёжной формы и для формирования последующих [уведомлений](ru_PP_receipt_data.md) \(если они актуальны\), однако если указанный язык не входит в рабочий набор языков проекта, то вместо него используется английский. ## Базовый набор языков {#section_qq2_xp5_p4b .section} Ecommpay обеспечивает работу платёжной формы с использованием следующих языков. |Язык|Код| |----|---| |Английский|`en`| |Испанский|`es`| |Итальянский|`it`| |Латышский|`lv`| |Литовский|`lt`| |Немецкий|`de`| |Португальский|`pt`| |Русский|`ru`| |Украинский|`uk`| |Французский|`fr`| |Эстонский|`et`| **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Предварительный выбор платёжных методов {#ru_PP__PreselectingPS .concept} статья о возможности задавать конкретный платёжный метод при вызове платёжной формы ## Общая информация {#section_cf5_jxk_ymb .section} По умолчанию работа пользователя с Payment Page начинается со страницы выбора платёжного метода, но в некоторых случаях нет необходимости отображать эту страницу. Например, когда пользователь выбирает метод в веб-сервисе мерчанта до открытия Payment Page или когда со стороны мерчанта по каким-либо причинам \(с учётом специфики региона, пользователя или иных факторов\) актуально использовать конкретный платёжный метод. Для работы с такими ситуациями в платёжной платформе Ecommpay предусмотрена возможность открытия Payment Page с учётом предварительно выбранного \(пользователем или мерчантом\) метода, минуя выбор метода в платёжной форме. Выбранный метод в таких случаях указывается в запросе на открытие Payment Page, и для подключения этой возможности не требуется никаких дополнительных действий. ![](images/ecommpay/ru_pp_preselectingps_1.svg "Базовый сценарий — с выбором метода в платёжной форме") ![](images/ecommpay/ru_pp_preselectingps_2.svg "Дополненный сценарий — с выбором метода до открытия платёжной формы") Вместе с выбором метода в некоторых случаяхмогут использоваться и другие возможности, актуальные для конкретного метода ивлияющие на сценарии работы Payment Page. К таким возможностям, в частности, относятся: - *Отображение сохранённых данных определённой платёжной системы.* Для оплаты с прямым использованием карт можно ограничивать выбор карт, данные которых были сохранены пользователем. В таком случае в запросе на открытие Payment Page указывается идентификатор предпочтительной платёжной системы \(например, Mastercard или Visa\), в результате чего первой пользователю отображается страница выбора платёжной карты с данными карт указанной платёжной системы. Если таких данных нет или среди представленных карт нет подходящих, то пользователь может указать данные другой карты, в том числе другой платёжной системы. ![](images/ecommpay/ru_pp_preselectingps_3.svg) - *Предварительный выбор банка*. Для некоторых методов интернет-банкинга, например [Indonesian Online Banking](pm_indonesia.md), предварительно можно указывать конкретный банк, поддерживающий оплату с использованием этого метода. В таком случае перенаправление пользователя осуществляется напрямую на сайт банка, минуя страницы с выбором платёжного метода и выбором банка.Информация о таких возможностях, специфичных для отдельных методов, представлена в описании этих методов в разделе [Методы](ru_pm_about.md). - *Предварительный выбор группы методов*. Некоторые методы, например [Open Banking in Germany](pm_germany.md), входят в группы, идентификаторы которых можно указывать при отправке запроса на открытие Payment Page. В таком случае пользователю отображаются кнопки выбора только тех методов, которые входят в указанную группу и доступны в рамках используемого проекта. Наконец, помимо выбора конкретного метода в некоторых ситуациях может быть актуальна фильтрация платёжных методов, отображаемых пользователю в платёжной форме. Эта возможность описана [в отдельной статье](ru_pp_methods_availability.md). ## Особенности {#section_h5k_t1n_b4b .section} При работе с предварительным выбором платёжных методов необходимо учитывать следующие особенности: - в качестве предварительно выбранного может указываться один из методов, доступных в рамках используемого проекта, иначе запрос отклоняется; - пользователю не предоставляется возможность выбрать другой метод, кроме указанного при вызове Payment Page, в том числе и при выполнении всех [повторных попыток](ru_PP_Try_Again.md) в рамках платежа; - при одновременном указании в запросе метода и токена платёжных данных платёж проводится с использованием токена, а информация о платёжном методе игнорируется. ## Формат запросов {#section_a4b_vxk_ymb .section} Для указания платёжного метода в запросе на открытие Payment Page необходимо передавать код этого метода в параметре `force_payment_method`, для указания группы методов — код этой группы в параметре `force_payment_group`. Коды поддерживаемых методови групп представлены [в отдельном справочнике](ru_pm_codes.md). В следующем примере для проведения оплаты указан метод Alipay. ``` { .language-json .show_more} { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "force_payment_method": "alipay", // код платёжного метода "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ```language-json { "project_id": 42, "payment_id": "456789", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "force_payment_method": "alipay", // код платёжного метода "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` Чтобы указать предпочтительную платёжную систему для оплаты с прямым использованием карты, в запросе на открытие Payment Page необходимо указать код платёжного метода `card` в параметре `force_payment_method` и идентификатор платёжной системы в параметре `force_payment_method_subtype`. Используемые идентификаторы платёжных систем представлены [в отдельном справочнике](ru_card_codes.md). В следующем примере в качестве предпочтительной указана платёжная система Mastercard. ``` { .language-json .show_more} { "project_id": 43, "payment_id": "456790", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "force_payment_method": "card", // код платёжного метода "force_payment_method_subtype": "mastercard", // идентификатор платёжной системы "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ```language-json { "project_id": 43, "payment_id": "456790", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "force_payment_method": "card", // код платёжного метода "force_payment_method_subtype": "mastercard", // идентификатор платёжной системы "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ## Дополнительные материалы {#section_dr1_mc2_hpb .section} При работе с предварительным выбором платёжных методов могут быть полезны следующие материалы: - [Коды платёжных методов](ru_pm_codes.md)— справочный раздел с кодами поддерживаемых платёжных методов. - [Коды брендов платёжных карт](ru_card_codes.md)— справочный раздел с идентификаторами поддерживаемых платёжных систем. - [Фильтрация платёжных методов](ru_pp_methods_availability.md)— раздел с информацией об ограничении списка платёжных методов для конкретного платежа. - [Методы](ru_pm_about.md)— раздел с информацией о платёжных методах и работе с ними. - [Спецификация Payment Page API](ru_PP_Parameters.md)— раздел с описанием параметров вызова Payment Page. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Фильтрация платёжных методов {#ru_pp_methods_availability} статья о возможности управлять наборами платёжных методов, актуальными для конкретных вызовов платёжной формы **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) ## Общая информация {#ru_pp_availability_info} При проведении платежей с использованием платёжной формы Payment Page пользователю по умолчанию предоставляется возможность выбрать любой из платёжных методов, доступных в рамках используемого проектаи поддерживаемых для выполнения целевого действия. Как правило, для одного проекта подключается относительно небольшое число методов, и их полный перечень не перегружает форму, а пользователь может быстро выбрать наиболее удобный для него способ оплаты. В типовых ситуациях такой подход обеспечивает хороший пользовательский опыт и высокую конверсию. Вместе с тем, в некоторых ситуациях — с учётом специфики проекта и используемых методов и валют — для улучшения пользовательского опыта может быть полезным фильтровать методы, предоставляя для выбора только часть из них. ![](images/ecommpay/ru_pp_methods_availability_1.svg "Возможные ситуации с выбором платёжного метода: в типовом случае, при обилии подключённых методов и при фильтрации методов") Для гибкой адаптации к различным ситуациям в платформе предусмотрены разные способы фильтрации методов. Это: - *Директивная фильтрация* — с прямым указанием со стороны веб-сервиса тех методов, которые следует исключить из выбора в рамках конкретного вызова платёжной формы. При этом способе фильтруемые методы каждый раз определяются на стороне веб-сервиса и указываются в запросе на открытие Payment Page \(в значении параметра `hide`\), в то время как в платформе обрабатывается указание скрыть эти методы из выбора. - *Параметрическая фильтрация* — с автоматическим исключением на стороне платформы тех методов, которые не относятся к актуальным для страны пользователя или валюты конкретного платежа. При этом способе изначально настраивается, что должно использоваться в качестве параметра фильтрации и какие допущения по выбору методов для разных стран актуальны для конкретного проекта \(с учётом специфики разных проектов такая настройка может быть довольно гибкой\). После настройки и подключения параметрической фильтрации фильтруемые методы каждый раз определяются на стороне платформы в соответствии с алгоритмами её работы и значением выбранного параметра — страны или валюты. - *Комбинированная фильтрация* — с комбинированием возможностей директивной и параметрической фильтрации. При этом способе из числа доступных методов каждый раз исключаются и автоматически отфильтрованные по заданному параметру, и директивно указанные в запросе. Каждый из этих способов может быть эффективным в определённых ситуациях, в частности, чтобы избегать конвертации валют и отклонения платежей в тех случаях, когда указанная в запросе валюта платежа отличается от валют, поддерживаемых для выбранного пользователем метода. Вместе с тем, важно учитывать, что чрезмерная фильтрация может лишать пользователей возможностей оплаты удобными для них способами и приводить к снижению конверсии. Чтобы избегать таких проблем и эффективно применять фильтрацию там, где она действительно уместна \(например, при работе в некоторых специфичных регионах или при использовании специфических сценариев работы\), следует обсуждать актуальные задачи и способы фильтрации с курирующим менеджером Ecommpay и внимательно анализировать предпочтения и затруднения своих пользователей.Также в некоторых случаях вместе с фильтрацией платёжных методов или даже вместо неё может быть эффективным настроить их [ранжирование](ru_pp_methods_order.md). ## Директивная фильтрация {#ru_pp_directive_methods_avalability} ### Общая информация {#ru_pp_directive_methods_avalability_info} *Директивная фильтрация* позволяет исключать из выбора платёжные методы, доступные в рамках используемого проекта, но неактуальные для конкретного платежа\(с учётом специфики региона, пользователя или иных факторов\). При использовании такой фильтрации на странице выбора платёжного метода пользователю отображаются все доступные методы, за исключением скрытых. ![](images/ecommpay/ru_pp_methods_availability_2.svg "Возможные ситуации с выбором платёжного метода: без фильтрации и с фильтрацией") Вместе с тем, когда для проведения платежа актуален только один платёжный метод или платёжные методы одной группы, может быть уместнее использовать возможность предварительного выбора соответствующих метода или группы \([подробнее](ru_PP__PreselectingPS.md)\). ### Подключение {#ru_pp_directive_methods_availability_enable} Директивная фильтрация доступна по умолчанию, и для её подключения в рамках тестовых и рабочих проектов с использованием Payment Page не требуется никаких действий. ### Использование {#ru_pp_directive_methods_avalability_request} Чтобы директивно скрыть определённые методы в рамках конкретного сеанса работы Payment Page, в запросе на открытие Payment Page необходимо передать параметр `hide` с кодами этих методов \(согласно [справочнику](ru_pm_codes.md)\) и с использованием запятой в качестве разделителя, если это актуально. При этом используются те же коды, что и для предварительного выбора методов, однако это не относится к кодам для предварительного выбора групп методов: скрывать группы методов допускается лишь через указание каждого из этих методов, но не через указание группы. При использовании директивной фильтрации стоит учитывать следующие особенности и ограничения: - если для проекта доступен лишь один метод и он указан в параметре `hide`, во избежание ошибки вызова значение этого параметра игнорируется и платёжная форма открывается без применения директивной фильтрации; - если для проекта доступно более одного метода и все они указаны в параметре `hide`, платёжная форма открывается с ошибкой, без возможности выбрать какой-либо метод; - при указании одного и того же метода в качестве скрываемого \(в значении параметра `hide`\) и предварительно выбранного \(в значении параметра `force_payment_method`, [подробнее](ru_PP__PreselectingPS.md)\) платёжная форма открывается с ошибкой, без возможности выбрать какой-либо метод. В следующем примере из числа доступных для проведения платежа исключаются методы WeChat и Alipay. ``` {#codeblock_nlv_lb5_sdc .language-json} { "project_id": 43, "payment_id": "456790", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "hide": "wechat, alipay", // коды скрываемых платёжных методов "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF..." } ``` ## Параметрическая фильтрация {#ru_pp_parameters_methods_availability} ### Общая информация {#ru_pp_parameters_methods_availability_info} *Параметрическая фильтрация* позволяет автоматически исключать из выбора платёжные методы, доступные в рамках используемого проекта, но неактуальные для страны или валюты конкретного платежа. При использовании такой фильтрации на странице выбора платёжного метода пользователю отображаются только те методы, которые актуальны с учётом контекста. Так, если в рамках используемого проекта настроена фильтрация по валюте и в общем случае доступны классические карточные платежи, методы [Blik](pm_blik.md), [Open Banking in the UK](pm_uk.md) и [Open Banking in Germany](pm_germany.md), а в запросе на открытие Payment Page указан польский злотый \(`PLN`\), то пользователю будут доступны для выбора только карточные платежи и метод [Blik](pm_blik.md). ![](images/ecommpay/ru_pp_methods_availability_3.svg "Возможные ситуации с выбором платёжного метода: без фильтрации и с фильтрацией") Со стороны мерчанта можно выбрать, по какому параметру \(стране или валюте\) выполнять такую фильтрацию и как фильтровать отдельные методы с учётом их особенностей и специфики веб-сервиса, и настроить соответствующим образом фильтрацию при её подключении. В остальном после подключения параметрической фильтрации никаких действий со стороны мерчанта не требуется. ### Подключение {#ru_pp_parameters_methods_availability_enable} Чтобы подключить параметрическую фильтрацию, со стороны мерчанта следует: 1. Определить: для каких проектов актуален такой способ фильтрации, что следует использовать в качестве параметра фильтрации\(страну пользователя или валюту платежа\) и есть ли потребности в настройке исключений и особых правил фильтрации для отдельных методов. При необходимости на этом шаге можно консультироваться с курирующим менеджером Ecommpay. 2. Передать специалистам технической поддержки Ecommpay информацию потребностях в настройке параметрической фильтрации и согласовать с ними сроки подключения и потребности в тестировании этой функциональности. 3. Получить от специалистов Ecommpay уведомление о подключении запрошенной функциональности и, при необходимости, проверить работу платёжной формы с её использованием. ### Использование {#ru_pp_parameters_methods_availability_use} После подключения параметрической фильтрации *по валюте* никаких дополнительных действий со стороны веб-сервиса не требуется, поскольку валюта платежа \(в значении параметра `payment_currency`\) относится к обязательным параметрам вызова Payment Page и фильтрация по этому параметру выполняется автоматически. После подключения параметрической фильтрации *по стране* со стороны веб-сервиса можно настроить передачу в запросах на открытие Payment Page актуальных кодов стран пользователей \(в значении параметра `region_code`; согласно [справочнику](ru_country_codes.md)\). При передаче таких кодов фильтрация по стране выполняется автоматически с их учётом, а если их не передавать, то с учётом стран, определяемых по IP-адресам пользовательских устройств. ## Дополнительные материалы {#ru_pp_methods_avalability_add_info} При работе с возможностями фильтрации платёжных методов могут быть полезны следующие материалы: - [Ранжирование платёжных методов](ru_pp_methods_order.md)— статья с информацией о возможности применения ранжирования платёжных методов. - [Предварительный выбор платёжных методов](ru_PP__PreselectingPS.md)— статья с информацией о возможности задавать при вызове Payment Page конкретный метод для проведения платежа. - [Коды платёжных методов](ru_pm_codes.md)— справочник с кодами поддерживаемых платёжных методов. - [Методы](ru_pm_about.md)— раздел с информацией о платёжных методах и работе с ними. - [Коды стран](ru_country_codes.md) — справочник с буквенными кодами стран. - [Спецификация Payment Page API](ru_PP_Parameters.md)— спецификация параметров вызова Payment Page. --- # Ранжирование платёжных методов {#ru_pp_methods_order} статья о возможностях ранжировать платёжные методы, чтобы представлять их пользователям в платёжной форме в оптимальном порядке ## Общая информация {#section_bgy_ply_sxb .section} При проведении платежей с использованием платёжной формы Payment Page кнопки выбора платёжных методов могут отображаться с применением *динамического* или *статического* ранжирования. По умолчанию используется динамическое ранжирование, в рамках которого методы выстраиваются в соответствии с тем, насколько подходящими они считаются для конкретного вызова платёжной формы. При этом учитываются: - местоположение пользователя, - тип бизнеса мерчанта, - частота выбора разных методов в рамках используемого проекта. **Прим.:** Можно отметить, что при использовании мобильных SDK методы ранжируются на основе информации, полученной при использовании мобильных устройств, а в остальных случаях — на основе информации, полученной при использовании всех устройств, кроме мобильных. Вместе с тем, можно использовать статическое ранжирование с заданным порядком отображения методов\(например, по алфавиту\). Для подключения и настройки этого варианта следует обращаться в службу технической поддержки. ## Примеры работы {#section_grh_qly_sxb .section} Чтобы сопоставить варианты ранжирования, можно рассмотреть несколько случаев. - Если пользователь из Португалии делает заказ на сайте мерчанта, который ведёт бизнес в нескольких странах Европы, то при применении динамического ранжирования методы выстраиваются от более актуальных в Португалии для типа бизнеса этого мерчанта и конкретного проекта \(Multibanco и Open Banking in Portugal\) к менее актуальным \(Astropay, Open Banking in France\). - Если на сайте этого же мерчанта делает заказ пользователь из Франции, методы выстраиваются от более актуальных во Франции для типа бизнеса этого мерчанта и конкретного проекта \(Open Banking in France, Google Pay\) к менее актуальным \(Astropay, Open banking in Portugal, Multibanco\). - В случае статического ранжирования для обоих указанных заказов методы выстраиваются в одном порядке. ![](images/ecommpay/pp_methods_order_1.svg "Динамическое ранжирование для вызова из Португалии") ![](images/ecommpay/pp_methods_order_2.svg "Динамическое ранжирование для вызова из Франции") ![](images/ecommpay/pp_methods_order_3.svg "Статическое ранжирование") **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Сохранение платёжных данных пользователей {#ru_PP_saved_data .concept} статья о возможностях сохранять и использовать платёжные данные пользователей при работе с платёжной формой Для улучшения пользовательских сценариев при работе с Payment Page предусмотрена возможность сохранять платёжные данные и в дальнейшем использовать их без необходимости повторного ввода. В рамках этой возможности платёжные данные могут быть сохранены при проведении оплат и проверке действительности платёжных инструментов. Сохранённые данные отображаются в платёжной форме на странице выбора способа оплаты вместе с данными платёжных карт, на основании которых выполнялось формирование токенов. Payment Page поддерживает следующие варианты сохранения платёжных данных: - всегда сохранять введённые платёжные данные пользователя; - никогда не сохранять платёжные данные пользователя; - запрашивать пользователя о сохранении данных. Дополнительно можно ограничить максимальное количество платёжных инструментов, которые может сохранить пользователь. При необходимости пользователь может самостоятельно удалить сохранённые платежные инструменты в Payment Page. В случае, если пользователь удалил сохранённую карту, по которой зарегистрированы подписки на проведение повторяемых оплат, списание средств не остановится. Подробная информация об отмене проведения повторяемых оплат представлена в разделе [Регистрация повторяемых оплат](ru_pp_recurring.md). **Прим.:** Для включения и настройки функциональности свяжитесь со службой технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Проведение оплат по токенам {#ru_PP_Payment_by_token .concept} статья о возможности применять в работе с Payment Page токены платёжных данных для сокращения пользовательских платёжных сценариев Payment Page поддерживает проведение быстрых платежей по токенам банковских карт. Запрашивая открытие платежной страницы, вы передаете токен банковской карты, и пользователю генерируется платежная страница с предвыбранной картой и заполненными данными этой карты, кроме CVV. Пользователь вводит только CVV и подтверждает сумму платежа. **Прим.:** При проведении оплаты по токену пользователь не сможет выбрать другую банковскую картуили иной платежный аккаунт. ![](images/ecommpay/ru_pp_payment_by_token.svg "Открытие платежной страницы при проведении оплаты по токену") **Прим.:** Проведение оплат по токенам доступно в режиме Purchase. **Прим.:** Для включения и настройки функциональности свяжитесь со службой технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). ## Передаваемые параметры {#section_wpx_yfk_5bb .section} Для проведения оплаты по токену передайте токен банковской карты в параметре account\_token, а также идентификатор пользователя в параметре customer\_id. Полный список параметров, поддерживаемых Payment Page, приведен в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Конвертация валют {#ru_pp_currency_conversion} статья о возможностях проводить через Payment Page платежи с применением разных валют и встроенной в этот процесс конвертацией ## Введение {#section_whs_hw2_ngc .section} Платёжная платформа Ecommpay позволяет проводить платежи с использованием разнообразных валют и автоматической конвертацией, то есть пересчётом актуальных сумм из одних валют в другие, когда это необходимо. При этом для оптимизации и удобства работыможно гибко настраивать различные возможности: - для оперирования разными валютами на стороне мерчанта можно настраивать соответствующие [балансы](ru_glossary.md); - для поддержки разных операционных валют можно настраивать соответствующие платёжные [методы](ru_glossary.md) и [каналы](ru_glossary.md); - для удобства пользователей можно предоставлять им возможности выбора валют в веб-сервисе и в платёжной форме Payment Page \([подробнее](ru_pp_currency_choice.md)\). В отношении каждой из этих возможностей могут быть применимы различные ограничения, связанные с условиями работы партнёров и провайдеров, региональными особенностями и другими факторами. Тем не менее, даже с учётом ограничений в большинстве случаев можно гибко адаптировать сервис к специфике бизнеса и эффективно использовать в работе локальные и глобальные валюты.С вопросами о настройке и использовании таких возможностей можно обращаться к этой и другим статьям документации, а также к курирующему менеджеру Ecommpay. ## Варианты конвертации {#section_sxy_3y2_ngc .section} При проведении любого платежа через платформу Ecommpay задействуются четыре валюты: - *запрошенная операционная валюта*, изначально указанная со стороны мерчанта в запросена проведение платежа; - *фактическая операционная валюта*, выбранная в платформедля проведения платежа с учётом разных факторов; - *пользовательская валюта*, в которой ведётся баланс платёжного инструмента пользователя, применяемого им для проведения платежа; - *балансовая валюта*, в которой ведётся баланс мерчанта, ассоциированный с платежом. Когда все эти валюты совпадают, никакой конвертации не требуется. Но еслихотя бы одна из этих валют отличается от стыковочной „соседней“, необходима соответствующая конвертация\(поскольку без такой конвертации средства не могут быть доставлены от отправителя к получателю и платёж не может быть проведён\). ![conversion_scheme](images/ru_pp_conversion_gbp.svg) В качестве примера можно рассмотреть ситуацию, когда пользователь из Польши с платёжной картой, счёт которой ведётся в польских злотых \([PLN](references/ru/currencies/PLN.md)\), рассчитывается за определённую услугу в Норвегии и при этом по умолчанию доступен платёжный канал в норвежских кронах \([NOK](references/ru/currencies/NOK.md)\), а валютой баланса мерчанта выступают фунты стерлингов \([GBP](references/ru/currencies/GBP.md)\). Если в описанной ситуации предварительно не настроено и не доступно никаких альтернатив, то для проведения такого платежа актуальна двойная конвертация: - для пользователя — из злотых в кроны на стороне эмитента карты; - для мерчанта — из крон в фунты стерлингов на стороне Ecommpay. Вместе с тем, если в описанной ситуации предварительно настроен и доступен платёжный канал в фунтах, то такой платёж может быть проведён в фунтах, без конвертации из операционной валюты в балансовую, а если доступен платёжный канал в злотых, то такой платёж может быть проведён в злотых, без конвертации из пользовательской валюты в операционную. Поддержка платёжных каналов и балансов в различных валютах обеспечивает вариативность в проведении платежей и позволяет избегать разных видов конвертации. При этом в практической работе стоит также учитывать целесообразность поддержки разных балансов и ограничения по допустимым валютам для разных платёжных методов, каналов и балансов в платформе Ecommpay. Непосредственно при проведении платежей конвертация всегда выполняется автоматически, по мере необходимости.При этом фактическая операционная валюта каждый раз выбирается в платформе исходя из параметров запроса, выбора предпочтительной валюты пользователем \(когда это применимо\), свойств проекта и метода\(включая заданные со стороны мерчанта предпочтения по использованию валют и каналов\) и, наконец, доступности актуальных платёжных каналов. Также в дополнение к рассмотренным вариантам возможна и конвертация на стороне веб-сервиса, до обращения к платёжной платформе — по курсам и на условиях мерчанта. ## Варианты выбора валют {#section_ndp_qbf_ngc .section} При работе через Payment Page можно использовать разные варианты включения пользователя в выбор операционной валюты. - *Выбор валюты в веб-сервисе* — вариант, при котором пользователь может выбирать удобную ему валюту до вызова платёжной формы\(с конвертацией на стороне веб-сервиса\). В таком случае выбранная валюта становится *запрошенной операционной* и используется в платформе соответствующим образом для проведения платежа. Этот вариант работы поддерживается по умолчанию в отношении любых платёжных методов и валют. - *Выбор валюты в платёжной форме* — вариант, при котором пользователь может выбирать удобную ему валюту непосредственно в платёжной форме\(с конвертацией на стороне платёжной платформы Ecommpay; [подробнее](ru_pp_currency_choice.md)\). В таком случае валюта, указанная в запросе на открытие Payment Page, остаётся *запрошенной операционной*, а валюта, выбранная пользователем, становится *выбранной операционной* и используется в платформе как более приоритетная для проведения платежа \(по умолчанию выступая и *фактической операционной* валютой\). Этот вариант работы поддерживается при его подключении в отношении отдельных платёжных методов и доступных для этих методов валют. ## Контроль платежей с конвертацией {#section_c2b_gcf_ngc .section} Чтобы контролировать применение разных валют и конвертации при проведении платежей, можно использовать различные инструменты, включая: - программные оповещения о результатах проведения платежей \([подробнее](ru_platform_callbacks.md)\), - реестры и карточки платежей в интерфейсе Dashboard \([подробнее](ru_dbl_payments.md)\), - информацию о выполнении операций, получаемую через Data API \([подробнее](ru_dbl_using_api.md)\), - финансовые отчёты. При этом следует учитывать, что для конвертации на стороне платёжной платформы Ecommpay применяются курсы, которые динамически определяются в соответствии с рыночной информацией от специализированных партнёрских сервисов. С вопросами об этих курсах, комиссиях и о применении конвертации в разных случаях можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Выбор валюты пользователем {#ru_pp_currency_choice} статья о возможности предоставлять пользователям выбор удобных для них валют непосредственно в платёжной форме ## Общая информация {#section_xzd_tn1_4gc .section} В некоторых случаях может быть актуальным предоставлять пользователям выбор удобных для них валют непосредственно в платёжной форме. При работе с Payment Page такая возможность может „бесшовно“ встраиваться в сценарии проведения разных видов платежей, с поддержкой широкого спектра допустимых валют, гибкой настройкой и автоматической конвертацией в тех случаях, когда она необходима. ![](images/ecommpay/ru_pp_conversion_1.svg "Выбор из общего списка валют для карты") ![](images/ecommpay/ru_pp_conversion_2.svg "Выбор из релевантных валют для карты") ![](images/ecommpay/ru_pp_conversion_3.svg "Выбор из списка валют для сервиса Google Pay") В пользовательских сценариях при подключении такой возможности предварительно выбранной всегда выступает валюта, указанная в запросе на открытие Payment Page, и вместе с тем появляется возможность выбрать любую из других доступных валют, увидеть актуальную сумму платежа в этой валюте и подтвердить платёж с учётом выбора. Выбор валюты в платёжной форме поддерживается, прежде всего, длянаиболее популярных методов с глобальным покрытием — классических карточных платежейи платежей с использованием методов Apple Pay и Google Pay.С вопросами о подключении, настройке и использовании этой функциональности, как и с предложениями о её развитии, можно обращаться к курирующему менеджеру Ecommpay. ## Особенности и ограничения {#section_ydx_kf3_hhc .section} При подключении и использовании выбора валют в платёжной форме стоит учитывать следующие особенности и ограничения: - *Методы с возможностью выбора валют должны быть доступны к прямому выбору в платёжной форме.* В частности, в отношении методов Apple Pay и Google Pay это значит, что кнопки выбора этих методов должны располагаться в Payment Page непосредственно на странице выбора метода, а не на панели указания данных карты \(когда они выступают в интерфейсе как дополнительные варианты к оплате с прямым использованием карты и не могут быть выбраны независимо от классических карточных платежей\). Когда это условие соблюдается, метод может быть выбран предварительно, через указание его кода в запросе, или непосредственно на форме пользователем, а после выбора метода обеспечивается возможность выбора валюты. Иначе выбор валюты для таких методов становится недоступным. - *Валюта может выбираться только из доступных пользователю, и доступностью валют можно управлять.* В базовом случае к доступным относятся те валюты, которые поддерживаются в качестве операционных для используемого проекта и по которым может выполняться конвертация в рамках конкретного сеанса работы платёжной формы. Вместе с тем, для оплат с прямым использованием платёжных карт этот набор валют можно ограничивать. В платформе поддерживаются следующие варианты работы: - Выбор из всех доступных валют. Этот вариант поддерживается для классических карточных платежей и платежей с использованием методов Apple Pay и Google Pay. - Выбор из валют, релевантных для страны выпуска указанной карты \(исходя из её номера\), либо, при их недоступности, выбор из всех остальных доступных валют. Так, при указании пользователем номера карты, выпущенной в Бразилии, и поддержке бразильского реала в качестве операционной валюты для используемого проекта, в числе доступных для выбора могут отображаться исходная валюта запроса и бразильский реал. Этот вариант поддерживается только для классических карточных платежей, и при его использовании список доступных валют отображается пользователю только после указания номера карты. - Выбор из валют, релевантных для страны выпуска указанной карты \(исходя из её номера\), либо, при их недоступности, исключение возможности выбора и использование исходной валюты запроса. Так, при указании пользователем номера карты, выпущенной в Бразилии, и отсутствии поддержки бразильского реала в качестве операционной валюты для используемого проекта, в числе доступных для выбора может отображаться только указанная в исходном запросе валюта. Этот вариант поддерживается только для классических карточных платежей, и при его использовании список доступных валют отображается пользователю только после указания номера карты. Со стороны веб-сервиса для каждого рабочего проекта может быть согласован своей перечень доступных валют и один из вариантов ограничения доступности этих валют для карточных платежей. В результате перечень доступных валют может адаптироваться под специфику конкретного проекта, платёжного метода и платёжного инструмента. - *Валютами баланса могут выступать доллары, евро и фунты стерлингов.* Если пользователи выбирают для оплат доллары США, евро или фунты стерлингов\(и при этом настроены соответствующие балансы и оплаты проводятся в выбранных валютах\), средства зачисляются на балансы в этих же валютах. В остальных случаях зачисления выполняются в долларах США. - *Для конвертации используются валютные курсы, устанавливаемые Ecommpay.* Эти курсы динамически определяются на стороне Ecommpay в соответствии с рыночной информацией от специализированных партнёрских сервисов.Для контроля фактически применённых курсов можно использовать различные интерфейсы платёжной платформы \([подробнее](ru_platform_payment_information_overview.md)\). Также с вопросами о курсах и порядке их применения можно обращаться к курирующему менеджеру Ecommpay. ## Схема работы {#section_sm4_sf3_hhc .section} После подключения этой функциональности для проведения платежей с выбором валюты пользователем со стороны веб-сервиса не требуется никаких дополнительных действий\(по отношению к основным действиям, связанным с проведением платежей соответствующего типа\). Так, схема проведения оплаты в одну стадию с выбором пользователем валюты выглядит следующим образом. ![](images/ru_pp_uml_conversion.svg) 1. От Payment Page к платёжной платформе направляется запрос на получение необходимой для конвертации информации\(о доступных валютах и курсах обмена\). 2. На стороне платёжной платформы выполняется обработка запроса. 3. От платёжной платформы к Payment Page передаётся необходимая для конвертации информация. 4. В платёжной форме Payment Page отображается список доступных валют. 5. Пользователь выбирает валюту и указывает необходимые сведения. 6. От Payment Page к платёжной платформе направляется запрос на оплатус учётом валюты, выбранной пользователем. В случаях, когда валюта, выбранная пользователем, отличается от исходно указанной в запросе, в оповещениях о результатах платежей может передаваться\(когда это настроено\) объект `sum_customer` со следующими параметрами:. - `amount` — сумма операции в дробных единицах пользовательской валюты; - `currency` — буквенный код пользовательской валюты в формате ISO-4217 alpha-3. Эта информация дополняет базовые сведения о суммах и валютах, которые передаются в объекте `operation`: - `sum_initial` — сумма и валюта, указанные в исходном запросе; - `sum_converted` — сумма и валюта, фактически использованные для выполнения операции. В следующем примере в оповещении содержится информация о том, что при проведении оплаты в размере `10,00 USD` в качестве пользовательской была выбрана валюта `BRL`, в результате чего была выполнена конвертация в `57,60 BRL`и сумма, фактически оплаченная пользователем, составила `57,60 BRL`. ``` {#codeblock_c1c_vvj_hhc .language-json} { "payment":{ "method":"card", "sum":{ "amount":1000, // сумма платежа в запрошенной операционной валюте "currency":"USD" // код запрошенной операционной валюты }, "id":"11006", "type":"purchase", "status":"success", "date":"2022-06-23T13:32:09+0000", "description":"" }, "customer":{ "id":"12" }, "sum_customer":{ "amount":5760, // сумма в пользовательской валюте "currency":"BRL" // код пользовательской валюты }, "account":{ "number":"541333******0019" }, "project_id":42, "operation":{ "created_date":"2022-06-23T13:32:02+0000", "request_id":"a23962a836e8e4-db4f1981d9-0006", "sum_initial":{ "amount":1000, // сумма операции в запрошенной операционной валюте "currency":"USD" // код запрошенной операционной валюты }, "sum_converted":{ "amount":5760, // сумма операции в фактической операционной валюте "currency":"BRL" // код фактической операционной валюты }, "code":"0", "message":"Success", "eci":"05", "provider":{ "id":6, "payment_id":"1629803", "auth_code":"563253", "endpoint_id":6, "date":"2022-06-23T10:32:09+0000" }, "id":682400942, "type":"sale", "status":"success", "date":"2022-06-23T13:32:09+0000" }, "signature":"BsGd0vcBQjd+aFl8ehEPRjf/eQUABow+VO+/xSG+lqKo6xHQ==" } ``` ## Подключение {#section_sv5_wvj_hhc .section} Чтобы подключить возможность проведения платежей с выбором валют в платёжной форме,со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpay подключение этой функциональности и ключевые аспекты её настройки и запуска, включая: - проекты, методы и валюты, для которых актуальна эта функциональность; - необходимость динамической фильтрации доступных для выбора валют исходя из информации о странах выпуска используемых платёжных карт; - необходимость тестирования перед запуском в работу. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить работу платёжной формы с использованием этой возможности и сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении возможности. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Поддержка экологических взносов {#ru_pp_ekko_earth} статья о возможности добавлять в пользовательские сценарии с применением платёжной формы внесение добровольных экологических взносов через партнёрский сервис ekko ## Общая информация {#section_nyc_v5y_flb .section} При работе с платёжной формой Payment Page можно расширять пользовательские сценарии возможностью внесения экологических взносов через специализированный партнёрский сервис [ekko](https://ekko.earth/) — непосредственно после выполнения основных целевых действий в платёжной форме. Такая возможность позволяет пользователям вместе с покупками проявлять заботу о природе, а мерчантам — демонстрировать в рамках своих сервисов приверженность к устойчивому развитию и благотворному воздействию на окружающую среду. ![](images/ecommpay/ru_pp_ekko_earth.svg "Включение возможности сделать взнос на итоговую страницу Payment Page") Использование такой функциональности в общем случае не требует от мерчанта никаких дополнительных технических действий и никаких дополнительных комиссий, но при этом позволяет поддерживать экологические активности и повышать лояльность пользователей и ценность бренда. ## Особенности и ограничения {#section_nxx_cfl_5fc .section} При поддержке экологических взносов стоит учитывать следующие особенности и ограничения: - Эта возможность может подключаться только при использовании платёжной формы Payment Page 5-го поколения. - Пользователи могут вносить взносы вслед за выполнением определённых целевых действий, среди которых [проведение оплат](ru_pp_purchase.md), [блокировка средств](ru_pp_purchase_auth.md) и [регистрация повторяемых оплат](ru_pp_recurring.md). - Взносы могут вноситься с использованием тех платёжных методов, которые поддерживаются со стороны платёжной платформы Ecommpay и сервиса ekko, независимо от того, какие платёжные методы доступны в рамках проекта мерчанта. К таким методам для внесения взносов относятся [классические карточные методы](ru_pm_card_payments.md), а также методы [Apple Pay](pm_applepay.md) и [Google Pay](pm_googlepay.md). - Каждый взнос проводится как отдельный платёж — в той же валюте, которая использовалась в рамках основного платежа перед переходом к сервису ekko, и вне проекта, который был использован при этом. Это позволяет оперировать методами, доступными для проведения взносов, и не перегружать сервисы мерчантов дополнительной информацией о сопутствующих взносах. - Для проведения взносов используются отдельные сеансы работы платёжной формы Payment Page, с её оформлением от Ecommpay и ekko и без учёта параметров тех проектов, в рамках которых выполнялись предшествующие действия пользователей. - Пользователи получают уведомления о зачислении внесённых взносов непосредственно от сервиса ekko. С вопросами, касающимися таких взносов, пользователей также можно перенаправлять к сервису ekko. С вопросами об этих и иных особенностях работы с экологическими взносами можно обращаться к курирующему менеджеру Ecommpay. ## Пользовательский сценарий {#section_sqh_3fl_5fc .section} Базовый сценарий внесения экологического взноса через сервис ekko при работе с Payment Page выглядит следующим образом: 1. На итоговой странице Payment Page вместе с информацией о выполнении целевого действия пользователю отображается дополнительная панель с возможностью перехода к сервису ekko для внесения взноса. 2. Пользователь переходит к сервису ekko. 3. Пользователь выбирает размер взноса и перенаправляется к платёжной форме Payment Page \(с инициированием нового сеанса её работы\). 4. Пользователю отображается платёжная форма \(с оформлением от Ecommpay и ekko\). 5. Пользователь выбирает платёжный метод, указывает необходимые данные и подтверждает готовность внести взнос выбранным способом. 6. Пользователю последовательно отображаются страница ожидания и страница с информацией о зачислении взноса. 7. Пользователь переходит на страницу сервиса ekko с информацией о зачислении его взноса и возможностью указать адрес электронной почты для получения дополнительного уведомления. 8. Пользователь получает уведомление на указанный им адрес электронной почты. Дополнительно к этим действиям при проведении взноса могут выполняться различные вспомогательные процедуры, такие как 3‑D Secure \([подробнее](ru_PP_Additional.md)\), но, как и с другими действиями по внесению взносов, они не требуют какого-либо реагирования со стороны веб-сервиса. ## Подключение {#section_nzh_xg4_xfc .section} Чтобы подключить возможность внесения пользователями экологических взносов через сервис ekko при работе с Payment Page, со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpay подключение этой возможности и необходимость её тестирования. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить работу платёжной формы с использованием этой возможностии сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении возможности. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Погашение задолженностей {#ru_PP_debt_repayments} статья о возможности применять платёжную форму для платежей по кредитам и займам ## Общая информация {#section_rzc_z4b_12b .section} *Погашение задолженности* — вид оплаты с карты пользователя, предназначенный для выплаты по кредиту или займу. Такой вид оплаты доступен для мерчантов, предоставляющих услуги микрокредитования с кодом категории `6012` или `6051`. Платеж на погашение задолженности может быть осуществлен как разовая оплата, регистрация повторяемой оплаты или проверка действительности карты. В случаях если мерчант зарегистрирован в Великобритании \(для платежей по картам Mastercard\) или Европейском регионе, согласно регламенту распределения Visa \(для платежей по картам Visa\), то в дополнение к обязательным объектам и параметрам в запросе указываются номер счёта мерчанта и дополнительные данные пользователя: - debt\_account — номер счёта для получения средств с карты пользователя. Допустимы буквы латинского алфавита и цифры, длина не более 10 символов; - customer\_first\_name — имя пользователя, - customer\_last\_name — фамилия пользователя, - customer\_day\_of\_birth — дата рождения пользователя, в формате ДД-ММ-ГГГГ, - customer\_zip — почтовый индекс адреса пользователя \(обязательно для Великобритании\). Для платежей по картам American Express данная возможность не поддерживается. Если параметр не указан в запросе, то он дополнительно запрашивается в оповещении о необходимости дополнить данные \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\) ```language-xml EPayWidget.run( { payment_id: '3936', payment_amount: 1000, payment_currency: 'EUR', project_id: 200, debt_repayment: '897896541, customer_first_name: 'John', customer_last_name: 'Johnson', customer_zip: 'SW1W 0NY, customer_day_of_birth: '12-05-1990', customer_id: '1', signature: "PJkV8ej\/UG0Di8NN5...==" } ) ``` Если платеж на погашение задолженности осуществлен через регистрацию повторяемой оплаты — передавать дополнительные параметры в запросах на проведение не требуется, они будут взяты из первоначального запроса. Дополнительные сведения об этой функциональности и ее подключении уточняйте у вашего курирующего менеджера Ecommpay. ## Ограничения Mastercard {#section_tc2_zmj_4mb .section} Согласно требованиям Mastercard эта функциональность доступна мерчантам из Великобритании только с кодом категории `6012`, для всех остальных стран допускаются оба кода — `6012` или `6051`. Запрещено погашение задолженности с кредитных и предоплаченных карт, если страной выпуска карты и регистрации мерчанта является Великобритания. ## Ограничения Visa {#section_wdr_qgk_4mb .section} Согласно требованиям Visa мерчанты из Великобритании, которые принимают погашение просроченной задолженности, должны иметь код категории `6051`. В других случаях и для всех остальных стран допускаются оба кода — `6012` или `6051`. Запрещено погашение задолженности с кредитных карт. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Ограничение времени работы с платёжной формой {#ru_pp_time_limit} статья о возможности устанавливать время, до истечения которого можно совершать платежи в рамках отдельных вызовов платёжной формы ## Общая информация {#section_pk4_rgg_nmb .section} При работе с Payment Page поддерживается возможность указывать дату и время, до наступления которых пользователь может работать сплатёжной формойдля подтверждения целевого действия. Такая возможность позволяет контролировать предоставление пользователям услуг с привязкой ко времени и может быть актуальна, например, при продаже билетов или распродаже товаров. Дата и время завершения работы с платёжной формой указываются в запросах на открытие Payment Page и для подключения этой возможности не требуется никаких дополнительных действий. Если ограничение задано, на страницах Payment Page используется дополнительная информационная панель, на которой отображаются: - запись о времени завершения работы с формой в формате `hh:mm`; - запись об остающемся времени работы с формой с использованием таймера `mm:ss`; - индикатор остающегося времени, отображаемый в последние пять минут из числа отведённых. **Прим.:** Следует учитывать, что ограничение времени работы с платёжной формой не должно превышать 30 суток с момента отправки в платформу запроса на открытие Payment Page, иначе указанные в таком запросе дата и время завершения работы игнорируются и соответствующие ограничения не применяются. ## Пользовательский сценарий {#section_ctr_ghg_nmb .section} Со стороны пользователя проведение оплаты с ограничением времени работы с Payment Page выглядит следующим образом: 1. На стороне веб-сервиса мерчанта пользователь подтверждает готовность перейти к оплате и перенаправляется к платёжной форме. 2. Пользователь выполняет необходимые действия для оплаты и получает информацию о результате. В случае, если пользователь не подтверждает выполнение целевого действия до истечения отведённого времени, ему отображается страница с уведомлением об истечении этого времени. ![](images/ecommpay/ru_pp_time_limit_1.svg "1 — Открытие платёжной формы") ![](images/ecommpay/ru_pp_time_limit_2.svg "2 а — Проведение оплаты") ![](images/ecommpay/ru_pp_time_limit_3.svg "2 б — Отклонение оплаты из-за истечения времени") ## Особенности {#section_bcn_ldj_5tb .section} При использовании возможности ограничения времени работы с Payment Page следует учитывать некоторые особенности: - при проведении отдельных платежейсо стороны платёжных систем или провайдеров могут запрашиваться дополнительные данныео пользователе, что может увеличивать время работы пользователейс платёжной формой \([подробнее](ru_pp_clarification.md)\); - ограничение времени работы с формой для отдельного платежа актуально и при выполнении всех повторных попыток в рамках этого платежа, независимо от их количества \([подробнее](ru_PP_Try_Again.md)\). ## Формат запроса {#section_pnk_grg_nmb .section} Чтобы задать ограничение на время работы с платёжной формой, в запросе на открытие Payment Page необходимо передать дату, время, а также часовой пояс в формате `YYYY-MM-DDThh:mm:ss±hh` \(или `YYYY-MM-DDThh:mm:ss±hh:mm`\) в значении параметра `best_before`, при этом допустимое время работы с формой должно составлять не более 30 суток с момента отправки запроса на открытие Payment Page. ```language-json { // обязательные параметры для проведения оплаты "project_id": 42, "payment_id": "7654321777", "payment_currency": "USD", "payment_amount": 131970, "customer_id": "customer_12", "signature": "TSzdE5rJZaA9TYAKoGpfXriFf82MxF...", // дата и время завершения работы с платёжной формой — // 12 апреля 2021 года в 10:15:30, GMT+3 "best_before": "2021-04-12T10:15:30+03" } ``` **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса {#ru_pp_additional_data} статья о возможности фиксировать при работе через Payment Page сопутствующую информацию о проводимых оплатах для её внутреннего использования в работе мерчантов **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) ## Введение {#ru_pp_additional_data_overview} В некоторых случаях при проведении платежей может быть актуально передаватьне только обязательные и рекомендуемые со стороны провайдера параметры, но и те сведения, которые могут быть полезны в дальнейшем на стороне мерчанта\(с привязкой к конкретным платежам и их статусам\). Для таких ситуаций в структуре Payment Page API предусмотрены параметры, позволяющие передавать различные сведения в запросах и получать эти сведения вместе с другой информацией в составе итоговых оповещений. **Прим.:** При работе с Gate API можно использовать аналогичные [возможности](ru_gate_additional_data.md). ## Передача сведений о бронировании товаров и услуг {#ru_pp_booking_data} ### Общая информация {#section_hxj_4jg_g1c .section} С помощью параметра `booking_info` можно фиксировать сведения о бронировании, связанном с оплатой, и получать эти сведения в оповещениях от платёжной платформы. Эта возможность может применяться достаточно широко \(например, для указания сведений о бронировании билетов на концерт\) и гибко, без ограничений на категорию мерчанта \(согласно коду [Merchant Category Code, MCC](ru_glossary.md)\). При наличии вопросов о работе с этой возможностью можно обращаться к курирующему менеджеру Ecommpay. Параметр `booking_info` может использоваться практически для всех целевых действий с прямым использованием платёжных карти с использованием методов Apple Pay, Click to Pay и Google Pay: в частности, для проведения оплат, блокировки средств, регистрации нерегулярных повторяемых оплат и проверки платёжных инструментов. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача параметра `booking_info` с информацией о датах начала и окончания бронируемой услуги \(в параметрах `start_date` и `end_date`\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. ### Пример использования {#section_x3n_yjg_g1c .section} В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере музыкальных фестивалей, актуально обеспечить: - сбор и обработку информации о бронированиях билетов на фестивали; - оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю. Для этого настраивается следующая схема работы: 1. В каждом запросе на открытие Payment Page со стороны веб-сервиса мерчанта передаются сведения о бронировании в параметре `booking_info`. В значении этого параметра указывается строка, полученная в результате кодирования JSON-объекта алгоритмом Base64. Исходный JSON-объект может включать в себя следующую информацию. - Массив `bookers` с информацией о лицах, для которых бронируется услуга. Каждый элемент такого массива содержит: - `first_name` — имя получателя услуги, указанное при бронировании; - `last_name` — фамилия получателя услуги, указанная при бронировании; - `email`— адрес электронной почты, указанный при бронировании. - Массив `items` с информацией об отдельных услугах, которые входят в состав бронирования. Каждый элемент такого массива содержит: - `description` — описание отдельной услуги в рамках бронирования; - `start_date` — дата начала действия отдельной услуги; - `end_date` — дата окончания действия отдельной услуги. - А также следующие параметры: - `start_date` — дата начала действия забронированной услуги; - `end_date` — дата окончания действия забронированной услуги; - `description` — произвольное описание бронирования; - `total` — итоговая стоимость бронирования; - `pax` — количество лиц, для которых бронируется услуга; - `reference` — указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта; - `id` — идентификатор бронирования, уникальный в рамках сервиса мерчанта. **Прим.:** Стоит учитывать, что в параметрах `start_date` и `end_date` исходного JSON-объекта должны передаваться даты начала и окончания забронированной услуги в целом, а в параметрах `start_date` и `end_date` массива `items` — даты начала и окончания отдельных её составляющих. **Внимание:** В параметрах `total` и `pax` следует передавать численное значение выше `0`. 2. По результатам выполнения соответствующей операции информация из параметра `booking_info` передаётся к веб-сервису мерчанта в итоговом оповещениии становится доступной для просмотра в карточке платежа интерфейса Dashboard. 3. На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о выполняемых операциях. ### Подключение {#section_b2p_nkg_g1c .section} Указывать параметр `booking_info` в запросах и получать передаваемые в нём сведения в оповещениях \(при использовании типовой структуры оповещений\) можно без согласований и каких-либо дополнительных действий. Эти возможности доступны по умолчанию. ### Формат данных {#section_pzw_4kg_g1c .section} Параметр `booking_info` может включаться в запросы на открытие Payment Page в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта `booking_info` с необходимыми параметрами бронирования. |Параметр|Описание| | |--------|--------|--| |`bookers` array |Массив с информацией о лицах, для которых бронируется услуга|1| |`first_name` string |Имя получателя услуги, указанное при бронировании|1-11| |`last_name` string |Фамилия получателя услуги, указанная при бронировании|1-21| |`email` string |Адрес электронной почты, указанный при бронировании|1-31| |`items` array |Массив с информацией об отдельных услугах, которые входят в состав бронирования|2| |`description` string |Описание отдельной услуги в рамках бронирования|2-12| |`start_date` string |Дата начала действия отдельной услуги, в формате `ДД-ММ-ГГГГ`|2-22| |`end_date` string |Дата окончания действия отдельной услуги, в формате `ДД-ММ-ГГГГ`|2-32| |`start_date` string |Дата начала действия забронированной услуги, в формате `ДД-ММ-ГГГГ`|3| |`end_date` string |Дата окончания действия забронированной услуги, в формате `ДД-ММ-ГГГГ`|4| |`description` string |Произвольное описание бронирования|5| |`total` integer |Итоговая стоимость бронирования. Указываемое значение должно быть выше `0`|6| |`pax` integer |Количество лиц, для которых осуществлено бронирование. Указываемое значение должно быть выше `0`|7| |`reference` string |Указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта|8| |`id` string |Идентификатор бронирования, уникальный в рамках сервиса мерчанта|9| ```language-json "booking_info": { "start_date": "12-08-2026", "end_date": "14-08-2026", "description": "Sideris music festival full pass", "total": 200000, "pax": 2, "bookers": [ { "first_name": "William", "last_name": "Herschel", "email": "rsfellow@mail.com" }, { "first_name": "Caroline", "last_name": "Herschel", "email": "salariedastronomer@mail.com" } ], "items":[ { "description": "VIP Arrival", "start_date": "12-08-2026", "end_date": "12-08-2026" }, { "description": "Hotel", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "Concerts", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "VIP Departure", "start_date": "14-08-2026", "end_date": "14-08-2026" } ], "reference": "musicfestlink", "id": "83" } ``` ``` ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ== ``` ```language-json { "payment": { "date": "2024-01-24T06:24:45+0000", "method": "card", "id": "FESTIVAL_PASS_1781", "sum": { "amount": 0, "currency": "EUR" }, "type": "purchase", "status": "refunded", "description": "FESTIVAL_PASS_1781" }, "project_id": 111738, "customer": { "id": "musicaficionado_83" }, "account": { "number": "551115******1822", "token": "7123ba1f24f16a115f3390a9", "type": "mastercard", "card_holder": "WILLIAM HERSCHEL", "expiry_month": "08", "expiry_year": "2030" }, "booking info": \{ // Объект с информацией о бронировании "start\_date": "12-08-2026", "end\_date": "14-08-2026", "description": "Sideris music festival full pass", "total": 200000, "pax": 2, "bookers": \[ \{ "first\_name": "William", "last\_name": "Herschel", "email": "rsfellow@mail.com" \}, \{ "first\_name": "Caroline", "last\_name": "Herschel", "email": "salariedastronomer@mail.com" \} \], "items": \[ \{ "description": "VIP Arrival", "start\_date": "12-08-2026", "end\_date": "12-08-2026" \}, \{ "description": "Hotel", "start\_date": "12-08-2026", "end\_date": "14-08-2026" \}, \{ "description": "Concerts", "start\_date": "12-08-2026", "end\_date": "14-08-2026" \}, \{ "description": "VIP Departure", "start\_date": "14-08-2026", "end\_date": "14-08-2026" \} \], "reference": "musicfestlink", "id": "83" \}, "operation": { "provider": { "payment_id": "0010000124258736", "auth_code": "", "endpoint_id": 414, "id": 414 }, "sum_converted": { "amount": 200000, "currency": "EUR" }, "code": "0", "message": "Success", "id": 55386010114429, "type": "refund", "status": "success", "date": "2024-01-24T06:24:45+0000", "sum_initial": { "amount": 200000 "currency": "EUR" }, "created_date": "2024-01-24T06:24:43+0000", "request_id": "abcaf52323381a-d988c158cc4b43046-00055387" } } ``` ## Передача произвольных сведений {#ru_pp_merchant_data} ### Общая информация {#section_f2q_4kv_fzb .section} С помощью параметра `merchant_data` можно фиксировать расширенные сведения о составе заказа, информацию об использовании промокодов и бонусных баллов и другие актуальные данные.При этом можно комбинировать состав таких сведений со сведениями, передаваемыми в описании платежа \(в параметре `payment_description`\) и в информации для товарного чека \(в параметре `receipt_data`\). Это позволяет получать в оповещениях всю необходимую информацию без её дублирования в различных параметрах. ### Пример использования {#section_ung_wjx_y2c .section} В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере видеоигр, актуально обеспечить: - сбор и обработку информации о дополнительных услугах, приобретаемых пользователями в процессе игр; - оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю. Специалисты мерчанта обращаются с такой задачей к курирующему менеджеру Ecommpay, после чего настраивается следующая схема работы: 1. В каждом запросе на открытие Payment Page со стороны веб-сервиса мерчанта передаётся информация о приобретаемых услугах — в виде JSON-объекта в параметре `merchant_data`. В состав строки `merchant_data` включаются: - массив `items`, в котором каждый элемент содержит артикул \(`sku`\), описание \(`description`\) и количество приобретаемых услуг \(`count`\); - параметр `total_count` с общим количеством приобретаемых услуг или товарных позиций; - параметр `user_id` с внутренним идентификатором пользователя. 2. По результатам проведения каждого платежа информация из строки `merchant_data` передаётся к веб-сервису мерчанта в итоговом оповещении и становится доступной для просмотра в карточке платежа интерфейса Dashboard. 3. На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о проводимых платежах. ![](images/ecommpay/ru_pp_additional_data.svg "Оформление заказа в веб-сервисе") ![](images/ecommpay/ru_merchant_data_db.svg "Отображение информации в интерфейсе Dashboard") ### Подключение {#section_xf5_tkv_fzb .section} Возможности применения параметра `merchant_data` для передачи и получения различных сведений следует согласовывать с курирующим менеджером Ecommpay. После согласований специалисты Ecommpay выполняют необходимые действия в платёжной платформе и уведомляют о готовностик включению расширенных сведений в оповещения и к отображению этих сведений в интерфейсе Dashboard. ### Формат данных {#section_tp5_rfc_nzb .section} В запросах на открытие Payment Page для проведения платежей сведения в параметре `merchant_data` должны передаваться в виде JSON-объекта. При этом, поскольку параметр имеет строковый тип данных\(string\), для передачи JSON-объекта методом POST требуется экранировать символ `"` \(двойной штрих,U+0022\) путём постановки перед ним символа `\` \(косой обратной черты,U+005C\). Это необходимо, чтобы чётко разграничивать на уровне программного взаимодействия, какие кавычки закрывают строку, а какие относятся к содержанию JSON-объекта внутри строки. Вместе с тем, при отправке запросов методом GET экранировать содержимое JSON-объектов не обязательно \(поскольку корректная интерпретация данных в таких случаях возможна и без экранирования\). В итоговых оповещениях о результатах платежей сведения из параметра `merchant_data` передаются в параметре `data` объекта `merchant`, с применением экранирования. В следующих примерах содержимое параметра разбито на несколько строк для удобства чтения. ```language-json "merchant_data": "{"items":[{"sku":"GM12-CC", "description":"10 Copper Coins","count":1}, {"sku":"GM12-GC","description":"Golden Coin", "count":2}],"total_count":3,"user_id":"122"}" ``` ```language-json "merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" ``` ```language-json "merchant": { "data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" } ``` --- # Контроль интерфейсных событий {#ru_pp_ui_monitoring} статья о возможностях получать и обрабатывать информацию о различных интерфейсных событиях, связанных с платёжной формой и действиями пользователя в ней ## Общая информация {#section_bgm_5sr_bbb .section} При использовании любой платёжной формы может быть полезным контролировать работу пользователей с её интерфейсом— чтобы оперативно реагировать на разные события и подстраивать под них работу сервиса. Например, можно проверять загрузку формы и давать пояснения пользователю, если по каким-либо причинам она не открылась, или напоминать пользователю о необходимости указания данных для завершения оплаты, если он перешёл на другие страницы сервиса, не закончив работу с формой, и так далее. Для платёжной формы Payment Page такая функциональность поддерживается за счёт служебных библиотек от Ecommpay, которые позволяют получать непосредственно в клиентской части веб-сервиса актуальную информацию об определённых событиях и автоматически реагировать на эти события с помощью функций по обработке, определяемых при вызове формы \(JavaScript callbacks\). Такая функциональность может дополнять получение информации через серверные [оповещения](ru_platform_callbacks.md), но её всё же не рекомендуется использовать для их замены. ## Использование {#section_kjq_wn2_tgc .section} Для подключения и использования возможностей контроля событий в платёжной форме Payment Page не требуется никаких согласований и организационных действий — только технические. Во-первых, в клиентской части веб-сервиса должны быть подключены служебные библиотеки от Ecommpay. ``` {#codeblock_b13_c42_tgc .language-xml} ``` Во-вторых, в веб-сервисе должна быть реализована функциональность по обработке тех событий, на которые необходимо реагировать с учётом специфики сервиса и пользовательских сценариев.Это могут быть, например, функции, касающиеся отображения статуса платежа в карточке заказа или работы с токенами платёжных карт, используемых пользователем. В-третьих, в каждом вызове Payment Page, для которого необходим контроль интерфейсных событий, должен передаваться код соответствующих функций. Он должен определяться на языке JavaScriptнепосредственно в запросах, вместе с параметрами вызова платёжной формы. При этом допустимо определять любое число функций из числа поддерживаемых для Payment Page и использовать обращения к объектам `data`, в которых содержится информация о целевых событиях, когда это применимо \(подробнее [далее](ru_pp_ui_monitoring.md)\). Так, при тестировании интеграции с платёжной платформой Ecommpay через Payment Page можно фиксировать идентификаторы запросов на проведение платежей и использовать их в дальнейшем для контроля и анализа проведения платежей. Определение функции `onPaymentSubmitResult`, в рамках которой можно выводить значение переменной `request_id` в консоль браузера, может выглядеть следующим образом. ``` {#codeblock_sbr_twx_1hc .language-javascript .show_more} EPayWidget.run({ payment_id: 'payment_443', payment_amount: 1000, payment_currency: 'EUR', project_id: 57123, signature: 'YWb6Z20ByxpQ30hfTIjaCCsVIwVynXV', **onPaymentSubmitResult: async function \(data\) \{ console.log\(data.request\_id\); \}** }, 'POST'); ``` Другой пример — определение функции`onResize`, которая должна автоматически вызываться при изменении размера страницы, отображаемой в элементе iframe. ``` {#codeblock_wh1_p42_tgc .language-javascript} EPayWidget.run({ payment_id: 'payment_443', payment_amount: 1000, payment_currency: 'EUR', project_id: 57123, signature: 'YWb6Z20ByxpQIjaCCsVIwVynXV', **onResize: function \(data\) \{ site.resize\(\{ frameWidth: data.width, frameHeight: data.height \}\); \}** }, 'POST'); ``` В этом примере функция `onResize` использует параметры объекта `data` для задания новых значений ширины и высоты в параметрах `frameWidth` и `frameHeight`. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) ## Функции и события {#ru_pp_ui_monitoring_handlers} ### Открытие формы {#section_yyn_t42_tgc .section} |`onLoaded`|Открытие платёжной формы\(с полноценной загрузкой всех элементов интерфейса и началом сеанса работы с учётом параметров вызова\). При регистрации этого события можно зафиксировать скорость открытия формы на конечном устройстве и ждать следующих действий пользователя. ``` {#codeblock_kvw_2dp_1hc .language-json} { "width":900, "height":640 } ``` | |`onFailLoading`|Ошибка при попытке открытия платёжной формы\(без возможности начать сеанс работы с учётом параметров вызова\). При регистрации этого события можно проверить корректность параметров вызова и отправить повторный запрос \(при этом допустимо повторно использовать тот же идентификатор платежа, если он корректен и до этого не использовался при проведении платежей в рамках проекта\). ``` {#codeblock_sc5_y2p_1hc .language-json} { "message": "Application error", "config": { "customer_id": "1", "frame_mode": "iframe", "payment_amount": "1000", "payment_currency": "EUR", "payment_id": "payment_443", "project_id": "57123", "signature": "YWb6Z20ByxpQIjaCCsVIwVynXV", "target_element": "iframe-holder" } } ``` | ### Переход к целевому действию {#section_inz_z2p_1hc .section} |`onPaymentMethodSelect`|Выбор платёжного метода. В случаях, когда пользователь переходит между вкладками разных методов, событие регистрируется при каждом таком переходе. При регистрации этого события можно зафиксировать, какой метод выбрал пользователь — на основании полученной информации, которая включает в себя название, код типа платежа \(`1` для оплат, `2` для выплат\) и код метода \(согласно [справочнику](ru_pm_codes.md)\). ``` {#codeblock_e3j_3fp_1hc .language-json} { "name":"Bank cards", "payment_method_type":"1", "payment_method_code":"card" } ``` | |`onWalletSelect`|Выбор сохранённых платёжных данных\(платёжной карты или другого платёжного инструмента\). При регистрации этого события можно зафиксировать, какой платёжный инструмент выбрал пользователь \(на основании маскированных данных об этом инструменте\), и, если актуально, использовать эту информацию в работе веб-сервиса, например для последующего проведения платежей с применением токенов \([подробнее](ru_PP_Payment_by_token.md)\). ``` {#codeblock_rbq_kfp_1hc .language-json} { "code":"card", "id":"37489", "pan":"541333******0019", "month":"12", "year":"2028", "type":"mastercard", "pan_first6":"541333", "pan_last4":"0019", "expired":"0", "cvv_required":"1", "holder":"JOHN SMITH", "token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce", "field_values":{ "country":"", "phone":"", "email":"", "card[expiry]":"12/28", "card[holder]":"JOHN SMITH", "card[type]":"mastercard", "card[country]":"GB", "card[product_name]":"Mastercard Gold", "card[bank_name]":"Citibank", "recurring_enable":"0" } } ``` | |`onWalletRemove`|Удаление сохранённых платёжных данных\(платёжной карты или другого платёжного инструмента\). При регистрации этого события можно зафиксировать, какой платёжный инструмент исключил пользователь \(на основании маскированных данных об этом инструменте\), и, если актуально, использовать эту информацию в работе веб-сервиса. ``` {#codeblock_l1s_nfp_1hc .language-json} { "code":"card", "id":"37489", "pan":"541333******0019", "month":"12", "year":"2028", "type":"mastercard", "pan_first6":"541333", "pan_last4":"0019", "expired":"0", "cvv_required":"1", "holder":"JOHN SMITH", "token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce", "field_values":{ "country":"", "phone":"", "email":"", "card[expiry]":"12/28", "card[holder]":"JOHN SMITH", "card[type]":"mastercard", "card[country]":"GB", "card[product_name]":"Mastercard Gold", "card[bank_name]":"Citibank", "recurring_enable":"0" } } ``` | |`onPaymentSent`|Подтверждение целевого действия\(после указания всех необходимых сведений в платёжной форме\) и переход к странице ожидания. При регистрации этого события можно зафиксировать время, понадобившееся пользователю для работы с платёжной формой, и, если актуально, использовать его в дальнейшем, например для настройки допустимого времени работы \([подробнее](ru_pp_time_limit.md)\). Также после регистрации этого события можно отображать в интерфейсе веб-сервиса информацию об ожидании результата платежа и ждать следующих событий. Для этого события предоставление информации в объекте `data` не предусмотрено | |`onPaymentSubmitResult`|Регистрация запроса в платёжной платформе. При регистрации этого события можно зафиксировать идентификатор запроса на проведение платежа и использовать этот идентификатор для контроля состояния платежа в нештатных ситуациях, например при обрыве связи с пользовательским устройством и отсутствии серверных оповещений о проведении платежа \(подробнее о контроле состояния платежей через программные запросы — [в отдельной статье](ru_Gate_payment_status_request.md)\). ``` {#codeblock_t2z_sfp_1hc .language-json} { "request_id": "bc4-5a032482802f-00002836" } ``` | ### Выполнение требуемых процедур {#section_hzh_5fp_1hc .section} |`onShowClarificationPage`|Отображение страницы для ввода дополнительных сведений, необходимых для выполнения целевого действия \([подробнее](ru_pp_clarification.md)\). При регистрации этого события можно зафиксировать факт запроса дополнительных сведений у пользователя и время этого события, после чего отследить, перешёл ли пользователь к следующим шагам \(по событию `onSubmitClarificationForm`\) и был ли проведён платёж \(с итоговым статусом `Success`\). Для этого события предоставление информации в объекте `data` не предусмотрено | |`onSubmitClarificationForm`|Подтверждение отправки запрошенных сведений. При регистрации этого события можно зафиксировать время, понадобившееся пользователю для предоставления запрошенных дополнительных сведений, и отследить, был ли проведён платёж \(с итоговым статусом `Success`\). При регулярной фиксации событий `onSubmitClarificationForm` с последующим отклонением платежей можно обращаться к специалистам технической поддержки Ecommpay и настраивать передачу необходимых сведений в запросах или их сбор в платёжной форме \([подробнее](ru_pp_clarification.md)\). Для этого события предоставление информации в объекте `data` не предусмотрено | |`onRedirectIframe`|Перенаправление к стороннему сервису с использованием элемента iframe \(согласно параметрам проекта и вызова, [подробнее](ru_PP_pm_redirect_mode.md)\). При регистрации этого события можно зафиксировать время такого перехода и отследить, вернулся ли пользователь к платёжной форме \(по событию `onRedirectIframeComplete`\) и был ли проведён платёж \(с итоговым статусом `Success`\). При выявлении проблем с такими переходами и возвращениями пользователей можно обращаться к специалистам технической поддержки Ecommpay. Для этого события предоставление информации в объекте `data` не предусмотрено | |`onResize`|Изменение размера HTML-страницы, отображаемой в элементе iframe. При регистрации этого события можно зафиксировать актуальные размеры страниц, используемых в рамках выполнения пользователем целевых действий, проверить, что исходный размер элемента iframe позволяет полноценно отображать эти страницы, и при необходимости скорректировать размеры элемента iframe. ``` {#codeblock_nqs_lgp_1hc .language-json} { "width":1080, "height":660 } ``` | |`onRedirectIframeComplete`|Возвращение от стороннего сервиса, открытого в элементе iframe, к платёжной форме. При регистрации этого события можно зафиксировать время работы пользователя со сторонним сервисом и ожидать завершения сеанса работы с платёжной формой. Для этого события предоставление информации в объекте `data` не предусмотрено | ### Отображение итоговой информации {#section_mk4_ngp_1hc .section} |`onTokenizeSuccess`|Отображение итоговой страницы с информацией о сохранении платёжных данных \(в результате вызова и использования формыв режиме `card_tokenize`\). При регистрации этого события можно сохранить созданный токен и использовать его для последующих действий на стороне веб-сервиса. ``` {#codeblock_odk_jqp_1hc .language-json} { "general":{ "project_id":57123, "customer_id":"1", "signature":"Lqj0B3ue5tG33F9NV qkVbjXHXNZj3x1o/5q7r8/rY+O5MC64iW3k77tg==" }, "request":{ "id":"a748130e0350895d71bd8154342e0c261e30e086-558 3739b323907d9d61a5ffbf4118afeec695552", "action":"tokenize", "status":"success" }, "token":"503hyugfe7874f5utrdub1f671667hvyufxyd2341ce", "customer":{ "ip_address":"102.129.155.0", "id":"1" }, "token_created_at":"2025-09-28T11:25:30+0000", "token_status":"active" } ``` | |`onCardVerifySuccess`|Отображение итоговой страницы с информацией о том, что проверка действительности платёжного инструмента проведена \(в результате вызова и использования формыв режиме `card_verify`\). При регистрации этого события можно зафиксировать, что платёжный инструмент признан действительным, и перейти к последующим действиям на стороне веб-сервиса \(например, к регистрации токена платёжной карты и инициированию выплаты\). ``` {#codeblock_hbf_r3j_dhc .language-json} { "request_id": "bbeef4d51e6ae4aadcb86d-00003158", "transaction": { "id": 3157000012768, "date": "2025-10-29T14:15:02+0000", "type": "account_verification" }, "payment": { "method": "card", "date": "2025-10-29T14:15:02+0000", "result_code": "0", "result_message": "Success", "status": "success", "is_new_attempts_available": false, "attempts_timeout": 0, "id": "EP1120-3e48", "cascading_with_redirect": false, "is_cascading": false, "remaining_refund": 0, "split_with_redirect": false, "method_id": 1, "provider_id": 3 }, "sum_real": { "amount": 0, "currency": "GBP" }, "customer": { "id": "123" }, "account": { "number": "424242******4242", "type": "visa", "id": 70256633, "card_holder": "HENRY FORD", "expiry_month": "12", "expiry_year": "2028" }, "avs_result": "X", "rrn": "000047769105", "sum_request": { "amount": 0, "currency": "GBP" }, "company": { "id": 1, "title": "My store" }, "terminal": { "method_code": "card", "mode_code": "card_verify", "name": "v5" }, "cashout_data": { "account_number": "424242******4242", "customer_first_name": "Henry", "customer_last_name": "Ford" }, "general": { "project_id": 291451, "payment_id": "EP1120-3e48", "signature": "fZKqrch...3//pDDJUaJ8R/7Yi5A==" }, "description": "", "operations": [ { "id": 3157000013487, "type": "account verification", "status": "success", "date": "2025-10-29T14:15:02+0000", "processing_time": "2025-10-29T14:15:01+0000", "request_id": "12a469296f-00003158", "sum": { "amount": 0, "currency": "GBP" }, "code": "0", "message": "Success", "provider": { "id": 3, "payment_id": "17616663016501" } } ], "return_url": "https://mystore.com/redirect/au80n3l6krq80" } ``` | |`onCardVerifyFail`|Отображение итоговой страницы с информацией о том, что проверка действительности платёжного инструмента отклонена \(в результате вызова и использования формыв режиме `card_verify`\). При регистрации этого события можно зафиксировать, что платёжный инструмент не признан действительным, уточнить причину отклонения и отобразить пользователю соответствующее сообщение. ``` {#codeblock_ij3_ylj_dhc .language-json} { "sum_request": { "amount": 0, "currency": "GBP" }, "request_id": "bbeef40ef99a6cd-00003158", "transaction": { "id": 3157000012768, "date": "2025-10-29T14:15:02+0000", "type": "account_verification" }, "payment": { "method": "card", "date": "2025-10-29T14:15:02+0000", "result_code": "100", "result_message": "General decline", "status": "decline", "is_new_attempts_available": false, "attempts_timeout": 0, "id": "EP1120-3e48", "cascading_with_redirect": false, "is_cascading": false, "split_with_redirect": false, "method_id": 1, "provider_id": 3 }, "sum_real": { "amount": 0, "currency": "GBP" }, "customer": { "id": "123" }, "account": { "number": "424242******4242", "type": "visa", "card_holder": "HENRY FORD", "expiry_month": "12", "expiry_year": "2034" }, "avs_result": "X", "rrn": "000047769105", "company": { "id": 1, "title": "My store" }, "terminal": { "method_code": "card", "mode_code": "card_verify", "name": "v5" }, "cashout_data": { "account_number": "424242******4242", "customer_first_name": "Henry", "customer_last_name": "Ford" }, "general": { "project_id": 291451, "payment_id": "EP1120-3e48", "signature": "fZPTytEOwT1Z8...BB3//pDDJUaJ8R/7Yi5A==" }, "description": "", "operations": [ { "id": 3157000013487, "type": "account verification", "status": "decline", "date": "2025-10-29T14:15:02+0000", "processing_time": "2025-10-29T14:15:01+0000", "request_id": "70-18a296f-00003158", "sum": { "amount": 0, "currency": "GBP" }, "code": "100", "message": "General decline", "provider": { "id": 3, "payment_id": "17617473016501" } } ], "return_url": "https://mystore.com/redirect/baun3l6krq80" } ``` | |`onPaymentSuccess`|Отображение итоговой страницы с информацией о проведении платежа. При регистрации этого события можно зафиксировать итоговый статус платежа и перейти к последующим действиям на стороне веб-сервиса \(с выполнением оплаченного заказа и соответствующей коммуникацией с пользователем\). Также в таком случае можно зафиксировать общее время проведения платежа. ``` {#codeblock_trr_lqp_1hc .language-json} { "sum_request":{ "amount":1000, "currency":"EUR" }, "request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024", "transaction":{ "id":2000000004, "date":"2025-10-08T11:14:49+0000", "type":"purchase" }, "payment":{ "method":"card", "date":"2025-10-08T11:14:49+0000", "result_code":"0", "result_message":"Success", "status":"success", "is_new_attempts_available":false, "attempts_timeout":0, "id":"payment_443", "provider_id":3 }, "sum_real":{ "amount":1000, "currency":"EUR" }, "customer":{ "id":"1" }, "status":"success", "account":{ "number":"541333******0019", "type":"mastercard", "card_holder":"JOHN SMITH", "id":37489, "expiry_month":"12", "expiry_year":"2028" }, "rrn":"000047769105", "auth_code":"563253", "general":{ "project_id":57123, "payment_id":"payment_443", "signature":"EjYXLJpvDBPtbwQSQ0ukti9B Y1m73+0SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA==" }, "description":"", "operations":[{ "id":2000000004, "type":"sale", "status":"success", "date":"2025-10-08T11:14:49+0000", "processing_time":"2025-10-08T11:14:49+0000", "sum":{ "amount":1000, "currency":"EUR" }, "code":"0", "message":"Success" } ], "return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46" } ``` | |`onPaymentFail`|Отображение итоговой страницы с информацией об отклонении платежа. При регистрации этого события можно зафиксировать, что платёж отклонён, уточнить причину отклонения, отобразить пользователю соответствующее сообщение и, если актуально, отправить повторный запрос \(с новым идентификатором платежа\). ``` {#codeblock_xl5_mqp_1hc .language-json} { "sum_request":{ "amount":1000, "currency":"EUR" }, "request_id":"f68d1288e3e37b0ded8763d94588dd2915c5dfadb5024", "transaction":{ "id":2000000004, "date":"2025-10-08T11:14:49+0000", "type":"purchase" }, "payment":{ "method":"card", "date":"2025-10-08T11:14:49+0000", "result_code":"10106", "result_message":"expired", "status":"decline", "is_new_attempts_available":false, "attempts_timeout":0, "id":"payment_443", "provider_id":3 }, "sum_real":{ "amount":1000, "currency":"EUR" }, "customer":{ "id":"1" }, "status":"decline", "account":{ "number":"541333******0019", "type":"mastercard", "card_holder":"JOHN SMITH", "id":37489, "expiry_month":"12", "expiry_year":"2028" }, "rrn":"000047769105", "auth_code":"563253", "general":{ "project_id":57123, "payment_id":"payment_443", "signature":"EjYXLJpvDBPtbwQSQ0ukti9BY1m73+0 SrRCCQGB5QXHzxTu7Fory/XQaZTtNz2Vm33AA==" }, "description":"", "operations":[{ "id":2000000004, "type":"sale", "status":"decline", "date":"2025-10-08T11:14:49+0000", "processing_time":null, "sum":{ "amount":1000, "currency":"EUR" }, "code":"10106", "message":"expired" } ], "return_url":"http://pp/process/complete-redirect?0ebeqgdcgbsj3d278b46" } ``` | ### Закрытие формы {#section_od2_wgp_1hc .section} |`onDestroy`|Закрытие платёжной формы до отображения итоговой страницы. При регистрации этого события стоит принять соответствующие действия в клиентской части веб-сервиса \(например, с уведомлением об уточнении информации\), проверить статус платежа \([подробнее](ru_Gate_payment_status_request.md)\) и перейти к последующим действиям, исходя из статуса платежа. Для этого события предоставление информации в объекте `data` не предусмотрено | |`onExit`|Закрытие платёжной формы после отображения итоговой страницы\(в соответствии с заданными параметрами\). При регистрации этого события можно зафиксировать, что сеанс работы с формой закончен, и перейти к последующим действиям на стороне веб-сервиса. Также в таком случае можно зафиксировать общее время работы пользователя с формой. Для этого события предоставление информации в объекте `data` не предусмотрено | --- # Использование сведений о мерчанте при проведении платежей {#ru_pp_descriptor} статья о возможностях опосредованно предоставлять пользователям сведения о мерчантах через сервисы эмитентов при работе через Payment Page ## Общая информация {#section_u2p_3rk_mhc .section} Выступая как эквайер, Ecommpayсогласно правилам платёжных систем передаёт другим сторонам, участвующим в проведении платежей, сведения о мерчантах. Эти сведениямогут использоваться каждой из сторон по своему усмотрению и, как правило, доводятся эмитентами до пользователей в уведомлениях и банковских выписках. По умолчанию сведения о каждом мерчантестатичны и включают в себялишь согласованное написание названия организации, однако по инициативе мерчанта к названию могут динамически добавляться и другие сведения,касающиеся конкретных операций или иных аспектов деятельности. Эти динамические части описаний могут указываться в запросах на открытие Payment Pageи ограничиваются только общей длиной строки и составом допустимых символов \(подробнее [далее](ru_pp_descriptor.md#section_b3f_hvp_13c)\).Так, в качестве сведений о мерчанте может указываться запись с названием организации и периодом бронирования услуги \(`Cosmotour* 17-19 feb`\) или с названием организации и забронированного отеля \(`Cosmotour* MarsSuite`\). ![](images/ecommpay/ru_gate_descriptor_2.svg "Указание периода бронирования") ![](images/ecommpay/ru_gate_descriptor_1.svg "Указание названия отеля") Гибкое применение корректных и информативных сведений такого рода позволяет пользователям чётче идентифицировать мерчантов и платежи, а мерчантам — улучшать пользовательский опыт и снижать вероятность опротестования платежей со стороны пользователей.Работа с такими сведениями в рамках платёжной платформы Ecommpay актуальна для *карточных платежей* \(включая классические карточные платежи и методы Apple Pay, Click to Pay, Google Pay и Visa Instalments\) в отношении разовых и повторяемых оплат, проверок действительности платёжных карт и выплат. ## Особенности {#section_fhg_s3m_djc .section} При работе со сведениями о мерчанте следует учитывать ряд особенностей: - Основное назначение сведений о мерчантах — помогать пользователям идентифицировать их операции и предотвращать неуместные опротестования. В связи с этим важно избегать в используемых сведениях двусмысленностей и иных сложностей интерпретирования и фокусировать внимание пользователей на тех сведениях, которые помогают однозначно идентифицировать мерчанта и, по возможности, каждую операцию с ним. В частности, можно руководствоваться рекомендацией использовать знакомое для пользователей название бренда и ёмкое описание товаров и услуг в рамках каждой операции. - Правила работы со сведениями о мерчантах могут отличаться для разных платёжных систем. Такие отличия стоит иметь в виду, как минимум, в части допустимых форматов \(подробнее [далее](ru_pp_descriptor.md#section_b3f_hvp_13c)\). - Порядок предоставления сведений о мерчантах пользователям определяется эмитентами. Состав и способ отображения итоговых сведений о мерчантах в уведомлениях, банковских выписках и иных материалах определяются правилами работы конкретных эмитентов. Это ведёт к тому, что сведения могут выглядеть по-разному как среди разных эмитентов, так и среди разных интерфейсов одного эмитента и среди разных типов операций в рамках одного интерфейса \(в частности, такие отличия могут касаться разных типов оплат и выплат, а также операций с использованием сервисов Mastercard MoneySend и Visa Direct\). ## Подключение {#section_ejd_vd3_1jc .section} Название организации, используемое в качестве базового варианта сведений о мерчанте, фиксируется при регистрации мерчанта в платёжной платформе и может быть скорректировано в дальнейшем только через курирующего менеджера Ecommpay. Чтобы подключить возможность использования дополнительных сведений о мерчанте,со стороны мерчанта следует: 1. Согласовать с курирующим менеджером Ecommpay актуальность подключениядля конкретных проектов и необходимость тестирования функциональности. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работыс использованием этой возможности и сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении функциональности. ## Использование {#section_dh5_v5p_13c .section} В тех случаях, когда для мерчанта актуально использование дополнительных сведений,в запросах на открытие Payment Page следует передавать соответствующий параметр: - для оплат и проверок действительности платёжных карт — `merchant_descriptor`; - для выплат — `sender_descriptor`. Также стоит учитывать, что в случаях, когда значения параметров `merchant_descriptor` и `sender_descriptor` не соответствуют требуемому формату \([подробнее](ru_pp_descriptor.md#section_b3f_hvp_13c)\), в платформе может выполняться техническая корректировка таких значений\(в частности, с транслитерацией алфавитных символов и удалением недопустимых неалфавитных\) и это не приводит к отклонению инициируемых платежей. Вместе с тем, значения этих параметровне анализируются на стороне Ecommpay по содержанию, но могут анализироваться и использоваться в дальнейшем на стороне эмитентов. В связи с этим со стороны мерчанта важно обеспечивать техническую и содержательную корректность сведений, передаваемых в параметрах `merchant_descriptor` и `sender_descriptor`, в каждом случае их применения. ## Формат данных {#section_b3f_hvp_13c .section} Допустимая длина используемых сведений о мерчанте ограничивается со стороны каждой платёжной системы. Так, Mastercard устанавливает максимальной длину в 22 символа, а Visa — в 25 символов.Все избыточные символы при этом отсекаются. Это стоит учитывать при формировании описаний наряду с ограничениями по допустимым символам. Допустимыми для параметров `merchant_descriptor` и `sender_descriptor` являются буквы базовой латиницы, цифры, пробел \(U+0020\) и следующие символы: |`*`|U+002A|звёздочка \(астериск\)| |`,`|U+002C|запятая| |`-`|U+002D|дефис| |`.`|U+002E|точка| |`=`|U+003D|знак равенства| |`_`|U+005F|нижнее подчёркивание| Чтобы сформировать параметр `merchant_descriptor` или `sender_descriptor`, необходимо указатьсогласованный вариант названия организации и дополнительные сведения, разделив их звёздочкой \(`*`\) и пробеломи проверив соответствие ограничениям по длине строки.Например, если использовать название `Cosmotour` длиной в 9 символов \(и 2 символа в качестве разделителя\), допустимая длина для дополнительных сведений составит 11 символов для карт Mastercard и 14 символов для карт Visa — достаточно для записи вида `Cosmotour* to the Moon`. **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Отправка чеков и оповещений пользователям {#ru_PP_receipt_data .concept} статья о возможностях прямо информировать пользователей о проведении платежей и других событиях через электронную почту при работе через Payment Page ## Отправка чека {#section_nkg_4ln_lhb .section} Для формирования и отправки пользователям электронных товарных чеков по итогам проведения платежей необходимо подключить соответствующую функциональность и обеспечить передачу информации о товарных позициях каждого платежа. При подключении этой функциональности, помимо прочего, можно настроить набор языков, используемых для формирования чеков, и задать язык, используемый по умолчанию. Выбором языка в конкретных случаях можно управлять так же, как и выбором языка платёжной формы — через указание кода языка в значении параметра `language_code`. Данные для чека передаются в виде JSON-объекта, который необходимо закодировать в Base64 и отправить в запросе на проведение платежа в параметре `receipt_data`. Структура JSON-объекта приведена в модели `[receiptdata](https://api-developers.ecommpay.com/api.html#/c2NoOjQwNTY3ODY2-receipt-data)` в Gate API. ## Пример передачи данных для чека {#section_l5c_lft_lhb .section} Исходный JSON-объект: ```language-json { "receipt_data":{ "positions":[ { "quantity":3, "amount":10000, "tax":18, "tax_amount":1800, "description":"Рамка с дизайном" } ], "total_tax_amount":1800, "common_tax":18 } } ``` Те же данные, закодированные с применением алгоритма Base64, для отправки в запросе на открытие Payment Page \(содержимое параметра разбито на несколько строк для удобства чтения\): ``` receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgICAg ICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI6MTgsCiAg ICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiLQoNCw0LzQutCwING BINC00LjQt9Cw0LnQvdC+0LwiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAs CiAgICAgICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ" ``` Подробная информация об отправке чеков пользователям представлена в разделе [Отправка уведомлений пользователям](ru_gate_receipts.md). **На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md) --- # Индивидуальное оформление {#ru_PP__design_customisation} статья о возможностях оформлять платёжную форму Payment Page с помощью специализированного конструктора, встроенного в интерфейс Dashboard ## Общая информация {#section_odq_gbr_jgc .section} По умолчанию при работе с Payment Page используется типовое оформление, разработанное и поддерживаемое специалистами Ecommpay с учётом актуальных требований и тенденций индустрии электронных платежей. Вместе с тем каждый мерчант может настраивать оформление платёжной формы с учётом специфики своих проектов — с помощью конструктора, встроенного в интерфейс Dashboard и доступного для учётных записей с правом работы с инструментарием Payment Page Designer \([подробнее](ru_dbl_roles_overview.md)\). ![](images/ecommpay/pp_designer_v5_1.svg "Типовое оформление") ![](images/ecommpay/pp_designer_v5_2.svg "Индивидуальное оформление (1)") ![](images/ecommpay/pp_designer_v5_3.svg "Индивидуальное оформление (2)") ![](images/ecommpay/pp_designer_v5_4.svg "Интерфейс конструктора (1)") ![](images/ecommpay/pp_designer_v5_6.svg "Интерфейс конструктора (2)") Интерфейс конструктора поддерживает широкий спектр возможностей и позволяет гибко настраивать оформление Payment Page, как для её основной редакции, так и для [облегчённой](ru_pp_microframe_solution.md). При этом следует учитывать, что изменения в оформлении платёжной формы могут существенно влиять на пользовательский опыт и проведение платежей, а ответственность за их возможное негативное влияние на конверсию возлагается на мерчанта. В связи с этим крайне важно вдумчиво готовить и анализировать любые изменения и при необходимости возвращаться к проверенным базовым вариантам. С вопросами и предложениями по работе с конструктором оформления Payment Page можно обращаться к курирующему менеджеру Ecommpay. ## Возможности {#section_e1z_gbr_jgc .section} Работа с вариантами оформления Payment Page может строиться по-разному: - Если актуальны относительно простые изменения в рамках одного проекта, для этого применима *настройка одного варианта оформления*. - Если актуальна тонкая настройка, с разными вариантами оформления в рамках одного или нескольких проектов, для этого необходимо *конфигурирование разных вариантов оформления*, с использованием различных стилей для разных случаев. Каждый из этих вариантов работы описан далее в рамках этой статьи и при работе с каждым из этих вариантов в случае с настройкой оформления основной редакции Payment Page можно: - добавлять логотип или иное заголовочное изображение и определять его расположение в форме; - скрывать записи о Ecommpay, используемые в качестве основного логотипа \(если он не был заменён в интерфейсе конструктора\) и в качестве уведомления об авторстве формы; - задавать фоновый цвет или изображение, используемое на панели с информацией о платеже; - настраивать цвета основных элементов формы; - управлять отображением панели с информацией о платеже при различных вариантах открытия формы; - задавать фоновый цвет или изображение, используемое в платёжной форме; - эмулировать работу различных страниц платёжной формы при использовании разных способов её открытия. В случае с настройкой оформления облегчённой редакции Payment Page можно настраивать цвета основных элементов формы и эмулировать работу формы с применением этих цветов. **На уровень выше:**[Payment Page](ru_PP_about.md) ## Настройка одного варианта оформления {#ru_pp_single_style_setup} Чтобы настроить в рамках конкретного проекта один вариант оформления Payment Page на базе типового, следует: 1. Открыть конструктор. Для этого в интерфейсе Dashboard необходимо открыть раздел **Проекты**, выбрать целевой проект и перейти на вкладку **Редактор платёжной страницы**. 2. Создать вариант оформления. Для этого следует щёлкнуть кнопку ![](images/universal/dbl/icon_add1.svg) в левом верхнем углу конструктора, задать название нового варианта в появившемся диалоговом окне и щёлкнуть кнопку **Create**. 3. Настроить параметры оформления. Для этого можно использовать инструменты, расположенные на панели инструментов в левой части конструктора. ![](images/ecommpay/pp_designer_v5_5.svg "Интерфейс конструктора: 1 — панель инструментов; 2 — область отображения формы") 4. Проверить вид формы. Для этого можно эмулировать работу платёжной формы в разных ситуациях, выбирая целевые страницы платёжной формы через выпадающий список **Preview layout** и переходя к отображению формы в актуальном виде \(**Redirect**, **Popup**, **iFrame**, **Mobile**, **Microframe**\) с помощью соответствующих кнопок. 5. Сохранить или применить оформление. Для этого необходимо: 1. Щёлкнуть кнопку **Save style** в верхней части панели инструментов \(если требуется только сохранить новое оформление\) или **Save and apply** в нижней части панели инструментов \(если требуется применить новое оформление\). 2. Убедиться в появлении сообщения о том, что вариант оформления сохранён \(и применён, если это актуально\) для выбранного проекта. После применения изменений новый вариант оформления используется для всех новых сеансов работы Payment Page в рамках целевого проекта и может быть скорректирован или заменён на другой по такой же схеме. ## Конфигурирование разных вариантов оформления {#ru_pp_multiple_styles_setup} ### Общая информация {#section_sf4_m33_2rb .section} Когда необходимо настраивать и применять разные варианты оформления платёжной формы для разных ситуаций в рамках одного или нескольких проектов, могут быть актуальны возможности конфигурирования *моделей интерфейса* и *стилей оформления*. Для этого полезно понимать, как строится оформление Payment Page и что можно делать с отдельными составляющими. Каждый вариант оформления Payment Page строится на базе модели интерфейса и стиля оформления, при этом в модели задаются состав, размеры, цвета и расположение различных элементов, а в стиле может дополнительно определяться часть используемых изображений и цветов. Для каждого вызова платёжной формы применимыми могут быть только одна модель интерфейса и один стиль оформления. Если необходимо одновременно поддерживать разные варианты оформления для разных ситуаций, для этого можно настраивать соответствующие варианты оформления и указывать их при вызове формы. При этом каждый стиль может использоваться только в том проекте, в рамках которого он был создан. В целом для конфигурирования разных вариантов оформления Payment Page со стороны мерчанта можно делать следующее: - *Согласовывать и использовать необходимую структуру проектов.* Все действия по настройке этой структуры в платёжной платформе выполняются специалистами Ecommpay с учётом потребностей мерчанта. - *Согласовывать применение необходимых моделей интерфейса для конкретных проектов.* Как правило, оформление Payment Page строится на актуальной версии базовой модели интерфейса. Вместе с тем, по согласованию с курирующим менеджером Ecommpay может быть допустимым и применение других моделей в оговорённых случаях. - *Создавать, настраивать и применять необходимые стили оформления для конкретных проектов.* Такие возможности полноценно доступны при работе с актуальной версией базовой модели интерфейса и могут быть частично или полностью недоступны при работе с другими моделями. ### Инструментарий {#section_l5c_4br_jgc .section} Для работы со стилями в интерфейсе Dashboard выделен конструктор оформления Payment Page, доступный в разделе **Проекты** на вкладке **Редактор платёжной страницы**. При работе с этим конструктором стоит учитывать следующие особенности: - Конструктор не позволяет переключаться в процессе работы между проектами. Для управления стилями по разным проектам следует открывать конструктор для каждого из них. - Конструктор не позволяет одновременно работать с разными стилями в одной вкладке и не поддерживает групповые операции со стилями. В случаях, когда актуальна параллельная работа с разными стилями, можно открывать и использовать конструктор в разных вкладках браузера. - Конструктор не поддерживает параллельную работу над одними и теми же стилями. В связи с этим стоит избегать ситуаций, когда в один и тот же стиль вносятся изменения на разных устройствах, поскольку это может приводить к различным нестыковкам и потере вносимых изменений. ## Работа со стилями оформления {#ru_pp_working_with_stylesv5} ### Общая информация {#section_jh4_jl3_2rb .section} Управлять стилями оформления Payment Page можно с помощью специализированного конструктора. Поскольку любые изменения в оформлении платёжной формы могут существенно влиять на пользовательский опыт и проведение платежей, работа с этим конструктором доступна только для учётных записей Dashboard, обладающих правом работы с инструментарием Payment Page Designer \([подробнее](ru_dbl_roles_overview.md)\). Чтобы открыть конструктор, следует открыть раздел **Проекты** интерфейса Dashboard, выбрать целевой проект и перейти на вкладку Payment Page Designer. В случаях, когда актуальна параллельная работа с несколькими стилями, можно открыть и использовать конструктор в нескольких вкладках браузера. **Внимание:** Конструктор оформления Payment Page не поддерживает параллельную работу над одними и теми же стилями. В связи с этим стоит избегать ситуаций, когда в один и тот же стиль вносятся изменения на разных устройствах, поскольку это может приводить к различным нестыковкам и потере вносимых изменений. ### Особенности {#section_t1p_dgf_kcc .section} Если со стороны мерчанта для работы с платёжной платформой Ecommpay используется более одного проекта, то при работе с конструктором стоит учитывать следующее: - Любой индивидуальный стиль оформления может использоваться только в рамках одного проекта. Для использования одного варианта оформления в отношении разных проектов следует создавать и настраивать соответствующее число стилей. - Конструктор не позволяет переключаться между проектами в процессе работы. Для управления стилями оформления Payment Page по конкретным проектам следует открывать конструктор для каждого из них \(через раздел **Проекты**\). ### Добавление стиля {#section_ff4_4sp_2rb .section} Чтобы добавить стиль оформления, следует: 1. Щёлкнуть кнопку ![](images/universal/dbl/icon_add1.svg) в левом верхнем углу конструктора. 2. Задать название нового стиля в появившемся диалоговом окне и, если актуально применить стиль при его сохранении, перевести переключатель **Apply after saving** в активное положение. 3. Подтвердить создание стиля с помощью кнопки **Create**. 4. Убедиться в отображении в интерфейсе конструктора страницы созданного стиля, с указанием его названия в выпадающем списке **Choose style**. ### Изменение стиля {#section_ipr_4sp_2rb .section} Чтобы изменить какой-либо стиль оформления, следует: 1. Выбрать требуемый стиль в выпадающем списке **Choose style** в левом верхнем углу конструктора. 2. Внести необходимые изменения с помощью инструментов, расположенных на панели инструментов конструктора. 3. При необходимости, [проверить](ru_PP__design_customisation.md#section_pqv_4sp_2rb) корректность внесённых изменений. 4. Сохранить внесённые изменения. Для этого следует: 1. Использовать один из двух вариантов сохранения в появившемся диалоговом окне: - для сохранения стиля без его применения — щёлкнуть кнопку **Save style** в верхней части панели инструментов конструктора; - для сохранения стиля и его применения — щёлкнуть кнопку **Save and apply** в нижней части панели инструментов конструктора. 2. Убедиться в появлении уведомления о сохранении стиля. Чтобы отменить внесённые в стиль изменения, можно использовать следующие варианты: - для сброса всех внесённых, но не сохранённых изменений относительно последних сохранённых изменений — закрыть окно конструктора, щёлкнув кнопку **Back to Dashboard** в правом верхнем углу, либо обновить используемую вкладку браузера с конструктором; - для сброса всех изменений стиля относительно типового оформления — щёлкнуть кнопку **Reset to defaults**, расположенную под выпадающим списком всех стилей. **Прим.:** При сбросе изменений подтверждение действия не запрашивается и, если требуется отменить такой сброс, то следует закрыть окно конструктора, не сохраняя никаких изменений. ### Проверка стиля {#section_pqv_4sp_2rb .section} Чтобы проверить отображение платёжной формы в различных случаях с применением какого-либо стиля оформления, следует выбрать этот стиль в выпадающем списке **Choose style** и эмулировать необходимые сценарии. Для этого можно использовать: - выпадающий список **Preview layout**— для выбора страницы Payment Page; - кнопки **Redirect**, **Popup**, **iFrame**, **Mobile** и **Microframe**— для варианта отображения платёжной формы; - отображаемую страницу Payment Page— для проверки её вида и возможностей заполнения полей. Следует учитывать, что для отображения в конструкторе могут быть доступны не все платёжные методы ине все страницы Payment Page, а эмулирование поведения платёжной формы выполняется только для отдельных элементов на отображаемых страницах. ### Применение стиля {#section_bsy_4sp_2rb .section} Чтобы назначить определённый стиль оформления используемым по умолчанию в рамках какого-либо проекта \(*применить* его для этого проекта\), следует: 1. Выбрать целевой стиль из выпадающего списка стилей. 2. Щёлкнуть кнопку **Save and apply** в нижней части панели инструментов конструктора для применения стиля. 3. Убедиться в появлении уведомления о применении стиля. **Прим.:** Если в рамках проекта актуально использовать разные стили оформления в дополнение к используемому по умолчанию, то в каждом запросе на открытие Payment Page с дополнительным стилем необходимо указывать идентификатор этого стиля в параметре `style_id`. Идентификаторы являются численными и отображаются справа от названий стилей после служебного символа `#`, например `Custom_red_style #6123`. ### Удаление стиля {#section_nlb_psp_2rb .section} Чтобы удалить определённый стиль оформления, необходимо: 1. Выбрать этот стиль в выпадающем списке **Choose style**. 2. Щёлкнуть кнопку ![](images/universal/dbl/icon_trashbean2.svg) справа от названия стиля. ![](images/universal/dbl/all_dbl_pp_designer_dropdown_list_of_styles.svg) 3. Подтвердить удаление с помощью кнопки **Delete** в появившемся диалоговом окне. 4. Убедиться в появлении уведомления об удалении стиля. Стоит учитывать, что при удалении стиля, применяемого по умолчанию для выбранного проекта \(о чём свидетельствует запись `current` рядом с названием стиля\), применяемым по умолчанию автоматически назначается следующий стиль в списке стилей оформления либо, при отсутствии альтернатив, типовой стиль оформления Payment Page. Если в такой ситуации необходимо назначить применяемым по умолчанию другой стиль, следует [применить](ru_PP__design_customisation.md#section_bsy_4sp_2rb) его для этого проекта. --- # Спецификация Payment Page API {#ru_PP_Parameters} спецификация с описанием структуры параметров, которые могут использоваться в запросах на открытие платёжной формы Payment Page В этой статье представлена спецификация параметров вызова Payment Page, с базовой информацией о применяемых параметрах и со ссылками на связанные статьи \(с описанием возможностей и сценариев, для которых актуальны отдельные параметры\). Параметры, отмеченные в этой спецификации как обязательные \(required\), являются обязательными для всех вызовов Payment Pageс проведением платежей. В режиме Card Tokenize к обязательным не относятся параметры платежа \(`payment_amount`, `payment_currency`, `payment_id`\). Параметры, отмеченные в этой спецификации как необязательные \(optional\), могут дополнительно настраиваться как обязательные для отдельных проектов и платёжных методов.Кроме того, ряд параметров может быть рекомендуемым к использованиюдля избегания участия пользователя в аутентификации 3‑D Secure \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\), для избегания процедуры дополнения информации о платеже \([подробнее](ru_pp_clarification.md)\) и для других улучшений в пользовательских сценариях и работе платёжной формы. С вопросами об обязательности и желательности передачи отдельных параметров в различных ситуациях можно обращаться к настоящей документации и специалистам технической поддержки Ecommpay. |Параметр|Описание| |--------|--------| |`account_token` string, optional |Токен платёжного инструмента. Представляет собой идентификатор, полученный от платёжной платформы при сохранении реквизитов этого платёжного инструмента. Может использоваться для проведения платежей по сохранённым данным \(в частности, [при проведении оплат](ru_PP_Payment_by_token.md)\). Пример: `42ab631449a78914502803aed8a0e5a728d558035d29a56f4dcc136c6bfc3021` | |`avs_post_code` string, optional |Почтовый индекс пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Пример: `WS13 6LG` | |`avs_street_address` string, optional |Адрес пользователя, используемый для проверки [Address Verification Service](ru_PP_avs.md). Включает в себя номер дома и название улицы. Пример: `4 Breadmarket Street` | |`baseUrl` string, optional |Базовый адрес вызова платёжной формы. Применяется в случаях, когдапо согласованию с курирующим менеджером Ecommpay он отличается от используемого по умолчанию \(https://paymentpage.ecommpay.com\) и его актуально указывать в запросах в явном виде. Пример: `https://cosmopage.site.com` | |`best_before` string, optional |Дата и время, до наступления которых по указанному часовому поясу пользователь может работать с платёжной формой для подтверждения целевого действия \([подробнее](ru_pp_time_limit.md)\). Могут указываться в виде записи формата `ГГГГ-ММ-ДДTчч:мм:сс`±`чч` или `ГГГГ-ММ-ДДTчч:мм:сс`±`чч:мм`. Должны указываться таким образом, чтобы допустимое время работы с формой составляло не более 30 суток с момента отправки запроса на открытие Payment Page. Пример: `2024-04-26T13:50:37+00` | |`billing_address` string, optional |Номер дома\(с обозначением корпуса или строения, где это актуально\) и название улицы в расчётном адресе пользователя. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Пример: `33 Store Street` | |`billing_city` string, optional |Название города в расчётном адресе пользователя. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Пример: `London` | |`billing_country` string, optional |Код страны в расчётном адресе пользователя. Указывается в формате ISO 3166-1 alpha-2. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Шаблон: `^[A-Z]{2}$` Пример: `GB` | |`billing_postal` string, optional |Почтовый индекс в расчётном адресе пользователя. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Пример: `BR1 1AA` | |`billing_region` string, optional |Название региона\(штата, провинции или иной территориальной области\) в расчётном адресе пользователя. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Пример: `Dorset` | |`billing_region_code` string, optional |Внутренний код региона\(штата, провинции или иной территориальной области\) в расчётном адресе пользователя. Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, и является применимым в тех случаях, когда передаётся в одном запросе с кодом страны в значении параметра `billing_country`.При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). Шаблон: `^[0-9A-Z]{1,3}$` Пример: `DOR` | |`booking_info` string, optional |Информация о бронировании услуг для учёта на стороне веб-сервиса. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя различные сведения из числа допустимых. Может использоваться для фиксации и учёта актуальных сведений при оплате услуг различных организаций \([подробнее](ru_pp_additional_data.md)\). - `bookers`, array — массив с информацией о лицах, для которых бронируется услуга; каждый элемент такого массива содержит: - `first_name`, string — имя получателя услуги, указанное при бронировании - `last_name`, string — фамилия получателя услуги, указанная при бронировании - `email`, string — адрес электронной почты, указанный при бронировании - `items`, array — массив с информацией об отдельных услугах, которые входят в состав бронирования; каждый элемент такого массива содержит: - `description`, string — описание отдельной услуги в рамках бронирования - `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата начала действия отдельной услуги - `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата окончания действия отдельной услуги - `start_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата начала действия забронированной услуги - `end_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата окончания действия забронированной услуги - `description`, string — произвольное описание бронирования - `total`, integer — итоговая стоимость бронирования - `pax`, integer — количество лиц, для которых бронируется услуга - `reference`, string — указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта - `id`, string — идентификатор бронирования, уникальный в рамках сервиса мерчанта ``` {#codeblock_fk4_4bn_phc .language-json} "booking_info": { "start_date": "12-08-2026", "end_date": "14-08-2026", "description": "Sideris music festival full pass", "total": 200000, "pax": 2, "bookers": [ { "first_name": "William", "last_name": "Herschel", "email": "rsfellow@mail.com" }, { "first_name": "Caroline", "last_name": "Herschel", "email": "salariedastronomer@mail.com" } ], "items":[ { "description": "VIP Arrival", "start_date": "12-08-2026", "end_date": "12-08-2026" }, { "description": "Hotel", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "Concerts", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "VIP Departure", "start_date": "14-08-2026", "end_date": "14-08-2026" } ], "reference": "musicfestlink", "id": "83" } ``` ``` {#codeblock_rpj_bcn_phc} ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ== ``` | |`card_holder` string, optional |Имя и фамилия держателя платёжной карты. Могут использоваться для предварительного заполнения соответствующего поля в платёжной форме\(с возможностью редактирования пользователем\) и должны соответствовать написанию, используемому непосредственно на карте, а также общим требованиям к написанию \([подробнее](ru_faq_payment_processing.md#section_z41_5cj_31c)\). Шаблон: `^[\p\{L}\p\{M}\s\-\'.]{1,255}$` Пример: `John Doe` | |`close_on_missclick` integer \(boolean\*\), optional |Указатель действия при щелчке за пределами формы, открытой [в модальном окне](ru_PP_method_ModalWindow.md). Актуален, когда используется соответствующий способ открытия. Может принимать одно из следующих значений: - `0` — оставить форму открытой \(вариант, используемый по умолчанию\); - `1` — закрыть форму. При работе с библиотекой `merchant.js` \([подробнее](ru_pp_interaction_organisation.md)\) значение этого параметра допустимо указывать как булево: `false` или `true`. Пример: `1` | |`css_modal_wrap` string, optional |Указатель дополнительного CSS-класса для оболочки модального окнас платёжной формой. Актуален, когда используется соответствующий способ открытия. Пример: `CosmoshopModal` | |`customer_address` string, optional |Название улицы и номер дома\(с обозначением корпуса или строения, где это актуально\) в адресе проживания пользователя, с использованием разделительной запятой. Представляет собой строку длиной не более 255 символов. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_pp_clarification.md)\). Пример: `Main Street, 12` | |`customer_account_info` string, optional |Информация об учётной записипользователя на стороне веб-сервиса и о его контактных данных. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя объект `customer` с различными сведениями из числа допустимых. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). - `address_match`, string — указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте `shipping`, в виде одного из следующих значений: - `Y` — адреса совпадают - `N` — адреса не совпадают - `account`, object — объект со сведениями об учётной записи пользователя на стороне веб-сервиса мерчанта: - `activity_day`, integer — количество попыток проведения оплаты за последние 24 часа, в виде числа от 0 до 999 - `activity_year`, integer — количество попыток проведения оплаты за последние 365 дней, в виде числа от 0 до 999 - `additional`, string — дополнительная информация об учётной записи пользователя, например её идентификатор, в произвольном формате с использованием до 64 символов - `age_indicator`, string, `^0[1-5]$` — индикатор давности учётной записи, который может принимать одно из следующих значений: - `01` — при невозможности оценить давность \(при инициировании платежа без аутентификации пользователя\) - `02` — при нулевой давности \(при создании учётной записи для инициирования платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней - `auth_data`, string — дополнительная информация об аутентификации на стороне веб-сервиса, в произвольном формате с использованием не более 255 символов - `auth_method`, string, `^(0[1-4]|0[1-4][1-6])$` — указатель способа последней аутентификации пользователя на стороне веб-сервиса, который может принимать одно из следующих значений: - для классических карточных платежей: - `01` — отсутствие аутентификации - `02` — аутентификация с использованием данных, сохранённых на стороне веб-сервиса мерчанта - `03` — аутентификация с использованием технологии Federated Identity \(например, Google Account или Facebook\) - `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\) - `auth_time`, string, `^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$` — дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм` - `change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ` - `change_indicator`, string, `^0[1-4]$` — индикатор давности изменений в учётной записи, за исключением изменения или сброса пароля, который может принимать одно из следующих значений: - `01` — при нулевой давности \(при изменениях в день проведения платежа\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней - `date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата создания учётной записи в формате `ДД-ММ-ГГГГ` - `pass_change_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ` - `pass_change_indicator`, string, `^0[1-5]$` — индикатор давности последнего изменения или сброса пароля, который может принимать одно из следующих значений: - `01` — при невозможности оценить давность \(пароль не был изменён или сброшен\) - `02` — при нулевой давности \(пароль был изменён или сброшен в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней - `payment_age`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата добавления реквизитов платёжного инструмента в формате `ДД-ММ-ГГГГ` - `payment_age_indicator`, string, `^0[1-5]$` — давность сохранения данных платёжного инструмента, используемой для проведения платежа, который может принимать одно из следующих значений: - `01` — при невозможности оценить давность \(платёж проводится без аутентификации в учётной записи\) - `02` — при нулевой давности \(данные карты сохранены в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней - `provision_attempts`, integer — количество попыток сохранения реквизитов для новых платёжных инструментов за последние 24 часа, от 0 до 999 - `purchase_number`, integer — количество покупок, совершённых через учётную запись за последние 6 месяцев, от 0 до 9999 - `suspicious_activity`, string, `^0[1-2]$` — индикатор подозрительной активности, который может принимать одно из следующих значений: - `01` — без выявления подозрительной активности - `02` — с выявлением подозрительной активности - `home_phone`, string — номер домашнего телефона пользователя, в виде последовательности цифр без использования разделителей - `work_phone`, string — номер рабочего телефона пользователя, в виде последовательности цифр без использования разделителей ```language-json { "customer":{ "address_match":"Y", "home_phone":"44991234567", "work_phone":"44997654321", "account":{ "additional":"gamer12345", "age_indicator":"01", "date":"01-10-2022", "change_indicator":"01", "change_date":"01-10-2022", "pass_change_indicator":"01", "pass_change_date":"01-10-2022", "purchase_number":12, "provision_attempts":16, "activity_day":22, "activity_year":222, "payment_age_indicator":"01", "payment_age":"01-10-2022", "suspicious_activity":"01", "auth_method":"01", "auth_time":"01-10-202213:12", "auth_data":"login_0102" } } } ``` ``` eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6IlkiLAogICAgImhvbWVfcGhvbmUiOiI3OTEwNTIxMTExMSIsCiAgICAid29ya19waG9uZSI6Ijc0OTU1MjExMTExIiwKICAgICJhY2NvdW50Ijp7IAogICAgICAiYWRkaXRpb25hbCI6ImdhbWVyMTIzNDUiLAogICAgICAiYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgImRhdGUiOiIwMS0xMC0yMDIyIiwKICAgICAgImNoYW5nZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJjaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicGFzc19jaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAicGFzc19jaGFuZ2VfZGF0ZSI6IjAxLTEwLTIwMjIiLAogICAgICAicHVyY2hhc2VfbnVtYmVyIjoxMiwKICAgICAgInByb3Zpc2lvbl9hdHRlbXB0cyI6MTYsCiAgICAgICJhY3Rpdml0eV9kYXkiOjIyLAogICAgICAiYWN0aXZpdHlfeWVhciI6MjIyMiwKICAgICAgInBheW1lbnRfYWdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBheW1lbnRfYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJzdXNwaWNpb3VzX2FjdGl2aXR5IjoiMDEiLAogICAgICAiYXV0aF9tZXRob2QiOiIwMSIsCiAgICAgICJhdXRoX3RpbWUiOiIwMS0xMC0yMDIyMTM6MTIiLAogICAgICAiYXV0aF9kYXRhIjoibG9naW5fMDEwMiIKICAgIH0KICB9Cn0== ``` | |`customer_account_number` string, optional |Идентификатор учётной записи пользователя на стороне платёжной системы. Может быть актуален при работе с отдельными платёжными методами\(например, [Neteller](pm_neteller.md) или [OVO Wallet](pm_ovo.md)\) и с учётом специфики конкретного метода может представлять собой идентификатор электронного кошелька, адрес электронной почты, номер телефона или иную запись. Пример: `example@mail.com` | |`customer_birthplace` string, optional |Название места рождения пользователя\(города или иного населённого пункта\). Представляет собой строку длиной не более 255 символов. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_pp_clarification.md)\). Пример: `London` | |`customer_city` string, optional |Название города \(или иного населённого пункта\) в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_pp_clarification.md)\). Пример: `London` | |`customer_country` string, optional |Код страны в адресе проживания пользователя. Указывается в формате ISO 3166-1 alpha-2. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий [\(подробнее](ru_pp_clarification.md)\). Шаблон: `^[A-Z]{2}$` Пример: `GB` | |`customer_day_of_birth` string, optional |Дата рождения пользователя. Представляет собой строку в формате `ДД-ММ-ГГГГ`. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_pp_clarification.md)\). Шаблон: `^\\d{2}-\\d{2}-\\d{4}$` Пример: `12-12-1990` | |`customer_email` string, optional |Адрес электронной почты пользователя. Представляет собой строку длиной не более 255 символов, состоящую из локального адреса и доменного имени, разделённых символом «@».Должен указываться для оплат с прямым использованием платёжных карт, если не указывается номер телефона \(в значении параметра `customer_phone`\) и не используется возможность указания таких сведений пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `john@example.com` | |`customer_first_name` string, optional |Имя пользователя. Представляет собой строку длиной не более 255 символов. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_pp_clarification.md)\). Пример: `Jane` | |`customer_id` string, required |Идентификатор пользователя в рамках проекта\(указанного в значении параметра `project_id`\). Должен быть однозначно сопоставим с учётной записью пользователя в веб-сервисе, в том числе для корректной работы с рисками и борьбы с мошенническими операциями. Пример: `customer_112` | |`customer_last_name` string, optional |Фамилия пользователя. Представляет собой строку длиной не более 255 символов.Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `Smith` | |`customer_middle_name` string, optional |Отчество \(или второе или среднее имя\) пользователя. Представляет собой строку длиной не более 255 символов.Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `Mary` | |`customer_mpi_result` string, optional |Информация о предыдущей аутентификации пользователя с использованием протокола 3‑D Secure. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя различные сведения из числа допустимых. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). - `mpi_result`, object — объект с данными о предыдущей аутентификации пользователя: - `acs_operation_id`, string, `^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$` — идентификатор предыдущей операции пользователя на стороне эмитента, полученный в параметре `acs_operation_id` оповещения о результате проведения предыдущего платежа, не более тридцати шести символов - `authentication_flow`, string, `^0[1-2]$` — указатель варианта предыдущего прохождения аутентификации пользователем, полученное в параметре `authentication_flow` оповещения о результате проведения предыдущего платежа, может принимать следующие значения: - `01` — frictionless flow - `02` — challenge flow - `authentication_timestamp`, string, `^\\d{12}$` — дата и время предыдущей успешной аутентификации пользователя, полученные в параметре `mpi_timestamp` оповещения о результате проведения предыдущего платежа ```language-json { "customer":{ "mpi_result":{ "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54", "authentication_flow":"01", "authentication_timestamp":"202210101050" } } } ``` ``` eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMjIxMDEwMTA1MCIKICAgIH0KICB9Cn0== ``` | |`customer_phone` string, optional |Номер телефона пользователя. В общем случае должен быть полным, с кодом страны, хотя в отдельных случаях допустимо указание и без кода страны. Должен содержать не менее 4 и не более 24 цифр, при этом, если такое допускается в рамках используемого проекта и платёжного метода, в записи номера могут использоваться знаки пунктуации и специальные символы \(подобные случаи, как правило, оговариваются отдельно\).Должен указываться для оплат с прямым использованием платёжных карт, если не указывается адрес электронной почты \(в значении параметра `customer_email`\) и не используется возможность указания таких сведений пользователем \([подробнее](ru_PP_Gathering_customer_data.md)\). Шаблон: `^[0-9]{4,24}$` Пример: `443031237300` | |`customer_security_code` string, optional |Код подтверждения платежа пользователем. Может быть актуален при работе с отдельными платёжными методами\(в соответствии с их спецификой\). Пример: `852923` | |`customer_shipping` string, optional |Информация о доставке товара или услуги пользователю.Может быть актуальна при работе с классическими карточными платежами и отдельными платёжными методами. Представляет собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя различные сведения из числа допустимых. При оплатах с использованием платёжных карт передача таких сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). - `shipping`, object — объект с информацией о доставке, который может быть актуален для классических карточных платежей и может включать в себя следующие сведения: - `address`, string — название улицы и номер дома в адресе доставки \(с обозначением корпуса или строения, где это актуально\), в виде строки длиной не более 150 символов - `address_usage`, string, `^\\d{2}-\\d{2}-\\d{4}$` — дата первого использования указанного адреса, в формате `ДД-ММ-ГГГГ` - `address_usage_indicator`, string, `^0[1-4]$` — индикатор давности первого использования указанного адреса доставки, который может принимать одно из следующих значений: - `01` — при нулевой давности \(указанный адрес используется впервые\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней - `city`, string — название города \(или иного населённого пункта\) в адресе доставки, в виде строки длиной не более 50 символов - `country`, string, `^[A-Z]{2}$` — код страны в адресе доставки в формате ISO 3166-1 alpha-2 - `delivery_email`, string — адрес электронной почты в случае доставки на этот адрес, может содержать не более 255 символов - `delivery_time`, string, `^0[1-4]$` — индикатор срока доставки, который может принимать одно из следующих значений: - `01` — в день покупки в электронном виде - `02` — в день покупки в материальном виде - `03` — на следующий день после покупки - `04` — позднее чем на следующий день после покупки - `name_indicator`, string, `^0[1-2]$` — индикатор совпадения имени пользователя с именем получателя доставки, который может принимать одно из следующих значений: - `01` — имена совпадают - `02` — имена не совпадают - `postal`, string — почтовый индекс в адресе доставки, представляет собой строку длиной не более 16 символов - `region`, string — название региона \(штата, провинции или иной территориальной области\) в адресе доставки, представляет собой строку длиной не более 255 символов - `region_code`, string, `^[0-9A-Z]{1,3}$` — внутренний код региона в адресе доставки, представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса - `type`, string, `^0[1-7]$` — индикатор варианта доставки, который может принимать одно из следующих значений: - `01` — доставка на платёжный адрес держателя карты - `02` — доставка на другой подтверждённый адрес - `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым - `04` — доставка в магазин мерчанта - `05` — доставка в электронном виде - `06` — отсутствие доставки - `07` — другой вариант ```language-json { "customer":{ "shipping":{ "type":"01", "delivery_time":"01", "delivery_email":"test@gmail.com", "address_usage_indicator":"01", "address_usage":"01-10-2022", "city":"Vilnius", "country":"LT", "address":"Dukstu street 30", "postal":"LT-071171", "region":"Vilnius County", "region_code":"VL", "name_indicator":"01" } } } ``` ``` eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAyMiIsCiAgICAgICJjaXR5IjoiTW9zY293IiwKICAgICAgImNvdW50cnkiOiJSVSIsCiAgICAgICJhZGRyZXNzIjoiTGVuaW5hIHN0cmVldCAxMiIsCiAgICAgICJwb3N0YWwiOiIxMDkxMTEiLAogICAgICAicmVnaW9uX2NvZGUiOiJSVSIsCiAgICAgICJuYW1lX2luZGljYXRvciI6IjAxIgogICAgfQogIH0KfQ==== ``` | |`customer_ssn` integer, optional |Последние 4 цифры в номере социального страхования налогоплательщика в США. Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `1984` | |`customer_state` string, optional |Название региона\(штата, провинции или иной территориальной области\) в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов.Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `Greater London` | |`customer_street` string, optional |Название улицы в адресе проживания пользователя. Представляет собой строку длиной не более 255 символов.Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `Main` | |`customer_zip` string, optional |Почтовый индекс в адресе проживания пользователя. Представляет собой строку длиной не более 10 символов.Передача этих сведений вместе с другими сведениями о пользователе может способствовать избеганию процедуры дополнения информации о платеже и упрощать пользовательский сценарий \([подробнее](ru_PP_Gathering_customer_data.md)\). Пример: `75001` | |`debt_account` string, optional |Номер счёта для получения средств в рамках оплаты с погашением задолженности пользователя. Актуален при проведении соответствующих оплат \([подробнее](ru_PP_debt_repayments.md)\).Может содержать не более 10 символов, среди которых допустимы буквы латинского алфавита и цифры. Пример: `an9876170i` | |`force_acs_new_window` integer \(boolean\*\), optional |Указатель необходимости использования отдельной вкладки при перенаправлении пользователя к стороннему сервису \([подробнее](ru_PP_redirect_modes.md)\). Может быть актуален при работе с отдельными платёжными методами и допускает следующие значения: - `0` — для перенаправления тем способом, который задан для используемого платёжного метода и применяется для него по умолчанию; - `1` — для перенаправления в отдельной вкладкенезависимо от способа, который задан для используемого платёжного метода по умолчанию. При работе с библиотекой `merchant.js` \([подробнее](ru_pp_interaction_organisation.md)\) значение этого параметра допустимо указывать как булево: `false` или `true`. Пример: `1` | |`force_payment_method` string, optional |Служебный код платёжного метода, который следует использовать в качестве предварительно выбранногодля проведения платежа \([подробнее](ru_PP__PreselectingPS.md)\). Может принимать значения в соответствии [со справочником](ru_pm_codes.md). Пример: `paypal-wallet` | |`force_payment_group` string, optional |Служебный код группы платёжных методов, которую следует использовать в качестве предварительно выбранной для проведения платежа \([подробнее](ru_PP__PreselectingPS.md)\). При указании такого кода доступными для выбора являются те методы, которые входят в указанную группу и доступны в рамках используемого проекта. Вместе с тем, при указании этого кода в одном запросе с кодом конкретного метода \(в значении параметра `force_payment_method`\) платёжная форма открывается для проведения оплаты указанным методом, без учёта выбранной группы. В настоящее время с помощью этого параметра применим выбор группы методов Open Banking — с помощью идентификатора `openbanking`. Пример: `openbanking` | |`force_payment_method_subtype` string, optional |Служебный код бренда платёжных карт, который следует использовать в качестве предварительно выбранного для проведения платежа \([подробнее](ru_PP__PreselectingPS.md)\). Может принимать значения в соответствии [со справочником](ru_card_codes.md). Пример: `mastercard` | |`hide` string, optional |Набор служебных кодов тех методов, которые следует исключить из выбора для конкретного платежа\([подробнее](ru_pp_methods_availability.md)\). Может включать в себя коды в соответствии [со справочником](ru_pm_codes.md) и с использованием запятой и пробела в качестве разделителя. Пример: `card, cup-union` | |`identify_doc_number` string, optional |Идентификатор документа, подтверждающего личность пользователя. Может быть актуален при работе с отдельными платёжными методами и с учётом специфики метода может представлять собой номер удостоверяющего личность документа, номер налогоплательщика\(как при работе с методом [PIX](pm_pix.md)\) или иные сведения подобного характера. Пример: `6543234567` | |`interface_type` string, optional |Служебный идентификатор интерфейса, используемого для проведения платежа через платёжную платформу. Может использоваться в отдельно оговариваемых случаях. Пример: `{"id":7}` | |`language_code` string, optional |Код целевого языка для отображения платёжной формы \([подробнее](ru_PP_WigetLanguages.md)\) и отправки пользователю дополнительных уведомлений о проведении платежа \([подробнее](ru_PP_receipt_data.md)\). Может представлять собой двухбуквенный код в формате ISO 639-1 alpha-2 \(согласно [справочнику](ru_language_codes.md)\) и в отдельно согласованных случаях код, не входящий в указанный стандарт. Шаблон: `/^([a-z]{2}|zh\-hant)$/i` Пример: `de` | |`merchant_callback_url` string, optional |Aдрес доставки оповещений по запросу. Актуален, когда оповещения по конкретному вызову Payment Page необходимо отправлять на специфический адрес, отличающийся от заданных по умолчанию \(подробнее об оповещениях и работе с ними — [в отдельной статье](ru_platform_callbacks.md)\). Пример: `https://cosmoshop.earth/specialorder` | |`merchant_data` string, optional |Дополнительная информация для учёта на стороне веб-сервиса. Состав сведений, передаваемых в значении этого параметра, может быть произвольным, но должен предварительно согласовываться и настраиваться для корректной обработки в платформе и представления в оповещениях и карточках платежей \([подробнее](ru_pp_additional_data.md)\). В согласованных случаях может представлять собой JSON-объект, при передаче которого методом POST требуется экранировать символ `"` \(двойной штрих, U+0022\) путём постановки перед ним символа `\` \(косой обратной черты, U+005C\), в то время как при использовании метода GET экранирование может быть необязательным. ``` {#codeblock_f2k_rv1_4fc .language-json} "merchant_data": "{"items":[{"sku":"GM12-CC", "description":"10 Copper Coins","count":1}, {"sku":"GM12-GC","description":"Golden Coin", "count":2}],"total_count":3,"user_id":"122"}" ``` ``` {#codeblock_hnr_wvd_wdc .language-json} "merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" ``` | |`merchant_descriptor` string, optional |Сведения о мерчанте для предоставления организациям, участвующим в проведении карточных платежей, и, через них, пользователям. Могут быть актуальны при проведении оплат и проверок действительности платёжных карт, при этом длина строки для карт платёжной системы Mastercard ограничивается 22 символами, а для карт платёжной системы Visa — 25 символами. Более подробная информация о работе с этими сведениями представлена [в отдельной статье](ru_pp_descriptor.md). Пример: `Cosmotour* to the Moon` | |`merchant_domain` string, optional |Доменное имя веб-сервиса, в котором необходимо открыть платёжную форму. Актуально, когда используется открытие платёжной формы с помощью встроенных кнопок Apple Pay и Google Pay \(подробнее — [в отдельной статье](ru_pp_embedded_payment_buttons.md)\). Пример: `merchant.example.com` | |`merchant_fail_enabled` integer, optional |Вариант обеспечения для пользователя доступности итогового возвращения к веб-сервису при отклонении оплаты. Может принимать одно из следующих значений: - `0` — отсутствие доступа к возможности возвращения; - `1` — частичная доступность возвращения,в рамках которой при открытии Payment Page в объекте iframe или модальном окне перенаправление к веб-сервису не выполняется, а при открытии Payment Page в отдельной вкладке браузераспособ открытия страницы веб-сервиса определяется через параметр группы `mode`; - `2` — полная доступность возвращения, используемая по умолчаниюи сочетаемая со способом открытия страницы веб-сервиса, указанным в параметре группы `mode`. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `2` | |`merchant_fail_redirect_mode` string, optional |Указатель способа, применяемого для итогового возвращения к веб-сервису по решению пользователя при отклонении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке; - `blank_page` — открытие страницыв новой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `blank_page` | |`merchant_fail_url` string, optional |Адрес для итогового возвращения к веб-сервису по решению пользователя при отклонении оплаты. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/failed` | |`merchant_return_enabled` integer, optional |Вариант обеспечения для пользователя доступности предварительного возвращения к веб-сервису со страниц платёжной формы. Может принимать одно из следующих значений: - `0` — отсутствие доступа к возможности возвращения; - `1` — частичная доступность возвращения, в рамках которой при открытии Payment Page в объекте iframe или модальном окне перенаправление к веб-сервису не выполняется, апри открытии Payment Page в отдельной вкладке браузераспособ открытия страницы веб-сервиса определяется через параметр группы `mode`; - `2` — полная доступность возвращения, используемая по умолчаниюи сочетаемая со способом открытия страницы веб-сервиса, указанным в параметре группы `mode`. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `0` | |`merchant_return_redirect_mode` string, optional |Указатель способа, применяемого для предварительного возвращения к веб-сервису со страниц платёжной формы. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке; - `blank_page` — открытие страницыв новой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `iframe` | |`merchant_return_url` string, optional |Адрес для предварительного возвращения к веб-сервису со страниц платёжной формы. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/return` | |`merchant_success_enabled` integer, optional |Вариант обеспечения для пользователя доступности итогового возвращения к веб-сервису при проведении оплаты. Может принимать одно из следующих значений: - `0` — отсутствие доступа к возможности возвращения; - `1` — частичная доступность возвращения, в рамках которой при открытии Payment Page в объекте iframe или модальном окне перенаправление к веб-сервису не выполняется, апри открытии Payment Page в отдельной вкладке браузераспособ открытия страницы веб-сервиса определяется через параметр группы `mode`; - `2` — полная доступность возвращения, используемая по умолчаниюи сочетаемая со способом открытия страницы веб-сервиса, указанным в параметре группы `mode`. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `1` | |`merchant_success_redirect_mode` string, optional |Указатель способа, применяемого для итогового возвращения к веб-сервису по решению пользователя при проведении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке; - `blank_page` — открытие страницыв новой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `parent_page` | |`merchant_success_url` string, optional |Адрес для итогового возвращения к веб-сервису по решению пользователя при проведении оплаты. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/success` | |`mode` string, optional |Указатель режима работы Payment Page. Может принимать одно из следующих значений: - `purchase` — для проведения оплатыв режиме Purchase \(этот режимиспользуется по умолчанию\); - `payout` — для проведения выплатыв режиме Payout; - `card_verify` — для проверки действительности платёжного инструментав режиме Card Verify; - `card_tokenize` — для формирования токена платёжных данныхв режиме Card Tokenize. Пример: `card_verify` | |`moto_type` integer, optional |Тип заказа для проведения оплаты категории Mail Order/Telephone Order \(с предоставлением реквизитов платёжной карты её держателем по телефону, почте, факсимильной связи или электронной почте\): - `1` — Mail Order; - `2` — Telephone Order. Пример: `2` | |`operation_type` string, optional |Указатель варианта проведения оплаты— в одну или две стадии. Актуален в тех случаях, когда необходимо использовать вариант, отличный от заданного по умолчанию. Может принимать одно из следующих значений: - `sale` — для оплатыв одну стадию \(с незамедлительным списанием средств;[подробнее](ru_pp_purchase.md)\); - `auth` — для оплатыв две стадии \(с предварительной блокировкой и последующим списанием средств;[подробнее](ru_pp_purchase_auth.md)\). Пример: `auth` | |`payment_amount` integer, required\* |Сумма платежа. Приводится в дробных единицах валюты без десятичного разделителя.Не используется в режиме Card Tokenize, в остальных случаях обязательна. Пример: `1815`\(для суммы 18,15 при использовании валюты с двумя дробными разрядами\) | |`payment_cryptocurrency_type` string, optional |Указатель категории цифровой валюты. Обязателен при выполнении операций, связанных с использованием криптовалют в рамках сервисов Mastercard MoneySend и Visa Direct. Может принимать одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. Пример: `cbdc` | |`payment_currency` string, required\* |Трёхбуквенный код валюты платежа. Указывается в формате ISO-4217 alpha-3, согласно [справочнику](ru_currency_codes.md). Не используется в режиме Card Tokenize, в остальных случаях обязателен. Шаблон: `^[A-Z]{3}$` Пример: `EUR` | |`payment_description` string, optional |Краткое описание платежадля отображения пользователю и учёта на стороне веб-сервиса. Представляет собой строку длиной не более 255 символов. Может отображаться пользователю на странице с информацией о результате выполнения операции и быть доступным на стороне веб-сервиса через программные оповещения и интерфейс Dashboard. Пример: `Thai massage session` | |`payment_extra_param` string, optional |Дополнительная информация, актуальная для проведения платежа. Может быть уместной при работе с отдельными платёжными методами и в иных специфических случаях. Как правило, уместность и способы использования этого параметра, а также форматы передаваемых в нём данных согласовываются отдельно, на этапе технической интеграции веб-сервиса с платформой Ecommpay или при подключении дополнительных методов и возможностей. | |`payment_id` string, required\* |Идентификатор платежа. Должен задаваться на стороне веб-сервиса и представлять собой строку длиной не более 255 символов с обеспечением регистронезависимости и уникальности в рамках используемого проекта.Не используется в режиме Card Tokenize, в остальных случаях обязателен. Пример: `payment_443` | |`payment_merchant_risk` string, optional |Дополнительные сведения об оплате товара или услуги пользователем и о предпочтительном для мерчанта варианте аутентификации 3‑D Secure. Представляют собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя различные сведения из числа допустимых. При оплатах с использованием платёжных карт передача этих сведений вместе с другими сведениями о пользователе может повышать вероятность аутентификации 3‑D Secure без участия пользователя \(с уходом от варианта challenge flow к варианту frictionless flow; [подробнее](ru_pp_3ds.md)\). - `challenge_indicator`, string, `^0[1-9]$` — указатель предпочтения по использованию варианта аутентификации challenge flow, может принимать следующие значения: - `01` — без предпочтений - `02` — предпочтительно не выполнять - `03` — предпочтительно выполнять - `04` — обязательно выполнять - `05` — не выполнять, анализ рисков выполнен на стороне мерчанта - `06` — не выполнять, применить сценарий Data Only - `07` — не выполнять, Strong Customer Authentication уже выполнена иным способом - `08` — не выполнять, мерчант включен в список доверенных для этого пользователя - `09` — обязательно выполнять, предпочтительно предложить пользователю добавить мерчанта в список доверенных - `challenge_window`, string, `^0[1-5]$` — размер окна для открытия страницы аутентификации, может принимать следующие значения: - `01` — 250 x 400 пикселей - `02` — 390 x 400 пикселей - `03` — 500 x 600 пикселей - `04` — 600 x 400 пикселей - `05` — полноэкранный режим - `gift_card`, object — объект с информацией об оплате предоплаченными или подарочными картами: - `amount`, integer — общая сумма оплаты предоплаченными или подарочными картами в минорных единицах валюты - `count`, integer — количество предоплаченных или подарочных карт, использованных для оплаты - `currency`, string — код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 - `preorder_date`, string, `^\\d{2}-\\d{2}-\\d{4}$` — планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ` - `preorder_purchase`, string, `^0[1-2]$` — индикатор предварительного заказа, может принимать следующие значения: - `01` — не является предварительным заказом - `02` — является предварительным заказом - `reorder`, string, `^0[1-2]$` — индикатор первичной или повторной покупки данного товара или услуги пользователем, может принимать следующие значения: - `01` — первичная покупка - `02` — повторная покупка ```language-json { "payment":{ "reorder":"01", "preorder_purchase":"01", "preorder_date":"11-10-2022", "challenge_indicator":"01", "challenge_window":"01", "gift_card":{ "amount":12345, "currency":"USD", "count":1 } } } ``` ``` eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIxMS0xMC0yMDIyIiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9== ``` | |`payment_methods_options` string, optional |Дополнительные сведения, актуальные при работе с отдельными платёжными методами и сторонними сервисами. Могут быть актуальны для управления возможностями выбора отдельных методови банков, для передачи дополнительных сведений о пользователе и платеже, для управления размерами страниц сторонних сервисов при перенаправлении к ним и для других целей — в соответствии со спецификой используемых платёжных методов. Пример: `{\"online_thailand_banks\": {\"split_banks\": true}}` | |`project_id` integer, required |Идентификатор проектавзаимодействия веб-сервиса с платёжной платформой, полученный от Ecommpayпри интеграции \([подробнее](ru_glossary.md)\). Пример: `57123` | |`receipt_data` string, optional |Информация о товарных позициях оплачиваемого заказа. Может использоваться для отправки пользователю \([подробнее](ru_PP_receipt_data.md)\).Представляют собой строку, полученную в результате кодирования исходного JSON-объекта с применением алгоритма Base64.Этот объект может включать в себя различные сведения из числа допустимых. - `positions`, array — массив, в котором можно перечислить до 300 товарных позиций; для каждой товарной позиции указывается следующее: - `amount`, integer — стоимость товара - `quantity`, integer — количество товарных единиц - `tax`, integer — ставка налога на добавленную стоимость \(НДС\), если она отличается для разных товарных позиций - `tax_amount`, integer — сумма налога на добавленную стоимость \(НДС\) - `description`, string — произвольное описание товара - `total_tax_amount`, integer — общая сумма НДС за всю покупку - `common_tax`, integer — ставка налога на добавленную стоимость \(НДС\), если она одинаковая для всех товарных позиций ``` {#codeblock_jg4_sj2_wdc .language-json} { "receipt_data":{ "positions":[ { "quantity":3, "amount":10000, "tax":18, "tax_amount":1800, "description":"Рамка с дизайном" } ], "total_tax_amount":1800, "common_tax":18 } } ``` ``` {#codeblock_trx_sj2_wdc} receipt_data: "eyAgCiAgICAgICJwb3NpdGlvbnMiOlsgIAogICAgICAgICB7ICAKICAgICAgICAg ICAgInF1YW50aXR5IjozLAogICAgICAgICAgICAiYW1vdW50IjoxMDAwMCwKICAgICAgICAgICAgInRheCI6MTgsCiAg ICAgICAgICAgICJ0YXhfYW1vdW50IjoxODAwLAogICAgICAgICAgICAiZGVzY3JpcHRpb24iOiLQoNCw0LzQutCwING BINC00LjQt9Cw0LnQvdC+0LwiCiAgICAgICAgIH0KICAgICAgXSwKICAgICAgInRvdGFsX3RheF9hbW91bnQiOjE4MDAs CiAgICAgICJjb21tb25fdGF4IjoxOCAgICAgICAKfQ" ``` | |`recipient_address` string, optional |Название улицы и номер дома\(с обозначением корпуса или строения, где это актуально\) в адресе местонахождения получателя платежа. Представляют собой строку длиной не более 99 символов и являютсяобязательными при выполнении операций Visa Direct, когда передаются в запросе на выполнение списания с карты, выпущенной в Австралии, Канаде или Новой Зеландии. Пример: `Via Dietro Duomo 36` | |`recipient_card_holder` string, optional |Имя и фамилия держателя платёжной карты, используемой получателем платежа. Должны соответствовать написанию, используемому непосредственно на карте, а также общим требованиям к написанию \([подробнее](ru_faq_payment_processing.md)\), не превышая при этом 255 символов. Пример: `Fran Petrarca` | |`recipient_city` string, optional |Название города \(или иного населённого пункта\) в адресе местонахождения получателя платежа. Представляет собой строку длиной не более 25 символов. Пример: `Padova` | |`recipient_country` string, optional |Код страны в адресе местонахождения получателя платежа. Указывается в формате ISO 3166-1 alpha-2. Шаблон: `^[A-Z]{2}$` Пример: `IT` | |`recipient_day_of_birth` string, optional |Дата рождения получателя платежа. Должна указываться в формате `ДД-ММ-ГГГГ` при использовании получателем карты Visa. Шаблон: `^\\d{2}-\\d{2}-\\d{4}$` Пример: `12-12-1990` | |`recipient_first_name` string, optional |Имя получателя платежа. Представляет собой строку длиной не более 255 символов. Пример: `Fran` | |`recipient_last_name` string, optional |Фамилия получателя платежа. Представляет собой строку длиной не более 255 символов. Пример: `Petrarca` | |`recipient_pan` string, optional |Номер платёжной карты, используемой получателем платежа. Должен указываться в явном виде, без маскирования и без пробелов и иных разделительных символов. Шаблон: `^[0-9]{15,19}$` Пример: `4314220000000056` | |`recipient_state` string, optional |Внутренний код региона\(штата, провинции или иной территориальной области\) в адресе местонахождения получателя выплаты \([подробнее](ru_Gate_payout.md)\). Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, и является применимым при проведении выплат, когда передаётся в одном запросе с кодом страны в значении параметра `recipient_country` и когда код страны соответствует Канаде \(`CA`\) или США \(`US`\). Шаблон: `^[A-Z]+$` Пример: `AK`\(для Аляски, с полным кодом `US-AK`\) | |`recipient_state_code` string, optional |Внутренний код региона\(штата, провинции или иной территориальной области\) в адресе местонахождения получателя перевода с использованием сервиса Mastercard MoneySend или Visa Direct \([подробнее](ru_gate_money_transfer_services.md)\). Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, и является применимым при выполнении операций Mastercard MoneySend и Visa Direct, когда передаётся в одном запросе с кодом страны в значении параметра `recipient_country` и когда код страны соответствует Канаде \(`CA`\) или США \(`US`\). Шаблон: `^[A-Z]+$` Пример: `ON`\(для Онтарио, с полным кодом `CA-ON`\) | |`recipient_wallet_id` string, optional |Идентификатор электронного кошелька, используемого получателем платежа. Представляет собой строку длиной не более 64 символов. Должен указываться в явном виде, без маскирования и без дополнительных пробелов и иных разделительных символов. Шаблон: `^[^!@&~№{}|<>\\[\\]]*$` Пример: `WID20071304` | |`recipient_wallet_owner` string, optional |Имя и фамилия владельца электронного кошелька, используемого получателем платежа. Должны соответствовать написанию, заданному в платёжной системе, не превышая при этом 255 символов. Шаблон: `/^[\p{L}\p{M}0-9 .'-]+$/u` Пример: `Fran Petrarca` | |`recurring` string, optional |Сведения о регистрируемой повторяемой оплате \([подробнее](ru_pp_recurring.md)\). При использовании JavaScript-библиотеки Ecommpay могут представлять собой JSON-объект, в других случаях должны указываться в виде URL-строки\(полученной из исходного JSON-объекта с помощью преобразования URL-encoding\). - `register`, boolean — указатель необходимости зарегистрировать повторяемую оплату - `type`, string, `^[RCU]$` — категория регистрируемой повторяемой оплаты, с одним из следующих значений: - `R` — для регулярной оплаты - `C` — для экспресс-оплаты - `U` — для автооплаты - `period`, string, `^[DWMQY]$` — указатель базового периода списаний \(для регулярной оплаты\), с одним из следующих значений: - `D` — ежедневно - `W` — еженедельно - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\) - `Q` — ежеквартально - `Y` — ежегодно - `amount`, integer — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты - `interval`, integer — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100` - `time`, string, `^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$` — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс` - `start_date`, string, `^([0-3]\\d-){2}[1-2]\\d{3}$` — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ` - `expiry_day`, integer илиstring — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\) - `expiry_month`, integer илиstring — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\) - `expiry_year`, integer — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\) - `scheduled_payment_id`, string — идентификатор платежа, в рамках которого следует выполнять списания \(должен отличаться от идентификатора платежа, который используется для регистрации повторяемой оплаты и указывается в параметре `payment_id`\) ```language-json { "register": true, "type": "U" } ``` ```language-json %7B%22register%22%3Atrue%2C%22type%22%3A%22U%22%7D%2C ``` | |`redirect` integer \(boolean\*\), optional |Указатель необходимости открытия платёжной формы в виде отдельной HTML-страницы независимо от типа используемого устройства \([подробнее](ru_PP_method_NewTab.md)\). Может принимать следующие значения: - `0` — для открытияплатёжной формы тем способом, который используется по умолчанию или задан через другие параметры; - `1` — для открытияплатёжной формы в виде отдельной HTML-страницы. При работе с библиотекой `merchant.js` \([подробнее](ru_pp_interaction_organisation.md)\) значение этого параметра допустимо указывать как булево: `false` или `true`. Пример: `1` | |`redirect_fail_mode` string, optional |Указатель способа, применяемого для автоматического итогового возвращения пользователя к веб-сервису при отклонении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке; - `blank_page` — открытие страницыв новой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `blank_page` | |`redirect_fail_url` string, optional |Адрес для автоматического итогового возвращения пользователя к веб-сервису при отклонении оплаты. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/failed` | |`redirect_on_mobile` integer \(boolean\*\), optional |Указатель необходимости открытия платёжной формы в виде отдельной HTML-страницы на мобильных устройствах \([подробнее](ru_PP_method_NewTab.md)\). Может принимать следующие значения: - `0` — для открытияплатёжной формы тем способом, который используется по умолчанию или задан через другие параметры; - `1` — для открытияплатёжной формы в виде отдельной HTML-страницы. При работе с библиотекой `merchant.js` \([подробнее](ru_pp_interaction_organisation.md)\) значение этого параметра допустимо указывать как булево: `false` или `true`. Пример: `1` | |`redirect_success_mode` string, optional |Указатель способа, применяемого для автоматического итогового возвращения пользователя к веб-сервису при проведении оплаты. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке; - `blank_page` — открытие страницыв новой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `parent_page` | |`redirect_success_url` string, optional |Адрес для автоматического итогового возвращения пользователя к веб-сервису при проведении оплаты. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/success` | |`redirect_return_url` string, optional |Адрес для промежуточного возвращения к веб-сервису со страниц сторонних сервисов, таких как сервисы банков или платёжных систем. Может использоваться при работе с отдельными сервисами после согласования и подключения такой функциональности. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/third_party_services` | |`redirect_tokenize_mode` string, optional |Указатель способа, применяемого для автоматического итогового возвращения пользователя к веб-сервису при формировании токена платёжных данных в режиме Card Tokenize. Может принимать одно из следующих значений: - `iframe` — открытие страницыв объекте iframe \(работающее при открытии платёжной формы в объекте iframe или модальном окне; при открытии платёжной формы в отдельной вкладке этот способ ведёт к перенаправлению в этой же вкладке\); - `parent_page` — открытие страницыв используемой вкладке. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `parent_page` | |`redirect_tokenize_url` string, optional |Адрес для автоматического итогового возвращения пользователя к веб-сервису при формировании токена платёжных данных в режиме Card Tokenize. Подробнее об управлении возможностями возвращения пользователей к веб-сервису — [в отдельной статье](ru_PP_redirect_modes.md). Пример: `https://cosmoshop.jupiter.example/pages/tokenize` | |`region_code` string, optional |Код страны местонахождения пользователя. Указывается в формате ISO 3166-1 alpha-2. В случаях, когда этот код не указывается, страна может определяться по IP-адресу пользователя или иным параметрам. Шаблон: `^[A-Z]{2}$` Пример: `FR` | |`sender_address` string, optional |Название улицы и номер дома\(с обозначением корпуса или строения, где это актуально\) в адресе местонахождения отправителя платежа. Представляет собой строку длиной не более 99 символов. Пример: `Via Certaldo 18` | |`sender_city` string, optional |Название города \(или иного населённого пункта\) в адресе местонахождения отправителя платежа. Представляет собой строку длиной не более 25 символов. Пример: `Florence` | |`sender_country` string, optional |Код страны в адресе местонахождения отправителя платежа. Указывается в формате ISO 3166-1 alpha-2. Шаблон: `^[A-Z]{2}$` Пример: `IT` | |`sender_descriptor` string, optional |Сведения о мерчанте для предоставления организациям, участвующим в проведении карточных платежей, и, через них, пользователям. Могут быть актуальны при проведении выплат, при этом длина строки для карт платёжной системы Mastercard ограничивается 22 символами, а для карт платёжной системы Visa — 25 символами. Более подробная информация о работе с этими сведениями представлена [в отдельной статье](ru_pp_descriptor.md). Пример: `Cosmotour* to the Moon` | |`sender_first_name` string, optional |Имя отправителя платежа. Представляет собой строку длиной не более 255 символов. Пример: `Gio` | |`sender_last_name` string, optional |Фамилия отправителя платежа. Представляет собой строку длиной не более 255 символов. Пример: `Boccaccio` | |`sender_state` string, optional |Внутренний код региона\(штата, провинции или иной территориальной области\) в адресе местонахождения отправителя платежа. Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, и является применимымв тех случаях, когда передаётся в одном запросе с кодом страны в значении параметра `sender_country`. Пример: `52`\(для Тосканы, с полным кодом IT‑52\) | |`sender_wallet_id` string, optional |Идентификатор электронного кошелька, используемого отправителем платежа. Представляет собой строку длиной не более 64 символов. Должен указываться в явном виде, без маскирования и без дополнительных пробелов и иных разделительных символов. Пример: `WID16061313` | |`sender_zip` string, optional |Почтовый индекс в адресе местонахождения отправителя платежа. Представляет собой строку длиной не более 255 символов. Пример: `50142` | |`signature` string, required |Цифровая подпись к параметрам запроса. Должна составляться после указания всех целевых параметров в соответствии с заданным алгоритмом \([подробнее](ru_platform_signature.md)\). | |`style_id` integer, optional |Идентификатор стиля оформления платёжной формы. Может использоваться при работе с различными стилями оформления Payment Page \([подробнее](ru_PP__design_customisation.md)\). Пример: `6123` | |`target_element` string, optional |Идентификатор элемента iframe \(в рамках HTML-страницы веб-сервиса\), в котором необходимо открыть платёжную форму \([подробнее](ru_PP_method_Embedded.md)\). Пример: `widget-container` | |`uuid` string, optional |Служебный идентификатор. Представляет собой строку длиной не более 64 символов.Может использоваться при вызове платёжной формы в режиме Payout \(со значением, полученным в оповещении о регистрации выплаты; [подробнее](ru_pp_payout.md)\). Пример: `Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==` | **На уровень выше:**[Payment Page](ru_PP_about.md) --- # Gate {#ru_Gate_Integration_About .concept} раздел с материалами о работе с программным интерфейсом Gate В этом разделе представлены материалы о работе с интерфейсом Gate. ## Обзор {#section_t4l_zyk_qtb .section} Вводная статья с информацией об интерфейсеи основных действиях, доступных при работе с ним — [Общая информация](ru_Gate_How_to_Integrate.md). ## Интеграция {#section_gdj_s1l_qtb .section} Материалы о том, как организовать работу с платёжной платформой Ecommpay через Gate: - [Быстрый старт](ru_gate_quickstart.md)— о том, как оперативно обеспечить приём платежей и работу с другими возможностями, используя примеры кода на языках программирования PHP и Go. - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как выстроить работу с платёжной платформой через Gate, опираясь на используемые схемы и форматы взаимодействия. ## Основные действия {#section_twd_gmq_qtb .section} Материалы об основных действиях, которые доступны при работе через Gate, с описанием ключевых особенностей, схем проведения и форматов запросов и оповещений: - [Разовые оплаты](ru_Gate_purchase.md)— о проведении оплат с незамедлительным списанием средств\([в одну стадию](ru_gate_payment_sale.md)\) и со списанием после предварительной блокировки \([в две стадии](ru_gate_payment_auth.md)\). - [Оплаты по платёжным ссылкам](ru_gate_invoice.md)— о проведении оплатв одну и две стадии с использованием платёжных ссылок и перенаправлением пользователей к платёжной форме Payment Page. - [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md)— о регистрации и проведении оплат с последующими списаниями. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о возвратах пользователям средств, которые были списаны ранее в рамках тех или иных оплат. - [Выплаты](ru_Gate_payout.md)— о проведении выплат с переводом средств от мерчанта к пользователю. - [Проверка платёжных инструментов](ru_gate_account_verification.md)— о выполнении условного списания или блокировки средств с целью проверки действительности платёжного инструмента. ## Процедуры и дополнения {#section_adb_s3r_qtb .section} Материалы о различных процедурах и возможностях, которые могут использоваться при проведении платежей через Gate: - [Вспомогательные процедуры](ru_gate_procedures.md)— о процедурах, которые могут быть обязательны при проведении отдельных платежей. - [Дополнительные возможности](ru_Gate_Additional_capabilities.md)— о возможностях, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг. ## Спецификация API {#section_lxd_hbl_qtb .section} Спецификация интерфейса с описанием структур данныхв программных запросах и ответах — [Спецификация Gate API](https://api-developers.ecommpay.com/). - **[Общая информация](ru_Gate_How_to_Integrate.md)** статья с вводной информацией об интерфейсе Gate и его возможностях - **[Быстрый старт](ru_gate_quickstart.md)** инструкция по оперативной организации приёма платежей через Gate, с использованием примеров исходного кода на PHP и Go - **[Организация взаимодействия](ru_gate_interaction_organisation.md)** статья о том, как строится работа с платёжной платформой через Gate и как можно организовывать эту работу со стороны веб-сервиса, опираясь на используемые схемы и форматы взаимодействия - **[Разовые оплаты](ru_Gate_purchase.md)** статьи о порядке проведения через Gate разовых оплат с незамедлительными списаниями \(в одну стадию\) и со списаниями после предварительных блокировок средств \(в две стадии\) - **[Оплаты по платёжным ссылкам](ru_gate_invoice.md)** статья о порядке проведения через Gate оплат в одну и две стадии с использованием платёжных ссылок и перенаправлением пользователей к платёжной форме Payment Page - **[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md)** статьи о порядке регистрации и проведения через Gate различных категорий оплат с сериями повторяемых списаний, а также о возможностях управления списаниями в рамках таких оплат - **[Возвраты средств после оплат](ru_Gate_Refund.md)** статья о порядке выполнения через Gate возвратов по проведённым ранее оплатам разных типов - **[Выплаты](ru_Gate_payout.md)** статья о порядке проведения через Gate выплат - **[Проверка платёжных инструментов](ru_gate_account_verification.md)** статья о порядке проверки через Gate действительности платёжных инструментов с условными списаниями или временными блокировками средств - **[Вспомогательные процедуры](ru_gate_procedures.md)** статьи о вспомогательных процедурах, которые могут быть обязательны при проведении отдельных платежей через Gate - **[Дополнительные возможности](ru_Gate_Additional_capabilities.md)** статьи о дополнительных возможностях Gate, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг - **[Gate API](gate_api.md)** спецификация Gate API с описанием моделей и структур данных для формирования запросов к различным конечным точкам --- # Общая информация {#ru_Gate_How_to_Integrate .concept} статья с вводной информацией об интерфейсе Gate и его возможностях Gate является одним из интерфейсов для работы с платёжной платформой Ecommpayи предоставляет наиболее полные возможности для взаимодействия на программном уровне. Через Gate можно проводить разовые и повторяемые оплаты, возвраты ивыплаты, а также получать дополнительную информацию, например, о статусе платежа.При этом Gate может использоваться и как единственная «точка входа», и как одна из, например, при проведении оплат через Payment Page, а возвратов и выплат — через Gate. Gate позволяет проводить платежи с прямым использованием платёжных карти с использованием альтернативных платёжных методов \(подробнее — в разделе [Методы](ru_pm_about.md)\). При этом поддерживается прямая работа с картами платёжных систем American Express, Mastercard и Visaи опосредованная работа \(через сервисы партнёров в рамках альтернативных платёжных методов\) с картами ряда других платёжных систем. Для проведения платежей через Gate на стороне веб-сервиса требуется обеспечить взаимодействие с пользователями через собственный платёжный интерфейс.И для работы с платёжными картами через такой интерфейс необходимо соблюдение требований PCI DSS \(за информацией о необходимых документах можно обращаться к курирующему менеджеру Ecommpay\). ![](images/ru_gate_scheme_1.svg) В общем случае при проведении платежа от веб-сервиса к платёжной платформе отправляется запрос на «точку входа» — Gate. Далее он поступает в платформу, обрабатывается в ней и перенаправляется в платёжную среду для проведения платежа, которое завершается отправкой к веб-сервису оповещения с конечным результатом. В данном разделе представлена следующая информация: - [Организация взаимодействия](ru_gate_interaction_organisation.md) — о порядке интеграции через Gate и технических аспектах взаимодействия между веб-сервисом и платёжной платформой: схемах взаимодействия, форматах запроса, ответа и оповещения. - [Проведение платежей](ru_platform_payment_model.md) — о типах поддерживаемых платежей, о схемах проведения и возможных статусах платежей, а также о связанных с платежами информационных объектах: запросах и операциях. - Разделы [Разовые оплаты](ru_Gate_purchase.md), [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md), [Выплаты](ru_Gate_payout.md), [Проверка платёжных инструментов](ru_gate_account_verification.md) — о технических аспектах проведения платежей. - Другие разделы о работе через Gate. **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Быстрый старт {#ru_gate_quickstart} инструкция по оперативной организации приёма платежей через Gate, с использованием примеров исходного кода на PHP и Go **На уровень выше:**[Gate](ru_Gate_Integration_About.md) ## Введение {#ru_gate_quickstart_overview} Эта инструкция — о том, как организовать проведение платежей через программный интерфейс Gate платёжной платформы Ecommpay. С тем, чтобы использовать свой пользовательский интерфейс и обеспечивать максимальное взаимодействие с пользователями на стороне веб-сервиса, а все взаимодействия с платёжной платформой выполнять на программном уровне, „под капотом“. И чтобы при этом можно было применять проверенные быстрые решения — с чёткими инструкциями и примерами кода на популярных языках программирования — PHP и Go. В рамках этой инструкции рассматриваются действия, необходимые для проведения наиболее востребованного вида платежей — оплат в одну стадиюс прямым использованием платёжных карт, — а также действия, необходимые для выполнения возвратов по таким оплатам.Поддержка этих функциональных возможностей, как правило, оптимальна для первичного тестирования и быстрого запуска платёжных проектов в работу. Кроме того, поддержав эти возможности, можно довольно легко поддержать и любые другие, поскольку в основе работы с любыми типами платежейи платёжными методами, поддерживаемыми в платформе, лежат те же принципы и во многом те же процедуры, что и в основе работы с одностадийными карточными оплатами. Если вам не актуальны оплаты через Gate и требуется настроить лишь работу с возвратами или выплатами, можно освоить с помощью этой инструкции работу с подписью, ответами и оповещениями и перейти после этого к реализации соответствующих [дополнений](ru_gate_quickstart.md).Если актуально использовать Gate лишь для контроля состояния отдельных платежей, можно освоить здесь работу с подписью и перейти к статье [Получение информации о состоянии платежа](ru_Gate_payment_status_request.md). И наконец, если актуально что-то принципиально другое, можно сориентироваться в соответствующих вариантах. - Если надо настроить решения с использованием платёжной формы Ecommpay на сайтахи в мобильных приложениях, можно обратиться к разделам [Payment Page](ru_PP_about.md) и [Интеграция с использованием SDK](ru_sdk_overview.md). - Если надо настроить оплаты с вызовом платёжной формы Ecommpay по платёжным ссылкам, можно освоить с помощью этой инструкции работу с подписью, ответами и оповещениями и перейти после этого к соответствующей статье: [Оплата по платёжной ссылке](ru_platform_invoice_model.md). Кроме того, оплаты по ссылкам можно инициировать и вручную, через интерфейс Dashboard, предназначенный для сотрудников мерчантов \([подробнее](ru_dbl_payments.md)\). - Если надо настроить получение через программный интерфейс информации об операциях, опротестованиях и балансах, следует обратиться к разделу о работе с интерфейсом [Data API](ru_dbl_api_protocol.md). - Наконец, если актуально что-то ещё, можно обратиться к другим разделам настоящей документации и к специалистам Ecommpay. **Прим.:** Отдельно можно отметить, что наряду с техническими вопросами для начала проведения платежей через Gate необходимо решить и организационные, в том числе вопросы о соответствии требованиям PCI DSS, если планируется проводить платежи с использованием платёжных карт. Информацию об этом можно найти в статье [Организация взаимодействия](ru_gate_interaction_organisation.md). На этом с вводными всё. Можно переходить к делу. ## Краткая теория {#ru_gate_quickstart_theory} ### Проекты и ключи {#section_rsb_xlg_fvb .section} Работу с платёжной платформой Ecommpayможно сравнить с использованием услуг гостиницы. Так, для заселения в гостиницу обычно необходимо получить номер и ключ от него, а для начала работы с платформой надо получить... *проект и ключ* от него. И как с номерами в гостиницах, в платформе может предоставляться разное количество проектов для одного клиента — под разные цели и задачи — при этом для каждого проекта \(как и для каждого гостиничного номера\) необходим свой ключ. Как правило, для работы достаточно одного тестового и одного рабочего проектов. Это типичный случай, и в рамках быстрого старта мы исходим из него. Если вам по какой-либо причине необходимо больше проектов, это стоит обсудить с курирующим менеджером, но начать всё также можно с одного тестового проекта. Если у вас уже есть идентификатор тестового проекта \(`project_id`\) и секретный ключ для него \(`secret_key`\), можно приготовиться к их использованию и переходить дальше. Если же вы ещё не бронировали тестовый проект, самое время сделать это[через заявку](https://ecommpay.com/sign-up/) на основном сайте компании и вернуться сюда. ### Схема работы {#section_ftf_5jw_v5b .section} Чтобы корректно проводить платежи через Gate, необходимо обеспечить сбор актуальных параметров, формирование и отправку к платёжной платформе соответствующих запросов и приём и обработку ответной информации от платформы. При этом все взаимодействия с пользователями\(для сбора и отображения релевантной информации\) должны обеспечиваться на стороне веб-сервиса с использованием собственных решений, в то время как все остальные процедуры \(для обработки используемой информации\) можно реализовывать на основе представленных далее примеров кода. Если сфокусировать внимание на технических аспектах для веб-сервиса и платёжной платформы, то проведение оплаты можно представить следующим образом. | |В веб‑сервисе|В платёжной платформе| |--|-------------|---------------------| |1|При готовности пользователя оплатить заказ получаем все необходимые данные, фиксируем параметры платежа и подписываем их, после чего формируем запрос на проведение платежа и отправляем его в платёжную платформу|–| |2|Информируем пользователя о том, что платёж проводится|Принимаем запрос и работаем по нему, чтобы провести платёж. Если актуально, отправляем оповещение о необходимых действиях| |3|Если актуально, принимаем оповещение о необходимых действиях, выполняем эти действия \(с участием пользователя или без него\) и отправляем в платёжную платформу запрос на продолжение платежа|–| |4|Информируем пользователя о том, что платёж проводится|Если актуально, принимаем дополнительный запрос и выполняем необходимые действия для продолжения платежа, после чего отправляем к веб-сервису оповещение о результате платежа| |5|Принимаем оповещение с информацией о результате платежа и отображаем пользователю необходимые сведения|–| При работе с платежами других типов выполняемые действия могут отличаться, но в целом схема соответствует приведённой. Реализовывать её на стороне веб-сервиса можно самыми разными способами.Здесь, в рамках быстрого старта, описываются базовые процедуры, которые можно использовать и адаптировать в соответствии со спецификой вашего веб-сервиса. ### Параметры запросов {#section_m14_wkn_w5b .section} Обязательный набор параметров, необходимых для проведения конкретного платежа, может отличаться в зависимости от типа этого платежа, спецификиплатёжного метода и платёжной системы, региональных особенностей и других факторов. Так, в каких-то случаях может требоваться указывать назначение платежа, адрес пользователя или другую информацию, в то время как в других случаях эти сведения могут быть необязательны. Поэтому при настройке работы с разными типами платежейи платёжными методами следует обращаться к соответствующим статьям настоящей документации и к спецификации Gate API. Для проведения карточной оплаты в базовом случае следует определиться с её суммой и валютой, добавить к этим двум параметрам три идентификатора \(проекта, платежа и пользователя\) и данные платёжной карты, а затем сформировать подпись к этим параметрам. **Прим.:** Данные карт могут указываться в явном виде, а также через стандартизированные токены и произвольные идентификаторы ранее сохранённых данных. Если соответствующие токены и идентификаторы ещё не созданы или информация о картах не перенесена в платформу Ecommpay от другого провайдера, то сначала следует выполнить действия, необходимые для их создания. К этому можно приступить после настройки проведения оплат, их первичного тестирования и запуска — то есть после выполнения основных действий, описанных в этой инструкции. Если данные карты указываются в явном виде, то к числу обязательных параметров относятся следующие. |Параметр|Описание| |--------|--------| |`general` — объект, содержащий параметры с основными идентификационными сведениями запроса| |`project_id` integer |Идентификатор проекта. Его вместе с ключом выдаёт Ecommpay, и его важно точно указывать даже в тестовых запросах. Иначе… стоит ждать реакцию, как при попытке зайти в чужой гостиничный номер. Пример: `42 ` | |`payment_id` string |Идентификатор платежа. Он может быть произвольным, но каждый раз должен быть уникальным в рамках используемого проекта. Иначе стоит ждать ошибку обращения. Пример: `Cosmoshop_purchase_2025-01-01_000001` | |`signature` string |Подпись к параметрам запроса. Она формируется в соответствии со специальным алгоритмом, описанным далее. При этом для тестового проекта следует использовать тестовый ключ, для рабочего — рабочий. Пример: `rnv1OS3PJUKEJ5kw5wqoK0ftZGSd4Q6LX5A5NxK6d5alpND4sQTRFt7/9aFV+m3SRwNB8ba98GMsOY91yTVhEQ==` | |`payment` — объект, содержащий параметры с основными сведениями о платеже| |`payment_amount` integer |Сумма платежа. В тестовых запросах может быть произвольной, а в реальных должна точно соответствовать сумме заказа. Приводится в дробных единицах валюты. Пример: `8855` \(для суммы `88,55`\) | |`payment_currency` string |Код валюты платежа. Приводится в трёхбуквенном формате ISO 4217 alpha-3.В тестовых запросах могут использоваться любые из действующих кодов, а в реальных каждый раз должен использоваться код той валюты, в которой инициируется платёж. Для сверки можно использовать [справочник валют](ru_currency_codes.md). Пример: `USD` | |`customer` — объект, содержащий параметры с основными сведениями о пользователе| |`customer_id` string |Идентификатор пользователя в веб-сервисе.Может быть произвольным и повторяемым в разных запросах, но для каждого реального пользователя должен быть однозначно сопоставляемым с его учётной записью в веб-сервисе и уникальным в рамках проекта.Иначе возможны различные коллизии, в том числе при оценке рисков проведения платежей. Пример: `17008 ` | |`ip_address` string |`ip_address`IP-адрес пользователя.В тестовых запросах можно указывать IP-адрес мерчанта, в рабочих запросах каждый раз должен указываться IP-адрес, с которого пользователь инициирует оплату. Пример: `248.121.176.220` | |`card` — объект, содержащий параметры со сведениями о платёжной карте пользователя| |`pan` string |Номер платёжной карты.В тестовых запросах можно указывать любые реалистичные значения, в том числе специальные, приведённые [далее](ru_gate_quickstart.md); в рабочих запросах должны использоваться реальные данные. Пример: `4242424242424243` | |`year` string |Порядковый номер года, в котором истекает срок действия карты, в формате `ГГГГ`.В тестовых запросах можно указывать произвольные значения, но в корректном формате и так, чтобы срок действия был актуален; в рабочих запросах должны использоваться реальные данные. Пример: `2025` | |`month` string |Порядковый номер месяца, в котором истекает срок действия карты, в виде числа от 1 до 12.В тестовых запросах можно указывать произвольные значения, но в корректном формате и так, чтобы срок действия был актуален; в рабочих запросах должны использоваться реальные данные. Пример: `5` | |`card_holder` string |Имя пользователя, в соответствии с указанным на карте и с учётом применяемых [ограничений](ru_faq_payment_processing.md#fig_hgj_jds_4nb), если этот параметр обязателен для используемого проекта \(исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\). В тестовых запросах можно указывать произвольные значения; в рабочих запросах должны использоваться реальные данные. Пример: `SONYA KOVALEVSKY` | |`cvv` string |Код проверки подлинности карты, в соответствии с указанным на карте или полученным держателем от эмитента.В тестовых запросах можно указывать произвольные значения из трёх цифр; в рабочих запросах должны использоваться реальные данные. Пример: `345` | В запросе такой набор параметров может выглядеть следующим образом. ```language-json { "general": { "project_id": 42, "payment_id": "Cosmoshop_purchase_2025-01-01_000001", "signature": "rdCiqlibt8SUMe3OVPNfKMYnQjQ6dkEvRQhMkJRg9ZJULdsKJEZU21E5Y/ISdv0FtXi3oJE5n4hSNK3Owo7Axw==" }, "customer": { "ip_address": "248.121.176.220", "id": "17008" }, "payment": { "amount": 8855, "currency": "USD" }, "card": \{ "pan": "4242424242424243", "year": 2025, "month": 5, "card\_holder": "SONYA KOVALEVSKY", "cvv": "123" \} } ``` Вместе с тем, при проведении платежей могут требоваться и другие параметры: - Параметры, необходимые в различных случаях,исходя из специфики конкретных платёжных систем и региональных особенностей. Если такие параметры не были переданы изначально, платёж может быть отклонён либо эти параметры могут быть запрошены в процессе его проведения. - Параметры, необходимые в различных случаях,исходя из специфики веб-сервиса, напримерпри выполнении аутентификации 3‑D Secure на стороне веб-сервиса или для отправки уведомления о результате платежа пользователю. Если такие параметры не были переданы, то соответствующие возможности могут не поддерживаться. Для работы с такими случаями может потребоваться настроить дополнительные процедуры. Они частично затронуты далее, а также отдельно разобраны в разделе [Дополнения](ru_gate_quickstart.md), к которому лучше переходить после настройки и тестирования всех базовых процедур. В целом, сбор всех необходимых параметров можно настраивать как удобно, с оглядкой на архитектуру вашего веб-сервиса и иные факторы \(например, с задействованием используемых справочников и баз данных\). Здесь же, определившись с обязательными параметрами, можно приступать к реализации. ## Базовая реализация {#ru_gate_quickstart_basic_implementation} ### Введение {#ru_gate_quickstart_basic_implementation_overview} Реализовывать функции веб-сервиса для проведения платежей можно по-разному, в том числе за счёт создания своих программных решений. В рамках этого быстрого старта мы рассматриваем реализацию с использованием готового кода от Ecommpay для подписывания данных, отправки запросов, приёма ответов на эти запросы и программных оповещений, и, вместе с тем, с использованием ваших решений на стороне веб-сервиса для всех остальных действий, включая получение информации от пользователей и предоставление им информации о проведении платежа. ### Подписывание данных {#ru_gate_quickstart_basic_implementation_signature} Когда для всех необходимых параметров определены их значения\(и только в таком случае\), можно формировать подписьк ним и готовить запрос. ```language-php */ class Signer { const ITEMS_DELIMITER = ';'; const ALGORITHM = 'sha512'; const IGNORED_KEYS = ['frame_mode']; /** * Secret key * * @var string */ private $secretKey; /** * __construct * * @param string $secretKey */ public function __construct(string $secretKey) { $this->secretKey = $secretKey; } /** * Check signature * * @param array $params * @param string $signature * @return boolean */ public function check(array $params, string $signature): bool { return $this->sign($params) === $signature; } /** * Return signature * * @param array $params * @return string */ public function sign(array $params): string { $stringToSign = implode(self::ITEMS_DELIMITER, $this->getParamsToSign($params, self::IGNORED_KEYS)); return base64_encode(hash_hmac(self::ALGORITHM, $stringToSign, $this->secretKey, true)); } /** * Get parameters to sign * * @param array $params * @param array $ignoreParamKeys * @param string $prefix * @param bool $sort * @return array */ private function getParamsToSign( array $params, array $ignoreParamKeys = [], string $prefix = '', bool $sort = true ): array { $projectId = 42; $paymentId = '12345'; $customerId = '123'; $ip = '192.168.1.1'; $paymentAmount = '1000'; $paymentCurrency = 'USD'; $cardPan = '\*4567'; $cardYear = '2029'; $cardMonth = '09'; $cardHolder = 'SONYA KOVALEVSKY'; $cardCvv = '123'; $paramsToSign = [ 'general' => [ 'project_id' => $projectId, 'payment_id' => $paymentId, ], 'customer' => [ 'id' => $customerId, 'ip_address' => $ip, ], 'payment' => [ 'payment_amount' => $paymentAmount, 'payment_currency' => $paymentCurrency, ], 'card' =\> \[ 'pan' =\> $cardPan, 'year' =\> $cardYear, 'month' =\> $cardMonth, 'card\_holder' =\> $cardHolder, 'cvv' =\> $cardCvv, \], ]; foreach ($params as $key => $value) { if (in_array($key, $ignoreParamKeys, true)) { continue; } $paramKey = ($prefix ? $prefix . ':' : '') . $key; if (is_array($value)) { $subArray = $this->getParamsToSign($value, $ignoreParamKeys, $paramKey, false); $paramsToSign = array_merge($paramsToSign, $subArray); } else { if (is_bool($value)) { $value = $value ? '1' : '0'; } else { $value = (string)$value; } $paramsToSign[$paramKey] = $paramKey . ':' . $value; } } if ($sort) { ksort($paramsToSign, SORT_NATURAL); } return $paramsToSign; } } ``` ``` package main import ( "crypto/hmac" "crypto/sha512" "encoding/base64" "sort" ) const itemsDelimiter = ";" var ignoredKeys = map[string]struct{}{"frame_mode": struct{}{}} var secretKey string func SetSecretKey(key string) { secretKey = key } func Check(params map[string]map[string]string, signature string) bool { return Sign(params) == signature } func Sign(params map[string]map[string]string) string { var stringToSign string paramsToSign := getParamsToSign(params, ignoredKeys, "", true) for _, value := range paramsToSign { for _, v := range value { stringToSign = stringToSign + itemsDelimiter + v } } mac := hmac.New(sha512.New, []byte(secretKey)) mac.Write([]byte(stringToSign)) return base64.StdEncoding.EncodeToString(mac.Sum(nil)) } func getParamsToSign(params map[string]map[string]string, ignoreParamKeys map[string]struct{}, prefix string, sorted bool) map[string]map[string]string { var paymentId, customerId, ip, amount, currency, cardPan, cardYear, cardMonth, cardHolder, cardCvv string paramsToSign := map[string]map[string]string{ "general": { "project_id": projectId, "payment_id": paymentId, }, "customer": { "id": customerId, "ip_address": ip, }, "payment": { "payment_amount": amount, "payment_currency": currency, }, "card": \{ "pan": cardPan, "year": cardYear, "month": cardMonth, "card\_holder": cardHolder, "cvv": cardCvv, \}, } for key, value := range params { for k, v := range value { if _, ok := ignoreParamKeys[k]; ok { continue } paramKey := k if prefix != "" { paramKey = prefix + ":" + k } paramsToSign[key][paramKey] = paramKey + ":" + v } } if sorted == true { return sortParams(paramsToSign) } return paramsToSign } func sortParams(params map[string]map[string]string) map[string]map[string]string { var sortedParams map[string]map[string]string keys := make([]string, 0, len(params)) for kp := range params { keys = append(keys, kp) } sort.Strings(keys) for _, ks := range keys { sortedParams[ks] = params[ks] } return sortedParams } ``` ### Отправка запросов и приём ответов на них {#ru_gate_quickstart_basic_implementation_requests} Когда все данные собраны и подписаны, можно отправлять запрос к требуемой конечной точке\(их перечень представлен в спецификации Gate API\). В нашем случае это [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale). При приёме запроса \(как правило, в течение 100 мс\) со стороны платёжной платформы к веб-сервису направляется синхронный HTTP-ответ — с информацией о приёме запроса в обработку или об ошибках, из-за которых запрос не был принят. В ответах от платформы используются следующие коды: - `200 OK` — запрос принят в обработку. В таком случае можно ждать дальнейших оповещений о проведении платежа. Работу с такими оповещениями рассматриваем уже в следующем разделе. - `400 Bad Request` — запрос не принят из-за того, что в нём не указан по крайней мере один из обязательных параметров или указана некорректная подпись. В таком случае можно дополнить запрос недостающими параметрами и обновить подпись \(или просто обновить подпись, проверив при этом корректность используемых идентификатора и ключа проекта\) и повторить отправку запроса. - `403 Forbidden` — запрос не принят из-за отказа в доступе к конечной точке. В таком случае можно обратиться к специалистам технической поддержки Ecommpay для добавления IP-адреса отправителя в список доверенных адресов. - `422 Unprocessable Entity` — запрос не принят из-за синтаксической ошибки \(например, из-за пропущенной запятой\). В таком случае можно исправить ошибку и повторить отправку запроса. - `500 Internal Error` — запрос не принят из-за сбоя в платёжной платформе. В таком случае можно повторить отправку запроса позднее. Чтобы получать информацию из ответов от платформы, следует настроить их приём и обработку. ```language-php $headers = []; $headerCallback = function ($curl, $header_line) use (&$headers) { if (strpos($header_line, ":") === false) { return strlen($header_line); } list($key, $value) = explode(":", trim($header_line), 2); $headers[trim($key)] = trim($value); return strlen($header_line); }; $absUrl = 'https://abs.url'; $curl = curl_init(); $opts[CURLOPT_URL] = $absUrl; $opts[CURLOPT_RETURNTRANSFER] = true; $opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout; $opts[CURLOPT_TIMEOUT] = $this->timeout; $opts[CURLOPT_HEADERFUNCTION] = $headerCallback; curl_setopt_array($curl, $opts); $rbody = curl_exec($curl); $errno = curl_errno($curl); if ($rbody === false) { $errno = curl_errno($curl); $message = curl_error($curl); curl_close($curl); $this->handleCurlError($absUrl, $errno, $message); } $rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); echo "http code = ".$rcode."\n"; echo "http response = ".$rbody."\n"; ``` ``` package main import ( "fmt" "net/http" "time" ) type conf struct { connectTimeout, timeout time.Duration returnTransfer bool } func main() { absUrl := "https://abs.url" var cf = conf{10 * time.Second, 20 * time.Second, true} req, err := http.NewRequest(http.MethodGet, absUrl, nil) if err != nil { fmt.Printf("client: could not create request: %s\n", err) return } client := http.Client{ Timeout: cf.timeout, } res, err := client.Do(req) if err != nil { fmt.Printf("client: error making http request: %s\n", err) handleError(err) return } fmt.Printf("http code = %d\n", res.StatusCode) fmt.Printf("http response = %s\n", res.Body) } ``` ### Приём оповещений и отправка ответов на них {#ru_gate_quickstart_basic_implementation_callbacks} В рамках проведения отдельного платежа от платформы к веб-сервису могут отправляться *предписывающие* и *уведомительные* оповещения. *Предписывающие* оповещения требуют отправки каких-либо сведений в платёжную платформу, предоставления определённой информации пользователю, перенаправления его к сторонним сервисам или выполнения иных действий. Это промежуточные оповещения, на которые необходимо своевременно реагировать для корректного проведения платежей. *Уведомительные* оповещения позволяют оперативно узнавать о результатах платежей и получать другую значимую информацию.Эту информацию можно использовать для оперативного обновления статусов заказов в веб-сервисе, информирования пользователей и других целей — в соответствии с моделью работы вашего сервиса. Уведомительные оповещения могут быть как промежуточными, с информацией о значимых событиях при проведении платежей, так и итоговыми, с информацией о результатах. Для приёма оповещений\(как предписывающих, так и уведомительных\) следует: 1. Определить и задать в платёжной платформе адрес, предназначенный для приёма в веб-сервисе оповещений по проекту. Для этого можно открыть раздел **Проекты** интерфейса Dashboard и использовать инструменты на вкладке **Оповещения**. 2. Настроить проверку целостности и разбор оповещений, ожидаемых по указанному адресу, так, чтобы не использовать в работе оповещения с некорректной подписью. Для такой настройки можно использовать приведённый далее пример кода. 3. Настроить отправку синхронных HTTP-ответов о приёме оповещений: `200 ОК`, если подпись корректна, и `400 Bad Request`, если подпись некорректна. ```language-java { "account": { "number": "424242******4243", "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type": "visa", "card_holder": "SONYA KOVALEVSKY", "id": 45678, "expiry_month": "05", "expiry_year": "2025" }, "customer": { "id": "17008", }, "payment": { "date": "2023-01-11T13:02:42+0000", "id": "Cosmoshop_purchase_2025-01-01_000001", "method": "card", "status": "success", "sum": { "amount": 8855, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2023-01-11T13:02:42+0000", "created_date": "2023-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 8855, "currency": "USD" }, "sum_converted": { "amount": 8855, "currency": "USD" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2023-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` ```language-php require_once __DIR__ . 'signature.php'; //@todo net set to merchant project https://api.merchant.com/callback.php //@todo set projectId $projectId = null; //@todo set paymentId $paymentId = ''; //@todo set secretKey $secretKey = ''; $response = json_decode(file_get_contents('php://input'), true); $rsignature = $response['signature']; unset($response['signature']); if ((new Signer($secretKey))->check($response, $rsignature)) { header('HTTP/1.1 200 OK'); header('Status: 200 OK'); echo "signature is correct\n"; $projectId = $response['project_id']; $paymentId = $response['payment']['id']; //@todo save necessary info to the merchant system } else { header('Status: 400 Bad Request'); header('HTTP/1.1 400 Bad Request'); echo "signature is invalid\n"; } ``` ``` package main import ( "encoding/json" "io/ioutil" "log" "net/http" ) //@todo net set to merchant project https://api.merchant.com/callback.go //@todo set project type project struct{} type request struct { Signature string `json:"signature"` } var prj project //@todo set secretKey var secretKey string //@todo set paymentId var paymentId string //@todo get request var r *http.Request func main() { body, err := ioutil.ReadAll(r.Body) if err != nil { log.Printf("Error reading body: %v", err) } var req request err = json.Unmarshal(body, &req) if err != nil { log.Printf("Error parsing request: %v", err) } var w http.ResponseWriter if checkSignature(req, secretKey, req.Signature) { w.WriteHeader(http.StatusOK) w.Write([]byte("signature is correct\n")) } else { w.WriteHeader(http.StatusBadRequest) w.Write([]byte("signature is invalid\n")) } } func checkSignature(req request, secretKey string, signature interface{}) bool { } ``` На этом можно остановиться и выполнить минимальное [тестирование](ru_gate_quickstart.md) либо продолжить разбираться со спецификой реагирования на различные оповещенияи перейти к тестированию после. ### Реагирование на оповещения {#ru_gate_quickstart_basic_implementation_callbacks_for_cards} #### Общая информация {#section_ygw_zh2_cxb .section} Для реагирования на *уведомительные* оповещения, если это актуально, можно настроить использование необходимой информации из таких оповещений в соответствии со спецификой веб-сервиса. Для реагирования на *предписывающие* оповещения обязательно следует разобраться с выполнением действий, которые могут быть необходимы для проведения платежа. Вместе с тем, настроить реагирование на оповещения можно и позже, после реализации основных действий и их тестирования. К действиям, необходимым при получении предписывающих оповещений, могут относиться: 1. Сбор дополнительных сведений о платеже и их отправка в платформу. В таких случаях в оповещениях передаётся объект `clarification_fields` со списком параметров, которые необходимо отправить в последующем запросе к платёжной платформе.Как правило, запрашивается информация о пользователе: его имя и фамилия, дата рождения, платёжный адрес и иные подобные сведения. ```language-json "clarification_fields":{ "avs_data": [ "avs_post_code", "avs_street_address" ] } ``` Сбор требуемых сведений в таких ситуациях можно осуществлять любым удобным способом, в том числе из имеющейся базы данных или через заполнение пользователем соответствующих полей в интерфейсе веб-сервиса.Подробнее о работе с такими оповещениями — в разговоре [о дополнениях](ru_gate_quickstart.md), после первичной настройки и тестирования. Здесь же можно отметить, что такие ситуации бывают и требуют оперативного решения на стороне веб-сервиса. 2. Перенаправление пользователя к стороннему сервису. В таких случаях оповещения, как правило, содержат объект `acs`или `redirectData` с адресом страницы сервиса, к которому необходимо перенаправить пользователя, и дополнительными сведениями. При получении таких оповещений следует перенаправлять пользователей по указанным адресам.Это можно делать с помощью HTML-форм. ```language-json "acs":{ "pa_req":"eJxVUtluwyAQ/BUrH2DA...n8/4htjT7Em", "acs_url":"https://example.com/ACS", "md":"eyJfto7jg456ZCI6IiJ9" } ``` ```language-xml
``` После перенаправления пользователя согласно полученному оповещению может понадобиться принять какую-либо дополнительную информацию от целевого сервиса \(например, от сервиса Access Control Server при аутентификации 3‑D Secure\) или ожидать следующего оповещения от платформы — в соответствии со схемой проведения платежа и спецификой используемого метода. Подробнее о работе с такими оповещениями — в разговоре [о дополнениях](ru_gate_quickstart.md), после первичной настройки и тестирования. 3. Отображение пользователю какой-либо информации. В таких случаях оповещения, как правило, содержат объект `display_data` с информацией, которую необходимо отобразить пользователю\(например, в виде текста или QR-кода\), и дополнительными сведениями. ```language-json "display_data": [ { "type": "qr_data", "title": "QR Code", "data": "https://example.com/paygate/union/pay/MDAyMDUxNjk0OTMwNjYyMTQzMTgwOHwwNHw0ODgxMDAwMA==" }, { "type": "add_info", "title": "QR Code Timeout", "data": "600" } ] ``` Такие оповещения могут быть актуальны для платежей с использованием различных альтернативных платёжных методов. Работа с этими методами рассматривается в разделе [Платёжные методы](ru_pm_about.md), и знакомиться с ней стоит после первичной настройки и тестирования. #### Работа с карточными оплатами {#section_c1h_dwt_xxb .section} При работе с карточными оплатами наиболее актуальными можно считать промежуточные оповещения для выполнения аутентификации 3‑D Secure. В таких оповещениях, как правило, содержатся сведения для перенаправления пользователя напрямую к сервису эмитента\(если в оповещении получен объект `acs`\)или к сервису провайдера\(если получен объект `redirectData`\). Перенаправить пользователя на требуемую страницу можно с помощью такой же HTML-формы, которая была представлена ранее \(и повторена здесь\). ```language-xml
``` При возвращении пользователя от сервиса эмитента следует принять от этого сервиса информацию о результате аутентификации, отправить эту информацию в HTTP-POST-запросе к платформе и принять синхронный HTTP-ответ. В случае возвращения пользователя от сервиса провайдера такая информация не передаётся, и со стороны веб-сервиса следует ожидать от платформы оповещение с информацией о результате платежа. ```language-php require_once __DIR__ . 'signature.php'; //@todo set projectId $projectId = null; //@todo set paymentId $paymentId = ''; //@todo set secretKey $secretKey = ''; $params = [ 'general' => [ 'project_id' => $projectId, 'payment_id' => $paymentId, ], "pares" => "", "md" => "" ]; $absUrl = 'https://api.ecommpay.com/v2/payment/card/3ds_result'; $params['general']['signature'] = (new Signer($secretKey))->sign($params); $request = json_encode($params); $curl = curl_init(); $opts = []; $opts[CURLOPT_POST] = 1; $opts[CURLOPT_POSTFIELDS] = $request; $opts[CURLOPT_HTTPHEADER] = ['Content-Type: application/json', 'Content-Length: '.strlen($request)]; $headers = []; $headerCallback = function ($curl, $header_line) use (&$headers) { if (strpos($header_line, ":") === false) { return strlen($header_line); } list($key, $value) = explode(":", trim($header_line), 2); $headers[trim($key)] = trim($value); return strlen($header_line); }; $opts[CURLOPT_URL] = $absUrl; $opts[CURLOPT_RETURNTRANSFER] = true; $opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout; $opts[CURLOPT_TIMEOUT] = $this->timeout; $opts[CURLOPT_HEADERFUNCTION] = $headerCallback; curl_setopt_array($curl, $opts); $rbody = curl_exec($curl); $errno = curl_errno($curl); if ($rbody === false) { $errno = curl_errno($curl); $message = curl_error($curl); curl_close($curl); $this->handleCurlError($absUrl, $errno, $message); } $rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); echo "http code = ".$rcode."\n"; echo "http response = ".$rbody."\n"; ``` ``` package main import ( "bytes" "encoding/json" "fmt" "net/http" "os" "time" ) type general struct{ project_id, payment_id, signature string } type params struct { gnrl general pares, md string } type conf struct { connectTimeout, timeout time.Duration } func main() { //@todo set project project := "" //@todo set secretKey var secretKey string //@todo set paymentId var paymentId string var cf = conf{10 * time.Second, 20 * time.Second} prms := params{ gnrl: general{project_id: project, payment_id: paymentId, signature: ""}, pares: "", md: "", } signature := sign(prms, secretKey) prms.gnrl.signature = signature absUrl := "https://api.ecommpay.com/v2/payment/card/3ds_result" reqBody, err := json.Marshal(prms) bodyReader := bytes.NewReader(reqBody) req, err := http.NewRequest(http.MethodPost, absUrl, bodyReader) req.Header.Set("Content-Type", "application/json") req.Header.Set("Content-Length", string(rune(bodyReader.Len()))) client := http.Client{ Timeout: cf.timeout, } res, err := client.Do(req) if err != nil { fmt.Printf("client: error making http request: %s\n", err) handleError(err) os.Exit(1) } defer res.Body.Close() fmt.Printf("http code = %d\n", res.StatusCode) fmt.Printf("http response = %s\n", res.Body) } func sign(par params, secretKey string) string { //@todo implement sign function } ``` Более подробно работа с аутентификацией 3‑D Secure рассматривается [в отдельной статье](ru_gate_payment_3ds.md), к которой можно обращаться уже после тестирования первичного решения. ## Тестирование {#ru_gate_quickstart_testing} Когда работа с подписью, ответами и оповещениями организована, можно приступать к тестированию проведения платежей. При работе с тестовым проектом можно использовать два вида платёжных реквизитов: *специальные* тестовые, позволяющие тестировать заданные сценарии работы, и *произвольные* реалистичные, позволяющие дополнительно проверять работу с платежами в разных случаях. В базовом случае можно использовать следующие тестовые номера платёжных карт\(для проведения платежей по заданным кратчайшим сценариям\). |Эмулируемый сценарий|Конечный статус платежа| |Платёж проведён|Платёж отклонён| |--------------------|:----------------------| |---------------|:--------------| |Оплата без аутентификации 3‑D Secure|`4000 0000 0000 0077`|`4111 1111 1111 1111`| |Оплата с аутентификацией 3‑D Secure|`4314 2200 0000 0056`|`5544 3300 0000 0045`| Для более масштабного тестирования можно использовать расширенный набор тестовых данных для [карточных](ru_test_cards.md)и различных [альтернативных](ru_pm_testing.md) платежей, а также произвольные данные, включая реквизиты реальных карт, кошельков и других платёжных инструментов. Такой набор позволяет тестировать различные сценарии проведения платежей, например с выполнением аутентификации 3‑D Secure без каких-либо действий пользователя. И это является безопасным, поскольку для всех данных в тестовой среде обеспечивается тот же уровень защиты, что и в рабочей, но реальные платежи при этом не проводятся. По итогам тестирования можно считать реализованными базовые функции по проведению платежей и при желании переходить дальше — к различным дополнениям, которые могут быть полезны уже на первых порах работы с платёжной платформой, и к запуску решения в работу. ## Дополнения {#ru_gate_quickstart_additional_aspects} ### Общий контроль проведения платежей {#section_osj_vd4_fvb .section} После проведения нескольких тестовых платежей можно разобраться с тем, как контролировать ситуацию по ним.Для общего контроля платежей в платформе предусмотрены пользовательский интерфейс Dashboard и программный интерфейс Data API. С их помощью можно получать различными способами сводную информацию о суммах, статусах и других атрибутах проводимых платежей, но с задержкой вплоть до нескольких минут. Для работы с этими интерфейсами необходимо предварительно получить [доступ](ru_dbl_overview.md) к интерфейсу Dashboard, настроить права доступа к текстовому проекту и, при необходимости работы с Data API, сформировать соответствующие токен и секретный ключ.После этого можно переходить к работе с информацией о платежах. В интерфейсе Dashboard для контроля состояния платежей предусмотрены раздел **Платежи** \(с информацией о платежах всех типов\) и специализированные разделы с информацией о платежах различных типов, а также карточки с информацией об отдельных платежах. Справочная информация об использовании этих разделов представлена в соответствующем [разделе документации](ru_dbl_payments.md). ![](images/ecommpay/dbl/ru_quickstart_dbl_overview.svg "Реестр платежей") ![](images/ecommpay/dbl/ru_quickstart_dbl_payment_details.svg "Карточка платежа") В Data API предусмотрены различные конечные точки, через запросы к которым можно получать информацию о группах платежей или отдельных платежах. Работа с такими запросами описана в соответствующем [разделе документации](ru_dbl_using_api.md). ### Оперативный контроль состояния отдельных платежей {#section_jbb_lkf_cxb .section} Чтобы получать оперативную информацию о состоянии отдельных платежей через Gate API, следует использовать HTTP-POST-запросы к конечной точке [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status)\(с указанием идентификаторов проекта и платежа\) и принимать синхронные HTTP-ответысо сведениями по этим запросам. ```language-php require_once __DIR__ . 'signature.php'; //@todo set projectId $projectId = null; //@todo set paymentId $paymentId = ''; //@todo set secretKey $secretKey = ''; $params = [ 'general' => [ 'project_id' => $projectId, 'payment_id' => $paymentId, ] ]; $absUrl = 'https://api.ecommpay.com/v2/payment/status'; $params['general']['signature'] = (new Signer($secretKey))->sign($params); $request = json_encode($params); $curl = curl_init(); $opts = []; $opts[CURLOPT_POST] = 1; $opts[CURLOPT_POSTFIELDS] = $request; $opts[CURLOPT_HTTPHEADER] = ['Content-Type: application/json', 'Content-Length: '.strlen($request)]; $headers = []; $headerCallback = function ($curl, $header_line) use (&$headers) { if (strpos($header_line, ":") === false) { return strlen($header_line); } list($key, $value) = explode(":", trim($header_line), 2); $headers[trim($key)] = trim($value); return strlen($header_line); }; $opts[CURLOPT_URL] = $absUrl; $opts[CURLOPT_RETURNTRANSFER] = true; $opts[CURLOPT_CONNECTTIMEOUT] = $this->connectTimeout; $opts[CURLOPT_TIMEOUT] = $this->timeout; $opts[CURLOPT_HEADERFUNCTION] = $headerCallback; curl_setopt_array($curl, $opts); $rbody = curl_exec($curl); $errno = curl_errno($curl); if ($rbody === false) { $errno = curl_errno($curl); $message = curl_error($curl); curl_close($curl); $this->handleCurlError($absUrl, $errno, $message); } $rcode = curl_getinfo($curl, CURLINFO_HTTP_CODE); curl_close($curl); echo "http code = ".$rcode."\n"; echo "http response = ".$rbody."\n"; $response = json_decode($rbody, true); $rsignrature = $response['signature']; unset($response['signature']); if ((new Signer($secretKey))->check($response, $rsignrature)) { echo "signature is correct\n"; } else { echo "signature is invalid\n"; } ``` ``` package main import ( "bytes" "encoding/json" "fmt" "io" "log" "math/rand" "net/http" "os" "time" ) //@todo net set to merchant project https://api.merchant.com/callback.go type general struct{ project_id, payment_id, signature string } type params struct{ gnrl general } type response struct { Signature string `json:"signature"` } func main() { //@todo set project project := "" //@todo set secretKey var secretKey string //@todo set paymentId var paymentId string prms := params{ gnrl: general{project_id: project, payment_id: paymentId, signature: ""}, } signature := sign(prms, secretKey) prms.gnrl.signature = signature absUrl := "https://api.ecommpay.com/v2/payment/status" reqBody, err := json.Marshal(prms) bodyReader := bytes.NewReader(reqBody) req, err := http.NewRequest(http.MethodPost, absUrl, bodyReader) req.Header.Set("Content-Type", "application/json") req.Header.Set("Content-Length", string(rune(bodyReader.Len()))) res, err := http.DefaultClient.Do(req) if err != nil { fmt.Printf("client: error making http request: %s\n", err) handleError(err) os.Exit(1) } defer res.Body.Close() fmt.Printf("http code = %d\n", res.StatusCode) fmt.Printf("http response = %s\n", res.Body) var respBody response b, err := io.ReadAll(res.Body) err = json.Unmarshal(b, &respBody) if err != nil { log.Printf("Error parsing response: %v", err) } rsign := respBody.Signature if checkSignature(respBody, secretKey, rsign) { fmt.Printf("signature is correct\n") } else { fmt.Printf("signature is invalid\n") } } func sign(par params, secretKey string) string { //@todo implement sign function } func checkSignature(resp response, secretKey string, signature interface{}) bool { //@todo implement checkSignature function } ``` При возникновении вопросов, касающихся получения информации о платежах через Gate, можно обращаться [к соответствующей статье](ru_Gate_payment_status_request.md). ### Возврат средств {#section_vzl_nzf_fvb .section} Если по каким-либо из проведённых оплат необходимо выполнить возвраты, для этого можно использовать Dashboard и Gate. При работе через Dashboard можно открывать карточки целевых оплат и использовать расположенную в них кнопку **Возврат**, а также применять пакетную отправку запросов через файлы \([подробнее](ru_dbl_payments.md)\). При работе через Gate следует использовать запросы к соответствующим конечным точкам \(с учётом специфики платёжных методов\). В случае карточных оплат это запросы к конечной точке [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund). В каждом запросе на возврат по карточной оплате необходимо указывать целевые идентификаторы проекта и платежа, а также описание причины возврата. Вместе с этими обязательными сведениями можно указывать также сумму и код валюты возврата, если возвратить необходимо только часть суммы. В таких случаях код валюты должен соответствовать исходному в платеже, иначе запрос на возврат отклоняется. Для более глубокого освоения работы с возвратами через Gate можно использовать [отдельную статью](ru_Gate_Refund.md). ```language-json { "general": { "project_id": 42, "payment_id": "Cosmoshop_purchase_2025-01-01_000001", "signature": "of8k9xeKJ7KLTZYO56lCv+f1M0Sf/7eg==" }, "payment": { "description": "Item return" } } ``` ```language-json { "project_id":42, "payment":{ "id":"Cosmoshop_purchase_2025-01-01_000001", "type":"purchase", // Тип платежа — разовая оплата "status":"refunded", // Статус платежа после полного возврата "date":"2023-01-12T15:20:36+0000", "method":"card", "sum":{ "amount":0, // Актуальная сумма платежа после полного возврата "currency":"USD" // Код валюты платежа } }, "account":{ "number":"424242******4243", "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49", "type":"visa", "card_holder":"SONYA KOVALEVSKY", "expiry_month":"05", "expiry_year":"2025" }, "customer":{ "id":"17008" }, "operation_description":"Item return", // Описание причины возврата "operation":{ "id":3861, "type":"refund", // Тип операции "status":"success", // Статус операции "date":"2023-01-12T15:21:00+0000", "created_date":"2023-01-12T15:20:58+0000", "request_id":"67a97cd6b14f1aa0543c81e18cd270b66-aadc6e790206d5-00038611", "sum_initial":{ "amount":8855, // Сумма возврата "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа) }, "sum_converted":{ "amount":8855, "currency":"USD" }, "code":"0", "message":"Success", "provider":{ "id":414, "payment_id":"", "endpoint_id":414 } }, "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` ### Организация работы с другими типами платежей {#section_g1n_zrw_dwb .section} Настроив проведение карточных оплат, можно настроить работу и с другими типами платежейи платёжными методами.Чтобы сориентироваться в том, как в платформе проводятся платежи разных типов, и настроить работу с необходимыми типами платежей и платёжными методами, можно использовать \(с описанием поддерживаемых типов платежей и их статусов\)и [материалы о методах](ru_pm_about.md)\(с описанием специфики проведения платежей с использованием различных методов\). ### Использование вспомогательных процедур и дополнительных возможностей {#section_hp1_p5x_2wb .section} При проведении платежей через платёжную платформу Ecommpay могут применяться различные *процедуры* и *возможности*. Вспомогательные процедуры требуются в отдельных случаях для решения специфических задач, например по аутентификации пользователей.Когда такие процедуры актуальны, они обязательны для проведения платежей, поэтому важно уметь с ними работать. В свою очередь, дополнительные возможности не блокируют проведение платежей имогут выполняться по желанию мерчанта.Они рассчитаны на улучшение качества предоставляемого сервиса. После настройки проведения оплат, описанных в этом быстром старте, может быть полезно настроить выполнение процедур и возможностей, актуальных в соответствии со спецификой вашего веб-сервисаи задействуемых платёжных методов. Среди них можно выделить следующие: - [Дополнение информации о платеже](ru_Gate_Clarification.md)— чтобы своевременно предоставлять дополнительные данные, которые могут запрашиваться платёжными системами; - [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md)— чтобы обеспечивать аутентификацию пользователей для проведения платежей с использованием платёжных карт; - [Отправка уведомлений пользователям](ru_gate_receipts.md)— чтобы информировать пользователей через электронную почту о проведении платежей и других событиях. Помимо этих процедур и возможностей можно настраивать и другие, описанные в разделах[Вспомогательные процедуры](ru_gate_procedures.md) и[Дополнительные возможности](ru_Gate_Additional_capabilities.md). ## Запуск {#ru_gate_quickstart_launch_project} После реализации базовых функций, тестирования актуальных возможностей и настройки необходимых вам сценариев работы можно переходить к запуску рабочего проекта. Важно, чтобы к этому моменту были решены основные организационные вопросы. В таком случае вопросы технические сводятся к настройке свойств проекта на стороне платёжной платформы и к началу использования идентификатора и ключа рабочего проекта на стороне веб-сервиса. Также после запуска можно продолжать настраивать работу с различными типами платежей, платёжными методами,процедурами и возможностями — с учётом ваших потребностей — и обращаться с вопросами и обратной связью к нашим специалистам. Успехов! --- # Организация взаимодействия {#ru_gate_interaction_organisation} статья о том, как строится работа с платёжной платформой через Gate и как можно организовывать эту работу со стороны веб-сервиса, опираясь на используемые схемы и форматы взаимодействия Gate представляет собой программный интерфейс \(API\) для приёма запросов от веб-сервиса к платёжной платформе Ecommpay. Gate отвечает принципам REST API, а также поддерживает обратную совместимость, благодаря которой выпуск каждой новой версии интерфейса не требует изменений программного кода на стороне веб-сервиса. Gate доступен по адресу `https://api.ecommpay.com` и обеспечивает приём запросов в заданных конечных точках с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2. Спецификация интерфейса доступна по адресу [https://api-developers.ecommpay.com](https://api-developers.ecommpay.com). В этом разделе представлена информация о порядке и технических аспектах интеграции через Gate. **На уровень выше:**[Gate](ru_Gate_Integration_About.md) ## Порядок интеграции {#ru_gate_integration_step} Для интеграции с платёжной платформой Ecommpay через Gate необходимо: 1. Решить организационные вопросы, касающиеся взаимодействия с Ecommpay: 1. Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с Ecommpay — отправить [заявку на подключение](https://ecommpay.com/apply-now/). 2. Если планируется проводить платежи с использованием карт платёжных систем Visa и Mastercard — предоставить курирующему менеджеру Ecommpay документы о соответствии [требованиям PCI DSS](ru_faq_integration.md#fig_fgk_rgs_4nb): - Для всех мерчантов — отчёт о результатах [ASV-сканирования](ru_glossary.md). Такие сканирования должны выполняться авторизованными поставщиками \(PCI SSC Approved Scanning Vendor, ASV\) ежеквартально, а также после каждого значительного изменения сетевой инфраструктуры.Мерчанты Ecommpay могут выбирать таких поставщиков самостоятельно и, если это актуально, могут задействовать поставщика, являющегося партнёром Ecommpay. Чтобы организовать сканирования через партнёра Ecommpay, можно обращаться к курирующему менеджеру. - Для мерчантов с количеством операций более 6 миллионов в год \(уровня 1\) — аттестат соответствия \(Attestation of Compliance, AOC\). - Для мерчантов с количеством операций до 6 миллионов в год \(уровней 2, 3 и 4\) — [опросный лист](https://www.pcisecuritystandards.org/pci_security/completing_self_assessment) \(Self-Assessment Questionnaire, SAQ\). С вопросами о правилах заполнения опросных листов можно обращаться к курирующему менеджеру Ecommpay. 3. Согласовать со специалистами технической поддержки Ecommpay порядок и сроки интеграции, тестирования \(в том числе с использованием различных платёжных методов\)и запуска решения в работу. 2. Доработать программный код веб-сервиса для интеграции с платёжной платформой через Gate. 3. Протестировать и совместно со специалистами технической поддержки Ecommpay запустить в работу решение по взаимодействию веб-сервиса с платёжной платформой. После тестирования и мониторинга, когда проведение платежей на рабочем трафике корректно, специалисты технической поддержки переводят работу с веб-сервисом в режим штатной поддержки. При возникновении вопросов о работе через Gate можно обращаться к курирующему менеджеру и специалистам технической поддержки Ecommpay \([support@ecommpay.com](mailto:support@ecommpay.com)\). ## Схемы взаимодействия {#ru_gate_interaction_scheme} ### Общая информация {#section_mcq_r43_chb .section} При использовании Gate взаимодействие между веб-сервисом и платёжной платформой Ecommpay строится на обмене HTTP-сообщениями по принципу «запрос-ответ» — с отправкой запросов от веб-сервиса и ответов от платформы. При этом предусмотрены две схемы взаимодействия: *синхронная* для тех запросов, которые могут быть выполнены автономно на стороне платформы, и *асинхронная* для тех запросов, выполнение которых зависит не только от работы платформы, но и от действий других сторон \(например, пользователя или платёжной системы\). ### Синхронная схема {#section_bc4_fsh_thb .section} *Синхронная схема взаимодействия* используется, когда запрос можно полностью выполнить на стороне платёжной платформы: например, чтобы получить статус платежа в платформе. Такое взаимодействие осуществляется в рамках одного HTTP-сеанса и подразумевает отправку одного ответа на полученный запрос. Это может быть ответ с запрошенной информацией или с информацией об ошибке. Время от получения запроса до отправки ответа, как правило, составляет не более 100 мс. ![](images/ru_gate_sync.svg) ### Асинхронная схема {#section_sdm_hsh_thb .section} *Асинхронная схема взаимодействия* используется, когда выполнение запроса требует участия других сторон помимо веб-сервиса и платёжной платформы: например, чтобы провести оплату с участием пользователя и платёжной системы. В рамках такой схемы от платформы к веб-сервису отправляются начальный ответ \(с информацией о том, что запрос получен и корректен, либо о том, что он некорректен\) и итоговое оповещение с информацией \(если запрос корректен\). Также в ходе проведения платежа могут отправляться промежуточные оповещения: например, с информацией для перенаправления пользователя к форме платёжной системы. Время от получения запроса до отправки начального ответа, как правило, составляет не более 100 мс. Время от приёма запроса до отправки оповещений может варьироваться, поскольку зависит от других сторон, задействованных в выполнении запроса. ![](images/ru_gate_async.svg) Для организации взаимодействия с платёжной платформой по асинхронной схеме на стороне веб-сервиса необходимо обеспечить корректное реагирование на оповещения. Для промежуточных оповещений способы реагирования зависят от переданных сведений, а для итогового оповещения необходимо отправить ответ о его приёме: - Если оповещение обработано успешно, необходимо указать код ответа `200 OK`, при этом тело ответа может быть пустым. - Если при обработке оповещения выявлена ошибка, рекомендуется указать код ответа, соответствующий этой ошибке, из числа доступных в спецификации HTTP. Оповещения отправляются повторно до получения ответа от веб-сервиса с кодом `200 OK`. ``` HTTP/1.1 200 OK Date: Fri, 07 Jun 2019 11:38:32 GMT Content-Type: text/plain;charset=UTF-8 Content-Length: 2 Connection: keep-alive OK ``` ## Порядок работы с запросами {#ru_gate_requests_processing_scheme} Взаимодействие в рамках любой из схем начинается с отправки запроса к платёжной платформе. При получении запроса в платформе выполняются следующие действия: - На этапе приёма запроса обеспечивается синтаксический анализ JSON-строки и проверяется наличие минимального набора параметров. - Если из JSON-строки удалось извлечь данные и в этих данных указан минимальный набор параметров, то запрос переводится на этап обработки. В рамках асинхронного взаимодействия в таком случае отправляется ответ о приёме запроса в обработку. - Если на этом этапе обнаружены ошибки, то работа с запросом прекращается. В таком случае в рамках любой схемы взаимодействия отправляется ответ с информацией об ошибке. - На этапе обработки запроса обеспечивается проверка набора данных на соответствие спецификации Gate, а также проверка семантической согласованности данных и корректности подписи. - Если в наборе данных не обнаружены ошибки, то запрос переводится на этап выполнения. Ответ при этом не отправляется. Для запросов на инициирование платежа в платформе регистрируется платёж: создаётся объект `payment`. - Если в наборе данных обнаружены ошибки, то работа с запросом прекращается. В рамках синхронного взаимодействия отправляется ответ с информацией об ошибке, в рамках асинхронного — оповещение. - На этапе выполнения запроса обеспечивается выполнение всех необходимых действий для получения и отправки результата, например, сбор запрашиваемой информации в платформе или проведение платежа. - Если запрос выполнен, то в рамках синхронного взаимодействия отправляется ответ с запрошенной информацией, а в рамках асинхронного — итоговое оповещение. - Если в рамках выполнения запроса возникли ошибки, то работа с запросом прекращается и в рамках синхронного взаимодействия отправляется ответ с информацией об ошибке, а в рамках асинхронного — оповещение. Как правило, ответ на полученный запрос в любом из описанных случаев отправляется к веб-сервису в течение 100 мс. Если ответ не получен, можно повторить отправку запроса с тем же набором данных \(при проведении платежа — с тем же идентификатором платежа\). Если в ответе указаны сведения об ошибке, допущенной на стороне веб-сервиса, следует устранить эту ошибку и повторить отправку запроса с учётом правок. ## Форматы данных {#ru_Gate_Formats} статья с описанием форматов данных, используемых в запросах и оповещениях ### Общая информация {#section_hgq_qwb_wvb .section} При работе с Gate API, как и при работе с другими интерфейсами платёжной платформы Ecommpay, должны использоваться допустимые способы кодирования и форматы представления данных.Основные сведения о них представлены в настоящей статье и [в спецификации интерфейса](https://api-developers.ecommpay.com/). Дополнительно, когда это актуально, следует использовать также специализированные [Справочники](ru_directory.md), описания конкретных платёжных методов в разделе [Платёжные методы](ru_pm_about.md) и статьи об используемых возможностях. Наконец, при возникновении вопросов и выявлении проблем, касающихся форматов данных, можно обращаться к специалистам технической поддержки Ecommpay. ### Кодирование данных {#section_kkg_kjl_bbb .section} При формировании запросов к платформе и при обработке полученных от платформы ответов и оповещений должна использоваться кодировка UTF-8. Кроме того, в некоторых случаях должны дополнительно применяться другие способы кодирования, в частности Base64.Такие случаи отдельно оговариваются в рамках настоящей документации и [в спецификации интерфейса](https://api-developers.ecommpay.com/). ### Указание даты и времени {#section_db4_ckl_bbb .section} При работе с платформой дата и время, как правило, указываются в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\), где `ГГГГ-ММ-ДД` — дата, `T` — служебный символ, `чч:мм:сс` — время, `чч:мм` — отклонение от всемирного координированного времени. Например, `2025-05-25T15:30:25+00:00`. Вместе с тем, в некоторых случаях дата и время могут указываться иначе.Такие случаи отдельно оговариваются в рамках настоящей документации и [в спецификации интерфейса](https://api-developers.ecommpay.com/). ### Указание сумм {#section_okf_xjl_bbb .section} Суммы платежей и операций при работе с платформой, как правило, указываются в дробных единицах валюты, без применения десятичного разделителя. Так, 100 долларов США представляются в центах и указываются как 10000 \(но не 100 и не 100,00\).И аналогично для других валют с учётом их специфики. |Валюта|Сумма|Представление| |------|-----|-------------| |EUR|39,95|`3995`| |GBP|450,66|`45066`| |JPY|200|`200`| |KWD|150,155|`150155`| Количество дробных разрядов для разных валют определяется в соответствии со стандартом [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html) и представлено [в справочнике валют](ru_currency_codes.md). ### Указание кодов валют, стран и языков {#section_iq3_dkl_bbb .section} При работе с платёжной платформой Ecommpay могут применяться: - трёхбуквенные *коды валют* — в соответствии со стандартом [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html); - двухбуквенные *коды стран* — в соответствии со стандартом [ISO 3166-1](https://www.iso.org/ru/iso-3166-country-codes.html); - одно-, двух- и трёхсимвольные *коды территорий* \(таких как штаты, провинции и регионы\) — в соответствии стандартом [ISO 3166-2](https://www.iso.org/ru/iso-3166-country-codes.html); - двухбуквенные *коды языков* — в соответствии со стандартом [ISO 639-1](https://www.iso.org/ru/iso-639-language-codes.html). Перечни таких кодов, за исключением кодов территорий, приведены в [справочниках](ru_directory.md). ## Формат запроса {#ru_gate_requests_format} ### Общая информация {#section_hjr_wc4_vhb .section} В рамках взаимодействия с платёжной платформой через Gate все данные от веб-сервиса должны передаваться в *запросах* — HTTP-сообщениях заданной структуры — с использованием метода POST. Описание общей структуры запросов представлено далее, а описание структур данных для различных случаев — [в спецификации интерфейса](https://api-developers.ecommpay.com/). ### Структура {#section_chd_1p2_xhb .section} В каждом запросе к платёжной платформе должны передаваться следующие элементы в указанном порядке: - стартовая строка с указанием метода передачи запроса \(`POST`\) и конечной точки в интерфейсе Gate \(например, `/v2/payment/status`\), протокола и его версии \(`HTTP/1.1`\); - заголовок с полем `Host`, содержащим доменное имя для запросов через Gate \(`api.ecommpay.com`\); - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним. В дополнение к обязательному полю `Host` в заголовке можно использовать любые другие поля из числа допустимых [в HTTP версии 1.1](https://tools.ietf.org/html/rfc2616#page-31). Далее представлен пример запроса с рекомендуемым набором полей заголовка. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения. ``` POST /v2/payment/status HTTP/1.1 User-Agent: curl/7.29.0 Host: api.ecommpay.com Accept: */* Content-Length: 179 Content-Type: application/x-www-form-urlencoded { "general": { "project_id": 1, "payment_id": "ID_184", "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tY3T\/pOMeSaRfBa...==" } } ``` ### Параметры адресации {#section_b3q_bsx_thb .section} При формировании запросов необходимо указывать базовый и относительный адреса отправки. В качестве базового адреса для запросов через Gate используется доменное имя `api.ecommpay.com`, а в качестве относительного — указатель конечной точки в интерфейсе Gate в соответствии со спецификацией. **Прим.:** Полный адрес в этом случае представляет собой строку вида `https://{доменное имя платформы для запросов через Gate}/{указатель конечной точки}`. Например, адрес для запроса на получение статуса платежа выглядит как `https://api.ecommpay.com/v2/payment/status`, но в таком виде при работе с POST-запросами полные адреса не используются. ### Тело {#section_kdx_ptx_thb .section} В теле сообщения должна содержаться JSON-строка с набором данных в формате `"<название параметра>": <значение параметра>`. Чтобы предотвратить утечку и подмену данных во время их передачи в платёжную платформу, в составе JSON-строки используется подпись, а на транспортном уровне передачи — протокол TLS 1.2, обеспечивающий шифрование. Подробная информация о формировании подписи представлена в разделе [Работа с подписью к данным](ru_platform_signature.md). Далее представлен пример JSON-строки c набором данных, обязательных для получения статуса платежа. Сумму и валюту платежа для данного запроса указывать не требуется. ``` { "general": { "project_id": 2990, "payment_id": "payment_id", "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA==" } } ``` ## Формат ответа {#ru_gate_responses_format} ### Общая информация {#section_wlh_tkg_vhb .section} Со стороны платёжной платформы получение запроса подтверждается отправкой ответа — HTTP-сообщения заданной структуры — в рамках того же сеанса. В зависимости от результата обработки запроса и схемы взаимодействия между веб-сервисом и платформой передаваемые в ответе данные включают в себя: - запрошенную информацию, если запрос выполнен в рамках синхронной схемы; - сведения о приёме запроса, если запрос принят в обработку в рамках асинхронной схемы; - расширенное описание ошибки, если запрос не может быть выполнен в рамках синхронной схемы или не может быть принят в обработку в рамках асинхронной. Далее представлена информация о структуре ответов, а также о кодах и статусах, используемых для передачи информации о состоянии запроса; информация о полном перечне кодов платёжной платформы, используемых в расширенном описании ошибок представлена в разделе [Работа с информацией об операциях](ru_platform_payment_info_codes.md). ### Структура {#section_c2t_tbm_xhb .section} В каждом ответе от платформы содержатся следующие элементы в порядке перечисления: - стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к коду \(например, `200 OK`\); - поля заголовка; - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 в с набором данных. ### Коды ответа {#section_aj3_knq_13b .section} HTTP-код ответа используется в стартовой строке любого ответа для передачи информации о результате приёма или выполнения запроса либо о причине обнаруженной ошибки. Перечень кодов ответов и пояснительных фраз, используемых в ответах платформы, приведён далее в таблице. |Код с пояснением|Описание| |----------------|--------| |200 OK|*В рамках синхронной схемы взаимодействия*: Запрос успешно выполнен. В теле ответа передана запрошенная информация *В рамках асинхронной схемы взаимодействия*: Запрос успешно принят. Можно ожидать промежуточные или итоговое оповещения | |400 Bad Request|Запрос не может быть принят из-за отсутствия в наборе данных, извлечённых из JSON-строки, обязательного параметра, например идентификатора проекта| |403 Forbidden|Запрос не может быть принят из-за отказа в доступе к указанной конечной точке, например, если запрос отправлен с IP-адреса, который не добавлен в список разрешённых| |422 Unprocessable Entity|Запрос не может быть принят из-за синтаксической ошибки, обнаруженной при извлечении данных из JSON-строки, например, из-за пропущенной запятой| |500 Internal Error|Запрос не может быть обработан из-за сбоя в платёжной платформе| ### Статусы запроса {#section_jmx_knq_13b .section} Статус запроса используется для передачи информации о приёме запроса в обработку и указывается в параметре `status` в теле ответа. Для запроса используется два статуса: - `success` — запрос принят в обработку. Данный статус используется только в рамках взаимодействия по асинхронной схеме в ответах с HTTP-кодом `200`. - `error` — запрос не может быть принят в обработку. Данный статус может использоваться в рамках обеих схем взаимодействия в ответах с кодами ошибок `400`, `403`, `422` и `500`. ### Ответы с запрошенной информацией {#section_rn2_tm2_yhb .section} В этом пункте представлены примеры ответа на запрос, обрабатываемый по синхронной схеме. Содержимое JSON-строки в этих примерах разбито на несколько строк для удобства чтения. Если запрос успешно обработан, то в стартовой строке ответа передаётся код ответа `200`, а в теле ответа — запрошенная информация без указания статуса запроса. ``` POST /v2/payment/status HTTP/1.1 // Запрос от веб-сервиса на получение статуса платежа в платформе HTTP/1.1 200 OK // Ответ от платёжной платформы Server: api.ecommpay.com Date: Wed, 22 May 2019 10:27:49 GMT Content-Type: application/json; charset=UTF-8 Content-Length: 875 Connection: keep-alive Keep-Alive: timeout=60 Cache-Control: no-cache Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Origin: * X-Powered-By: PHP/7.0.32 Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent, X-Requested-With,If-Modified-Since,Cache-Control,Content-Type Expires: Wed, 22 May 2019 10:27:48 GMT { "project_id":665, "payment":{ "id":"E2E__S02_0.53381200_1558520409", "type":"purchase","status":"success", "date":"2019-05-22T10:20:20+0000", "method":"cup-card", "sum":{ "amount":100, "currency":"CNY" }, "description":"Success from PP" }, "account":{ "number":"628888******8888" }, "customer":{ "id":"Vally Vasya" }, "operations":[{ "id":3259141213429, "type":"sale", "status":"success", "date":"2019-05-22T10:20:20+0000", "created_date":"2019-05-22T10:20:13+0000", "request_id":"e0d69edf1c3aac249e", "sum_initial":{ "amount":100, "currency":"CNY" }, "sum_converted":{ "amount":100, "currency":"CNY" }, "provider":{ "id":1379, "payment_id":"1558520414466", "date":"2019-05-22T10:20:14+0000", "auth_code":"" }, "code":"0", "message":"Success" }], "signature":"p6BvZTmzzzUSaN06OVT2SNxTJWvm6\/GEOSEMvUaKgLGzVO5VpKKWt27rq\ /D1HulyqMGvV0+yN6ixICqSW3oCeA==" } ``` Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки \(в примере — `422`\), а в теле — статус `error` и расширенная информация об ошибке: код ошибки в платёжной платформе \(в примере —`2003`\) и описание к нему \(в примере — `Invalid JSON string`\). ``` POST /v2/payment/status HTTP/1.1 // Запрос от веб-сервиса на получение статуса платежа в платформе HTTP/1.1 422 Unprocessable Entity // Ответ от платёжной платформы Server: nginx/1.14.2 Date: Thu, 30 May 2019 09:44:26 GMT Content-Type: application/json; charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Powered-By: PHP/7.0.33 Expires: Thu, 30 May 2019 09:44:25 GMT Cache-Control: no-cache Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive, User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type { "status":"error", "code":"2003", "message":"Invalid JSON string" } ``` ### Ответы с результатом приёма {#section_zxw_5m2_yhb .section} В этом пункте представлены примеры ответа на запрос, обрабатываемый по асинхронной схеме. Содержимое JSON-строки в этих примерах разбито на несколько строк для удобства чтения. Если запрос принят в обработку, то в стартовой строке ответа указывается код ответа `200`, а в теле — статус `success`. ``` POST /v2/payment/card/auth HTTP/1.1 // Запрос от веб-сервиса на предварительную блокировку средств HTTP/1.1 200 OK // Ответ от платёжной платформы Server: nginx/1.14.2 Date: Thu, 30 May 2019 09:52:16 GMT Content-Type: application/json; charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Powered-By: PHP/7.0.33 Expires: Thu, 30 May 2019 09:52:15 GMT Cache-Control: no-cache Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent, X-Requested-With,If-Modified-Since,Cache-Control,Content-Type { "status":"success", "request_id":"e7cdefae67068d", "project_id":69, "payment_id":"ORDER_ID__sendPurchase_dcc_1" } ``` Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки \(в примере — `400`\), а в теле — статус `error` и расширенная информация об ошибке: код ошибки в платёжной платформе \(в примере —`2004`\) и описание к нему \(в примере — `Required field not provided`\). ``` POST /v2/payment/card/auth HTTP/1.1 // Запрос от веб-сервиса на предварительную блокировку средств HTTP/1.1 400 Bad Request // Ответ от платёжной платформы Server: nginx/1.14.2 Date: Thu, 30 May 2019 09:23:23 GMT Content-Type: application/json; charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Powered-By: PHP/7.0.33 { "status":"error", "code":"2004", "message":"Required field not provided" } ``` ## Формат оповещения {#ru_gate_callbacks_format} Для передачи промежуточной и итоговой информации о результате обработки и выполнения запроса в рамках асинхронного взаимодействия используются оповещения — HTTP-запросы, отправляемые методом POST от платёжной платформы на согласованные адреса. Общая структура оповещений описана далее, а подробная информация о работе с ними — в разделе [Работа с оповещениями](ru_platform_callbacks.md). В каждом оповещении от платформы содержатся следующие элементы в порядке перечисления: - стартовая строка с указанием метода передачи запроса \(`POST`\), URI веб-сервиса для отправки оповещений о результатах \(в примере — `/notify/success`\), протокола и его версии \(`HTTP/1.1`\); - поля заголовка, в том числе поле `Host` с указанием доменного имени веб-сервиса \(в примере — `webservice.com`\); - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним \(структура и последовательность передаваемых объектов и параметров может отличаться\). Далее представлен пример итогового оповещения с информацией о результате проведения платежа. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения. ``` POST /notify/success HTTP/1.1 Content-Length: 1237 User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1 Content-Type: application/json Host: webservice.com { "account":{ "number":"431422******0056", "token":"1234567890", "type":"visa", "card_holder":"TEST TEST", "id":1234,"expiry_month":"**", "expiry_year":"****" }, "customer":{ "id":"12345", "phone":"***********" }, "payment":{ "date":"2019-06-07T11:38:31+0000", "id":"1234567890", "method":"card", "status":"success", "sum":{ "amount":1750, "currency":"EUR" }, "type":"purchase", "description":"Deposit to 1234567890" }, "project_id":25, "processingDateTime":"2019-06-07T11:38:30+0000", "country":"GB", "product_name":"Visa", "issuer_name":"", "operation":{ "id":1234567890, "type":"sale", "status":"success", "date":"2019-06-07T11:38:32+0000", "created_date":"2019-06-07T11:37:56+0000", "request_id":"1234567890-1234567890", "sum_initial":{ "amount":1750, "currency":"EUR" }, "sum_converted":{ "amount":1750, "currency":"EUR" }, "provider":{ "id":11, "payment_id":"098765432", "date":"2019-06-07T11:38:30+0000", "auth_code":"","endpoint_id":1 }, "code":"0", "message":"Success", "eci":"05" }, "signature":"qwertyuioiuytrewqwertyuu123434" } ``` --- # Разовые оплаты {#ru_Gate_purchase} статьи о порядке проведения через Gate разовых оплат с незамедлительными списаниями \(в одну стадию\) и со списаниями после предварительных блокировок средств \(в две стадии\) В этом разделе представлена информация о проведении разовых оплат.Общая информация, которая дополняет сведения из модели проведения платежей \([Проведение платежей](ru_platform_payment_model.md)\), актуальна как для работы с платёжными картами, так и для работы с альтернативными инструментами, а подробная информация актуальна только для работы с картами. Подробная информация о проведении разовых оплат при работе с альтернативными инструментами представлена в разделе [Методы](ru_pm_about.md). **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_gate_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. Разовая оплата — это тип платежа, в рамках которого осуществляется один \(разовый\) перевод денежных средств от пользователя к мерчанту. Платёжная платформа Ecommpay поддерживает следующие *варианты* таких оплат: - *Оплата в одну стадию* или одностадийная оплата. Тип платежа, в рамках которого на основании одного исходного запроса осуществляется один \(разовый\) перевод денежных средств от пользователя к мерчанту.Оплаты в одну стадию поддерживаются как при работе с платёжными картами, так и при работе с альтернативными платёжными инструментами, иприменяются в том числе для погашения кредитов и займов в микрофинансовых организациях. Подробная информация об этом варианте разовой оплаты представлена в разделе [Оплата в одну стадию](ru_gate_payment_sale.md). - *Оплата в две стадии* или двухстадийная оплата. Тип платежа, в рамках которого для перевода денежных средств от пользователя к мерчанту сначала, на основании исходного запроса, осуществляется предварительная блокировка, а затем, на основании подтверждающего запроса или по истечении заданного периода, — списание заблокированных средств или отмена блокировки. Оплаты в две стадии поддерживаются как при работе с платёжными картами, так и при работе с альтернативными платёжными инструментами.Подробная информация об этом варианте разовой оплаты представлена в разделе [Оплата в две стадии](ru_gate_payment_auth.md). - **[Оплата в одну стадию](ru_gate_payment_sale.md)** статья о порядке проведения через Gate разовых одностадийных оплат с незамедлительными списаниями - **[Оплата в две стадии](ru_gate_payment_auth.md)** статья о порядке проведения через Gate разовых двухстадийных оплат с предварительными блокировками средств и последующими списаниями **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Оплата в одну стадию {#ru_gate_payment_sale} статья о порядке проведения через Gate разовых одностадийных оплат с незамедлительными списаниями **Прим.:** Эта статья посвящена тому, как проводить разовые оплаты в одну стадию через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с разовыми оплатами в одну стадию могут быть полезны: - статья [Разовая оплата в одну стадию](ru_platform_sms_model.md) модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в одну стадию в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить разовые оплаты в одну стадию через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. **На уровень выше:**[Разовые оплаты](ru_Gate_purchase.md) ## Общая информация {#ru_gate_payment_sale_overview} При проведении разовой оплаты в одну стадию реквизиты платёжного инструмента могут указываться в одной из следующих форм: - *Реквизиты \(в явном виде\)*. Это базовая форма, при использовании которой необходимо обеспечить предоставление реквизитов пользователем, а затем передать эти реквизиты в платёжную платформу в запросе на проведение платежа.Это касается и так называемых оплат Mail Order/Telephone Order \(MO/TO\), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе [Проведение оплат MO/TO](ru_Gate_moto.md). - *Идентификатор реквизитов*. В этом случае со стороны веб-сервиса передаётся идентификатор, однозначно ассоциированный с реквизитами платёжного инструмента на стороне платёжной платформы \(подробнее — в разделе [Сохранение платёжных данных](ru_gate_saved_data.md)\). - *Токен реквизитов*. В отличие от базового способа, вместо полных реквизитов передаётся токен. Для использования этого способа необходимо провести первоначальный платёж. Подробная информация об использовании токена представлена в разделе [Использование токенов](ru_Gate_Token.md). ## Схема проведения {#ru_gate_payment_sale_workflow} Для проведения оплаты в одну стадию через Gate со стороны веб-сервиса необходимо: 1. Отправить запрос к конечной точке `/v2/payment/\{название метода\}/sale[/форма указания реквизитов платёжного инструмента]`. 2. При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже. - *Аутентификация 3‑D Secure*. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием платёжных карт через интернет. Подробная информация об этой процедуре представлена в разделе [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md). - *Аутентификация по инициативе мерчанта*. Такая аутентификация предназначена для обеспечения дополнительной безопасности оплаты с использованием платёжных карт. Подробная информация об этой процедуре представлена в разделе [Аутентификация по инициативе мерчанта](ru_gate_payment_merch_auth.md). - *Дополнение информации о платеже*. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md). 3. Принять от платёжной платформы оповещение о результате оплаты. 4. При необходимости для проведённых оплат использовать дополнительную возможность — возврат средств по проведённой оплате. Возврат используется в ситуациях, когда в рамках проведённой оплаты необходимо частично или полностью вернуть средства пользователю. Подробная информация о возвратах представлена в разделе [Возвраты средств после оплат](ru_Gate_Refund.md). Схема проведения оплаты в одну стадию в базовом случае — без выполнения дополнительных процедур — представлена далее. ![](images/purchase_schemes/ru_gate_schema_sale.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты в одну стадию. 3. Запрос на проведение оплаты в одну стадию поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой его корректности. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. В платёжной платформе выполняется обработка этого запроса, его преобразование и отправка в платёжную систему в соответствии с протоколом взаимодействия с ней. 7. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 8. На стороне эмитента выполняется обработка платежа и списание средств пользователя. 9. От эмитента к платёжной системе направляется уведомление о результате оплаты. 10. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты. 11. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 12. От веб-сервиса пользователю направляется результат оплаты. Далее приведена информация о формате запросов и параметрах инициирования оплаты в одну стадию с использованием платёжных карт, а также о формате оповещений с результатами оплаты. Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_sms_model.md). ## Формат запросов {#ru_gate_payment_sale_request_format} Формат запросов в этом разделе представлен для проведения оплат в одну стадию с использованием *платёжных карт*. При формировании запросов необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - при передаче реквизитов карты в явном виде — к [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale); - при передаче идентификатора вместо реквизитов — к [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved); - при передаче токена вместо реквизитов — к [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта мерчанта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя; - `id` — идентификатор пользователя в рамках проекта мерчанта; - `screen_res` — разрешение экрана устройства пользователя, в пикселях и с символом `x` в качестве разделителя \(например, `360x640`\); - `email` — адрес электронной почты пользователя; - `phone` — номер телефона пользователя; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_gate_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. 3. В запросе должны содержаться сведения о платёжной карте пользователя: - при передаче реквизитов карты в явном виде — следующие данные в объекте `card`: - `pan` — номер карты; - `year` — порядковый номер года, в котором заканчивается срок действия карты \(в четырёхзначном формате `YYYY` по григорианскому календарю\); - `month` — порядковый номер месяца, в котором заканчивается срок действия карты \(в виде числа, без ведущего нуля\); - `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта \(это имя должно указываться в соответствии с написанием на карте, а исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\); - `cvv` — код проверки подлинности карты \(в соответствии с указанным на карте\); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе [Проведение оплат MO/TO](ru_Gate_moto.md); - при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платёжной платформе, и код проверки подлинности карты в параметрах `saved_account_id` и `cvv`; - при передаче токена — токен и код проверки подлинности карты в параметрах `token` и `cvv`. 4. В запросе должен содержаться объект `return_url` с адресами для перенаправления пользователя к веб-сервису: - `success` — URL для перенаправления после завершения платежа; - `decline` — URL для перенаправления после отклонения платежа. 5. В зависимости от специфических региональных требований, а также от требований провайдеров и платёжных систем, в запросе может понадобиться указать дополнительные сведения о пользователе: - `first_name` — имя пользователя; - `last_name` — фамилия; - `middle_name` — отчество или среднее имя; - `day_of_birth` — дата рождения; - `phone` — номер телефона с кодом страны; - `email` — адрес электронной почты; - `zip` — почтовый индекс адреса проживания; - `address` — адрес проживания \(улица, номер дома\); - `city` — город проживания \(или иной населенный пункт\); - `district` — округ \(район, область и т.д.\) проживания; - `state` — регион проживания \(штат, графство, кантон и т.д.\); - `avs_post_code` — почтовый индекс, зафиксированный эмитентом как актуальный для пользователя; - `avs_street_address` — улица и номер дома, зафиксированные эмитентом как актуальные для пользователя. Для получения информации о наборе сведений, требуемом в каждом конкретном случае, следует обращаться к курирующему менеджеру Ecommpay. Если необходимые сведения не были переданы в запросе, со стороны веб-сервиса потребуется выполнить процедуру [дополнения информации о платеже](ru_Gate_Clarification.md). 6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на оплату в одну стадию с использованием платёжных карт должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму платежа, а также реквизиты платёжной карты в какой-либо из форм. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "customer": { "ip_address": "248.121.176.220", "id": "customer_12", "screen\_res": "360x640", "phone": "44991234567", "email": "john\_smith@email.com" }, "payment": { "amount": 400000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "decline": "https://example.com/decline" }, //при передаче реквизитов карты в явном виде: "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JOHN SMITH", "cvv": "123" } //при передаче идентификатора ранее сохранённой платёжной карты: "saved_account_id": 2345678, "cvv": "123" //при передаче токена ранее сохранённой платёжной карты: "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "cvv": "123" } ``` ## Формат данных для перенаправления пользователей {#ru_gate_payment_sale_redirect_form} В зависимости от платёжной системы, обрабатывающей платёж, для завершения оплаты может потребоваться перенаправление пользователя от веб-сервиса на сайт платёжной системы. Для этого необходимо принять оповещение от платёжной платформы Ecommpay, содержащее объект `redirect_data` с параметрами: - `redirect_data.url` — ссылка для перенаправления пользователя, - `redirect_data.body` — данные для отправки запроса \(может быть пустым\), - `redirect_data.method` — метод отправки запроса. Далее приведён пример оповещения, содержащего данные для перенаправления. Данное оповещение отправляется от платёжной платформы Ecommpay на URL, указанный в настройках проекта мерчанта. В таком случае платеж находится в статусе `awaiting redirect result` до момента завершения оплаты со стороны пользователя. ``` "type": "redirect", "code": "0", "operation_id": 64897000022161, "request_type": "purchase", "redirect_data": { "body": { }, "method": "POST", "url": "https://payment.asiapaygateway.com/payment/DirectInterface", "encrypted": { "key": 3, "message": "d4d9aa52891d0a59c40069bae69b57e872d0e946b70c67860e9c3e3b182cf240033a..." } ``` ## Формат оповещений {#ru_gate_payment_sale_callback_format} Для оповещения о результате оплаты в одну стадию с использованием платёжных карт используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` была проведена оплата в одну стадию в размере `4 000,00 USD` с платёжной карты `№424242******4243`. ```language-json { "account": { "number": "431422******0056", "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type": "visa", "card_holder": "JOHN SMITH", "id": 45678, "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2019-01-11T13:02:42+0000", "id": "456789", "method": "card", "status": "success", "sum": { "amount": 400000, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2019-01-11T13:02:42+0000", "created_date": "2019-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 400000, "currency": "USD" }, "sum_converted": { "amount": 400000, "currency": "USD" }, "provider": { "id": 408, "payment_id": "330157196", "date": "2019-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении оплаты. Оплата отклонена из-за ввода некорректных данных карты. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "decline", "date": "2019-01-11T14:11:33+0000", "method": "card", "sum": { "amount": 400000, "currency": "USD" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 13300000004505, "type": "sale", "status": "decline", "date": "2019-01-11T14:11:33+0000", "created_date": "2019-01-11T14:11:00+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 400000, "currency": "USD" }, "sum_converted": { "amount": 400000, "currency": "USD" }, "provider": { "id": 12, "payment_id": "48219213050", "auth_code": "", "endpoint_id": 12 }, "code": "10102", "message": "Incorrect data entered", "eci": "05" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` --- # Оплата в две стадии {#ru_gate_payment_auth} статья о порядке проведения через Gate разовых двухстадийных оплат с предварительными блокировками средств и последующими списаниями **Прим.:** Эта статья посвящена тому, как проводить разовые оплаты в две стадии через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с разовыми оплатами в две стадии могут быть полезны: - статья [Разовая оплата в две стадии](ru_platform_dms_model.md) модели проведения платежей с описанием того, как в целом проводятся разовые оплаты в две стадии в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить разовые оплаты в две стадии через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. **На уровень выше:**[Разовые оплаты](ru_Gate_purchase.md) ## Общая информация {#ru_gate_payment_auth_overview} В рамках платёжной платформы оплаты в две стадии проводятся в соответствии с моделью проведения платежей \([Разовая оплата в две стадии](ru_platform_dms_model.md)\): с инициированием *первой стадии* такой оплаты по запросу со стороны веб-сервиса мерчанта, а *второй стадии* — по запросу или автоматически по истечении заданного срока. Информация о двухстадийных оплатах с прямым использованием платёжных карт содержится в данном разделе, а информация о таких оплатах с использованием альтернативных платёжных методов — в разделе [Методы](ru_pm_about.md). Сумму средств, предварительно заблокированных в результате выполнения первой стадии такой оплаты, можно изменить по запросу со стороны веб-сервиса мерчанта. Такие изменения могут выполняться как однократно, с одновременным инициированием второй стадии оплаты, так и многократно, с необходимостью последующего инициирования второй стадии по запросу или автоматически. Для настройки автоматического инициирования второй стадии оплаты, то есть автоматического списания средств или отмены их блокировки, следует обращаться к специалистам технической поддержки \([support@ecommpay.com](mailto:support@ecommpay.com)\). При этом срок блокировки и тип операции, которую необходимо выполнить по истечении этого срока, указываются со стороны мерчанта. Информацию о возможности проведения таких оплат необходимо уточнять у службы технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). При проведении разовой оплаты в две стадии реквизиты платёжного инструмента могут указываться в одной из следующих форм: - *Реквизиты \(в явном виде\)*. Это базовая форма, при использовании которой необходимо обеспечить предоставление реквизитов пользователем, а затем передать эти реквизиты в платёжную платформу в запросе на проведение платежа.Это касается и так называемых оплат Mail Order/Telephone Order \(MO/TO\), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе [Проведение оплат MO/TO](ru_Gate_moto.md). - *Идентификатор реквизитов*. В этом случае со стороны веб-сервиса передаётся идентификатор, однозначно ассоциированный с реквизитами платёжного инструмента на стороне платёжной платформы\(подробнее — в разделе [Сохранение платёжных данных](ru_gate_saved_data.md)\). - *Токен реквизитов*. В отличие от базового способа, вместо полных реквизитов передаётся токен. Для использования этого способа необходимо провести первоначальный платёж.Подробная информация об использовании токена представлена в разделе [Использование токенов](ru_Gate_Token.md). ## Ограничения {#ru_gate_payment_auth_time_limit} ### Ограничение максимальных сроков блокировки {#section_vqt_zsr_vlb .section} При проведении оплат в две стадии необходимо учитывать, что в соответствии с требованиями международных платёжных систем Visa, Mastercard и American Express срок, на который можно заблокировать средства пользователя, ограничивается. И для различных типов карт этот срок определяется с учётом разных условий: - Для карт платёжной системы Visa: 1. если блокировка средств выполняется в рамках повторяемой оплаты — 5 дней; 2. если блокировка средств выполняется не в рамках повторяемой оплаты и без её регистрации, а присвоенный мерчанту код Merchant Category Code \(MCC\) соответствует одному из следующих: 3351–3500, 3501–3999, 4411, 7011, 7512, 7513 — 30 дней; 3. в других случаях — 10 дней. - Для карт Maestro и Cirrus — 6 дней. - Длядругих карт платёжной системы Mastercard — 28 дней. - Для карт платёжной системы American Express: 1. если в соответствии с присвоенным мерчанту кодом Merchant Category Code \(MCC\) его деятельность относится к гостиничному бизнесу, аренде автомобилей или организации круизов — на весь срок проживания, аренды или круиза соответственно; 2. в других случаях — 7 дней. Максимально допустимый срок блокировки средств отсчитывается от момента формирования в платёжной платформе Ecommpay операции блокировки \(`auth`\). За полчаса до истечения этого срока в зависимости от параметров, указанных сотрудниками Ecommpay, автоматически выполняется одна из следующих операций: списание заблокированных средств пользователя \(`capture`\) или отмена блокировки средств \(`cancel`\). После этого к веб-сервису направляется оповещение, описание формата которого представлено в разделе [Формат оповещений](ru_gate_payment_auth.md). Для уточнения информации и изменения типа операции следует обратиться к курирующему менеджеру Ecommpay.Исключением являются блокировки с использованием карт платёжной системы American Express, максимально допустимый срок для которых соответствует сроку проживания, аренды или круиза: для таких блокировок автоматическое списание не выполняется. В случаях, когда в платёжной платформе настроено автоматическое списание или отмена блокировки средств в указанный со стороны мерчанта срок, но этот срок превышает максимально допустимый, списание или отмена выполняются в соответствии с максимально допустимым сроком.Допустим, в соответствии с пожеланиями мерчанта настроена автоматическая отмена блокировки по истечении десяти дней. Тогда для блокировки средств, выполненной с использованием карты Maestro \(с максимально допустимым сроком в шесть дней\), по истечении шести дней выполняется автоматическая отмена. ### Ограничение возможности изменения суммы {#section_zpr_z1m_mnb .section} Изменение суммы предварительно заблокированных средств поддерживается только для оплат с использованием карт платёжных систем Mastercard и Visa с учётом следующих ограничений: - После уменьшения суммы заблокированных средств оставшаяся сумма должна составлять не менее 0,01 USD или эквивалента в другой валюте с учётом курса для этой валюты. Если оставшаяся сумма меньше требуемой, запрос на уменьшение суммы отклоняется с кодом ошибки `3117`. - Для оплат с использованием карт платёжной системы Visa изменение суммы более чем на 15 % поддерживается только при соответствии присвоенного мерчанту MCC одному из следующих: 3351–3500, 3501–3999, 4111, 4112, 4121, 4131, 4411, 4457, 5411, 5552, 5812, 5813, 7011, 7033, 7394, 7512, 7513, 7519, 7523, 7996, 7999. При любых других MCC мерчанта допускается изменение суммы в пределах 15 % от первоначально заблокированной. Для оплат с использованием карт платёжной системы American Express эта возможность не поддерживается. ## Схема проведения {#ru_gate_payment_auth_workflow} Для проведения оплаты в две стадии через Gate со стороны веб-сервиса необходимо: 1. Отправить запрос на предварительную блокировку к конечной точке `/v2/payment/card/auth[/форма указания реквизитов платёжного инструмента]`. 2. При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже. - *Аутентификация 3‑D Secure*. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием платёжных карт через интернет. Подробная информация об этой процедуре представлена в разделе [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md). - *Аутентификация по инициативе мерчанта*. Такая аутентификация предназначена для обеспечения дополнительной безопасности оплаты с использованием платёжных карт. Подробная информация об этой процедуре представлена в разделе [Аутентификация по инициативе мерчанта](ru_gate_payment_merch_auth.md). - *Дополнение информации о платеже*. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md). 3. Принять от платёжной платформы оповещение о результате предварительной блокировки. 4. При необходимости изменить сумму предварительно заблокированных средств без одновременного подтверждения их списания — отправить запрос, содержащий требуемые параметры и подпись, к одной из следующих конечных точек: - `/v2/payment/card/incremental` — для увеличения суммы заблокированных средств; - `/v2/payment/card/cancel` — для уменьшения суммы предварительно заблокированных средств. После чего принять оповещение о результате изменения суммы средств. 5. Отправить запрос на списание средств, содержащий требуемые параметры и подпись, к конечной точке `/v2/payment/card/capture` или на отмену блокировки — к конечной точке `/v2/payment/card/cancel`. При необходимости списать сумму, отличную от суммы заблокированных средств, в запросе к конечной точке `/v2/payment/card/capture` необходимо указать сумму для списания и код валюты. 6. Принять от платёжной платформы оповещение о результате списания средств \(или об отмене блокировки средств\). 7. При необходимости для проведённых оплат использовать дополнительную возможность — возврат средств по проведённой оплате. Возврат используется в ситуациях, когда в рамках проведённой оплаты необходимо частично или полностью вернуть средства пользователю. Подробная информация о возвратах представлена в разделе [Возвраты средств после оплат](ru_Gate_Refund.md). Схема проведения оплаты в две стадии в базовом случае — без выполнения дополнительных процедур — со списанием заблокированных средств представлена далее. ![](images/purchase_schemes/ru_gate_schema_auth_capture.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на предварительную блокировку средств. 3. Запрос на проведение предварительной блокировки поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой его корректности. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. В платёжной платформе выполняются обработка этого запроса, его преобразование и отправка в международную платёжную систему в соответствии с протоколом взаимодействия с ней. 7. В международной платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 8. На стороне эмитента выполняется обработка платежа и блокировка средств пользователя. 9. От эмитента к международной платёжной системе направляется уведомление о результате. 10. От международной платёжной системы к платёжной платформе направляется уведомление о результате. 11. От платёжной платформы к веб-сервису направляется оповещение о результате. 12. От веб-сервиса пользователю направляется результат оплаты. 13. От веб-сервиса на заданный URL Ecommpay передаётся запрос на списание средств \(или на отмену блокировки средств\). 14. Запрос на списание средств \(или на отмену блокировки средств\) поступает в платёжную платформу. 15. В платёжной платформе выполняется приём запроса с начальной проверкой. 16. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 17. В платёжной платформе выполняются обработка этого запроса, его преобразование и отправка в международную платёжную систему в соответствии с протоколом взаимодействия с ней. 18. В международной платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 19. На стороне эмитента выполняется обработка платежа и списание средств пользователя \(или отмена предварительной блокировки средств\). 20. От эмитента к международной платёжной системе направляется уведомление о результате. 21. От международной платёжной системы к платёжной платформе направляется уведомление о результате. 22. От платёжной платформы к веб-сервису направляется оповещение о результате. 23. В случае отмены блокировки от веб-сервиса пользователю направляется результат. Информация о формате запросов и параметрах инициирования операций оплаты в две стадии с прямым использованием платёжных карт через Gate, а также о формате оповещений о результатах операций приведена далее; общая информация о работе с API — в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_dms_model.md). ## Формат запросов {#ru_gate_payment_auth_request_format} Формат запросов в этом разделе представлен для проведения оплат в две стадии с использованием *платёжных карт*. Необходимо учитывать, что проведение оплат в две стадии включает в себя отправку запросов на предварительную блокировку средств и на списание средств или отмену блокировки. ### Запрос на предварительную блокировку {#section_ps3_mnb_v3b .section} При формировании запросов необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - при передаче реквизитов карты в явном виде — [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth), - при передаче идентификатора вместо реквизитов карты— [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved), - при передаче токена вместо реквизитов карты — [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя; - `id` — идентификатор пользователя в рамках проекта мерчанта; - `screen_res` — разрешение экрана устройства пользователя, в пикселях и с символом `x` в качестве разделителя \(например, `360x640`\); - `email` — адрес электронной почты пользователя; - `phone` — номер телефона пользователя; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3. - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_gate_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. 3. В запросе должны содержаться сведения о платёжной карте пользователя: - при передаче реквизитов карты в явном виде — следующие данные в объекте `card`: - `pan` — номер карты; - `year` — порядковый номер года, в котором заканчивается срок действия карты \(в четырёхзначном формате `YYYY` по григорианскому календарю\); - `month` — порядковый номер месяца, в котором заканчивается срок действия карты \(в виде числа, без ведущего нуля\); - `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта \(это имя должно указываться в соответствии с написанием на карте, а исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\); - `cvv` — код проверки подлинности карты \(в соответствии с указанным на карте\); при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе [Проведение оплат MO/TO](ru_Gate_moto.md); - при передаче идентификатора — идентификатор, ассоциированный с реквизитами карты в платёжной платформе, и код проверки подлинности карты в параметрах `saved_account_id` и `cvv`; - при передаче токена — токен и код проверки подлинности карты в параметрах `token` и `cvv`. 4. В запросе должен содержаться объект `return_url` с адресами для перенаправления пользователя к веб-сервису: - `success` — URL для перенаправления после завершения платежа; - `decline` — URL для перенаправления после отклонения платежа. 5. Если необходимо зачислить средства на электронный кошелёк мерчанта, в объекте `customer` дополнительно должны использоваться следующие параметры: - `first_name` — имя пользователя, - `last_name` — фамилия, - `address` — адрес проживания \(улица, номер дома\), - `email` — адрес электронной почты, - `city` — город проживания \(или иной населенный пункт\), - `state` — регион проживания \(штат, графство, кантон и т.д.\). 6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на оплату в одну стадию с использованием платёжных карт должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму платежа, а также реквизиты платёжной карты в какой-либо из форм. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "customer": { "ip_address": "248.121.176.220", "id": "customer_12", "screen\_res": "360x640", "phone": "44991234567", "email": "john\_smith@email.com" }, "payment": { "amount": 15000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "decline": "https://example.com/decline" }, //при передаче реквизитов карты в явном виде: "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JOHN SMITH", "cvv": "123" } //при передаче идентификатора ранее сохранённой платёжной карты: "saved_account_id": 2345678, "cvv": "123" //при передаче токена ранее сохранённой платёжной карты: "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "cvv": "123" } ``` ### Запрос на увеличение суммы заблокированных средств {#section_y1l_b1s_mnb .section} Запрос отправляется методом POST к конечной точке [/v2/payment/card/incremental](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-incremental) и должен содержать следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя в рамках проекта мерчанта; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма, на которую необходимо увеличить сумму заблокированных средств, в дробных единицах валюты; - `currency` — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку. - Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на увеличение суммы заблокированных средств должен содержать идентификаторы проекта и платежа, подпись, а также сумму, на которую необходимо увеличить сумму заблокированных средств, и код валюты. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "customer": { "id": "customer_12" }, "payment": { "amount": 1000, "currency": "USD" } } ``` ### Запрос на списание заблокированных средств {#section_vgl_r1g_k3b .section} Запрос отправляется методом POST к конечной точке [/v2/payment/card/capture](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-capture) и должен содержать следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Перечисленных параметров достаточно для списания всей суммы заблокированных средств. Чтобы списать часть суммы или сумму больше заблокированной, в объекте `payment` дополнительно необходимо использовать следующие параметры: - `amount` — итоговая сумма списания в дробных единицах валюты; - `currency` — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку. Таким образом, корректный запрос на списание заблокированных средств должен содержать идентификаторы проекта и платежа, подпись и, при необходимости, сумму и код валюты списания. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } } ``` ### Запрос на уменьшение суммы или отмену блокировки средств {#section_flr_s1g_k3b .section} Запрос отправляется методом POST к конечной точке [/v2/payment/card/cancel](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-cancel) и должен содержать следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Перечисленных параметров достаточно для отмены блокировки всей суммы средств. Чтобы уменьшить сумму заблокированных средств, в объекте `payment` дополнительно необходимо использовать следующие параметры: - `amount` — сумма, на которую необходимо уменьшить сумму заблокированных средств, в дробных единицах валюты; - `currency` — код валюты в формате ISO-4217 alpha-3, должен соответствовать коду валюты, переданному в запросе на блокировку. Таким образом, корректный запрос на отмену блокировки средств должен содержать идентификаторы проекта и платежа, подпись и, при необходимости, сумму, на которую необходимо уменьшить сумму заблокированных средств, и код валюты списания. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } } ``` ## Формат оповещений {#ru_gate_payment_auth_callback_format} Для оповещения о результате оплаты в две стадии используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` заблокированы средства в размере `150,00 USD` с платёжной карты `№555555******4445`. ```language-json { "project_id": 42, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "id": "456789", "type": "purchase", "status": "awaiting capture", "date": "2019-01-11T13:00:40+0000", "method": "card", "sum": { "amount": 15000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "operation": { "id": 2777000002350, "type": "auth", "status": "success", "date": "2019-01-11T13:00:40+0000", "created_date": "2019-01-11T13:00:37+0000", "request_id": "e2fd233d27c064fbe01af291039e6478341a0489-3...9", "sum_initial": { "amount": 15000, "currency": "USD" }, "sum_converted": { "amount": 15000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "224750650", "date": "2019-01-11T13:00:39+0000", "result_code": "000", "result_message": "Approved", "auth_code": "505050", "endpoint_id": 120 }, "code": "0", "message": "Success", "description": "SUCCESS", "eci": "00" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` В следующем примере блокировка средств была отклонена из-за указания некорректной даты окончания срока действия карты. ```language-json { "project_id": 42, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "id": "456789", "type": "purchase", "status": "decline", "date": "2019-01-11T13:00:40+0000", "method": "card", "sum": { "amount": 15000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "operation": { "id": 6304000002973, "type": "auth", "status": "decline", "date": "2019-01-11T13:00:40+0000", "created_date": "2019-01-11T13:00:34+0000", "request_id": "63821f1e49b2b289d1dee0552082ed60b4108175-5...c", "sum_initial": { "amount": 15000, "currency": "USD" }, "sum_converted": { "amount": 15000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "239689120", "date": "2019-01-11T13:00:36+0000", "result_code": "101", "result_message": "Decline, expired card", "auth_code": "", "endpoint_id": 120 }, "code": "10106", "message": "Card expired", "description": "Bank cards. Operation was declined due to incorrect card expiry date entry", "eci": "00" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` В следующем примере содержится информация о том, что в рамках проекта `42` сумма средств, заблокированных на платёжной карте `№555555******4445` пользователя `customer_12`, увеличена на `10,00 USD`. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "awaiting capture", "date": "2019-01-11T15:54:40+0000", "method": "card", "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 7178000006589, "type": "incremental", "status": "success", "date": "2019-01-11T15:54:40+0000", "created_date": "2019-01-11T15:54:39+0000", "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0", "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "227307324", "date": "2019-01-11T15:54:40+0000", "auth_code": "919372", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` В следующем примере содержится информация о том, что в рамках проекта `42` с платёжной карты `№555555******4445` пользователя `customer_12` списаны заблокированные ранее средства в размере `160,00 USD`. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "success", "date": "2019-01-11T15:54:40+0000", "method": "card", "sum": { "amount": 16000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 7178000006597, "type": "capture", "status": "success", "date": "2019-01-11T15:54:40+0000", "created_date": "2019-01-11T15:54:39+0000", "request_id": "d066dfd72443584e1a35bb5eed60415aeb15ccfa-1...0", "sum_initial": { "amount": 16000, "currency": "USD" }, "sum_converted": { "amount": 16000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "227307324", "date": "2019-01-11T15:54:40+0000", "auth_code": "919372", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` В следующем примере содержится информация о том, что в рамках проекта `42` для пользователя `customer_12` отменена блокировка средств в размере `160,00 USD` на платёжной карте `№555555******4445`. ```language-json { "project_id": 42, "payment": { "id": "456789", "type": "purchase", "status": "canceled", "date": "2019-01-11T15:54:40+0000", "method": "card", "sum": { "amount": 16000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "operation": { "id": 18289000007021, "type": "cancel", "status": "success", "date": "2019-01-11T15:54:40+0000", "created_date": "2019-01-11T15:54:40+0000", "request_id": "25cdabfad200b82bf6740d6a8d01818c6e64804e-1...c", "sum_initial": { "amount": 16000, "currency": "USD" }, "sum_converted": { "amount": 16000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "239672146", "auth_code": "", "endpoint_id": 120 }, "code": "0", "message": "Success" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` В следующем примере отмена блокировки средств была отклонена из-за указания некорректных данных карты. ```language-json { "account": { "number": "541333******0019", "type": "mastercard", "card_holder": "JOHN SMITH", "expiry_month": "08", "expiry_year": "2025" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2019-01-11T15:54:40+0000", "id": "456789", "method": "card", "status": "decline", "sum": { "amount": 16000, "currency": "USD" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 18397000002376, "type": "cancel", "status": "decline", "date": "2019-01-11T15:54:40+0000", "created_date": "2019-01-11T15:54:35+0000", "request_id": "7482145798366de3166bedd372552b3f0094eed2-6...3", "sum_initial": { "amount": 16000, "currency": "USD" }, "sum_converted": { "amount": 16000, "currency": "USD" }, "provider": { "id": 120, "payment_id": "248013808", "date": "2019-01-10T22:37:10+0000", "auth_code": "876856", "endpoint_id": 120 }, "code": "10102", "message": "Incorrect data entered" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` --- # Оплаты по платёжным ссылкам {#ru_gate_invoice} статья о порядке проведения через Gate оплат в одну и две стадии с использованием платёжных ссылок и перенаправлением пользователей к платёжной форме Payment Page **Прим.:** Эта статья посвящена тому, как проводить оплаты по платёжным ссылкам через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с оплатами по платёжным ссылкам могут быть полезны: - статья [Оплата по платёжной ссылке](ru_platform_invoice_model.md) модели проведения платежей с описанием того, как в целом проводятся оплаты по платёжным ссылкам в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - [описание](ru_dbl_payments.md) того, как проводить оплаты по платёжным ссылкам через Dashboard; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводятся оплаты с использованием платёжной формы Payment Page в контексте пользовательских сценариев и общих схем взаимодействия. **На уровень выше:**[Gate](ru_Gate_Integration_About.md) ## Общая информация {#ru_gate_invoice_overview} *Оплата по платёжной ссылке* — это тип платежа, в рамках которого на основании одного исходного запроса сначала создаётся и отправляется пользователю платёжная ссылка, а затем, при переходе по этой ссылке и подтверждении платежа, выполняется переводили серия переводов денежных средств от пользователя к мерчанту. Как правило, оплаты по ссылкам используются для разовых расчётов, с предварительной блокировкой средств или без таковой. Вместе с тем, когда это актуально, при проведении оплат по ссылкам можно регистрировать [повторяемые оплаты](ru_Gate__payments_on_saved_data.md), а в рамках работы с отдельными платёжными методами можно использовать платёжные ссылки только для получения согласия пользователей на регистрацию повторяемых оплат, без фактических списаний. Такие оплаты проводятся с использованием платёжной формы Payment Page, ссылка для открытия которой отправляется на электронную почту пользователя через платформу Ecommpay или любым другим способом со стороны мерчанта. Дата и время окончания срока действия ссылки и вариант проведения платежа определяются на стороне мерчанта и указываются в параметрах запроса на его инициирование, при этом срок действия ссылки не может превышать 30 суток \(с момента формирования ссылки в платформе и до момента получения в платформе запроса на инициирование платежа\) и по его истечении от платформы отправляется соответствующее оповещение.Также в параметрах такого запроса можно указать платёжный метод, с использованием которого необходимо провести платёж, или предоставить пользователю возможность выбора из всех методов, подключенных для проекта мерчанта. Так как оплаты по платёжной ссылке проводятся с использованием платёжной формы Payment Page, в параметрах запросов на инициирование таких оплат реквизиты платёжного инструмента либо не указываются, либо указываются в форме токена карты. В последнем случае пользователю понадобится только подтвердить подлинность платёжного инструмента, без указания его реквизитов в платёжной форме. Как и при проведении других типов платежей, в процессе проведения оплаты по платёжной ссылке может потребоваться выполнить вспомогательные процедуры, такие как аутентификация с использованием технологии 3‑D Secure, дополнение информации о платеже и конвертация валют. Эти процедуры полностью выполняются на стороне Payment Page, дополнительных действий со стороны веб-сервиса мерчанта при этом не требуется. ## Сценарии использования {#ru_gate_invoice_scenarios} Допустим, пользователь веб-сервиса оформил заказ на сумму `1379,50 USD` и выбрал возможность оплаты по платёжной ссылке, указав для получения ссылки свой адрес электронной почты — `eddington@mail.uk`. ### Проведение платежа {#section_u3k_51f_5kb .section} ![](images/ecommpay/ru_gate_invoice_1.svg "Открытие платёжной формы и указание необходимых данных") ![](images/ecommpay/ru_gate_invoice_2.svg "Получение информации о результате") 1. Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос с параметрами, необходимыми для отправки платёжной ссылки пользователю средствами Ecommpay. 2. Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на указанный в запросе адрес электронной почты письмо. Стандартный язык письма — английский. 3. Пользователь переходит по ссылке, после чего ему отображается Payment Page.Если в запросе на инициирование платежа не указан платёжный метод, то пользователю отображается страница выбора платёжного метода, а если платёжный метод указан — страница указанного платёжного метода. 4. Пользователь указываетплатёжные данные и подтверждает оплату, а также, при необходимости, осуществляет дополнительные действия, требуемые для выполнения одной или нескольких вспомогательных процедур. 5. По результатам проведения платежа к веб-сервису направляется оповещение о результате, а пользователю отображается страница результата оплаты. ### Отмена платежа {#section_urr_zsf_5kb .section} 1. Со стороны веб-сервиса мерчанта к платёжной платформе отправляется запрос на отмену платежа. 2. Платёжная платформа обрабатывает такой запрос, направляет оповещение к веб-сервису мерчанта и отправляет на ранее указанный адрес электронной почты письмо, стандартные вид и содержание которого представлены в примере далее. Стандартный язык письма — английский. ![](images/ecommpay/ru_gate_invoice_4.svg "Пример письма об отмене платежа") 3. Если пользователь переходит по платёжной ссылке, ему отображается сообщение об ошибке. ### Истечение срока действия ссылки {#section_if1_btf_5kb .section} 1. К веб-сервису мерчанта направляется оповещение об истечении срока действия платёжной ссылки. 2. Если пользователь переходит по платёжной ссылке, ему отображается страница с уведомлением об истечении срока действия платёжной ссылки. ![](images/ecommpay/ru_gate_invoice_3.svg "Пример страницы с уведомлением об истечении срока действия платёжной ссылки") Детальные сведения о том, что необходимо делать со стороны мерчанта для проведения платежа, представлены далее. ## Настройка {#ru_gate_invoice_custom} ### Оформление писем {#section_vjk_3nx_1lb .section} По умолчанию в письмах, отправляемых пользователям, содержатся адрес отправителя, noreply@ecommpay.com, тема письма с указанием названия мерчанта или используемого проекта \(в соответствии с указанными в платформе\), например `Payment Link from Cosmoshop`, а также сведения из запроса на создание платёжной ссылки: - идентификатор платежа \(`payment_id`\); - сумма \(`amount`\) и валюта \(`currency`\) платежа; - дата и время окончания срока действия платёжной ссылки \(`best_before`\); - описание платежа \(`description`\). ![](images/ecommpay/ru_gate_invoice_5.svg "Пример шаблона письма") По желанию мерчанта можно указать адрес электронной почты, который следует отображать пользователю в качестве адреса отправителя, а также изменить язык письма и состав данных, которые необходимо передавать в его составе, или предоставить собственную вёрстку такого письма. По всем вопросам, связанным с изменением содержания и оформления писем, следует обращаться к специалистам технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com). ### Оформление платёжной формы {#section_kfw_3nx_1lb .section} По умолчанию пользователю отображается платёжная форма с типовым вариантом оформления от Ecommpay. По желанию мерчант может настроить собственный вариант оформления, применив различные изменения к отдельным элементам платёжной формы с помощью соответствующего [конструктора](ru_PP__design_customisation.md). С вопросами, выходящими за рамки возможностей конструктора, можно обращаться к курирующему менеджеру. ## Схема проведения {#ru_gate_invoice_workflow} Для проведения оплаты по платёжной ссылке через Gate необходимо: 1. Отправить [запрос на оплату по платёжной ссылке](ru_gate_invoice.md#section_qxt_mz3_tkb) к конечной точке `/v2/payment/invoice[/card/token]/create`. 2. Принять [оповещение о создании платёжной ссылки](ru_gate_invoice.md#section_h1k_nz3_tkb). 3. Если исходно не инициирована отправка платёжной ссылки пользователю средствами платформы Ecommpay \(и подразумевается отправка средствами веб-сервиса\), отправить ссылку пользователю \(по электронной почте или любым другим способом\). 4. Принять [оповещение о результате оплаты](ru_gate_invoice.md#section_yd1_4tk_tkb) или [оповещение об истечении срока действия ссылки](ru_gate_invoice.md#section_wv1_yjq_tkb). Для проведения оплаты по платёжной ссылке в две стадии дополнительно требуется выполнить вторую стадию такой оплаты: подтверждение списания заблокированных средств или отмену блокировки. Подробная информация о выполнении второй стадии оплаты в две стадии представлена в разделе [Оплата в две стадии](ru_gate_payment_auth.md). Схема проведения оплаты по платёжной ссылке представлена далее. ![](images/ru_gate_invoice_uml.svg) 1. От веб-сервиса на заданный URL Ecommpay передаётся запрос на оплату по платёжной ссылке. 2. Запрос поступает в платёжную платформу. 3. В платёжной платформе выполняется приём запроса с проверкой его корректности. 4. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 5. В платёжной платформе осуществляется обработка запроса. 6. От платёжной платформы к веб-сервису мерчанта направляется оповещение о создании платёжной ссылки. 7. От платёжной платформы на электронную почту пользователя \(или от веб-сервиса мерчанта на электронную почту либо другим способом\) отправляется платёжная ссылка. 8. Пользователь переходит по этой платёжной ссылке. 9. Запрос на открытие платёжной формы поступает в платёжную платформу. 10. В платёжной платформе осуществляется обработка запроса. 11. Осуществляется генерация Payment Page согласно настройкам проекта. 12. Пользователю отображается ранее сгенерированная платёжная форма. 13. Пользователь указываетплатёжные данные и подтверждает оплату. 14. Запрос на проведение оплаты поступает в платёжную платформу. 15. Выполняются обработка запроса и его отправка в платёжную систему \(или в сервис провайдера\). 16. В платёжной системе \(или в сервисе провайдера\) выполняется обработка платежа. 17. От платёжной системы \(или сервиса провайдера\) к платёжной платформе направляется уведомления о результате платежа. 18. От платёжной платформы к веб-сервису направляется оповещение о результате платежа. 19. От платёжной платформы к Payment Page направляется результат платежа. 20. Результат платежа отображается пользователю на Payment Page. Для отмены такой оплаты до её подтверждения пользователем необходимо: 1. Отправить [запрос на отмену платежа](ru_gate_invoice.md#section_nnb_tgk_tkb) к конечной точке `/v2/payment/invoice/cancel`. 2. Принять [оповещение об отмене платежа](ru_gate_invoice.md#section_nkb_ntk_tkb). Далее приведена информация о форматах запросов и параметрах инициирования оплаты по платёжной ссылке и её отмены, а также о форматах оповещений, используемых при проведении платежа. Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_invoice_model.md). ## Форматы запросов {#ru_gate_invoice_format_request} ### Формат запроса на проведение платежа {#section_qxt_mz3_tkb .section} При формировании запросов необходимо учитывать следующее: 1. Должен использоваться POST-запрос кодной из следующих конечных точек: [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)или [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя в веб-сервисе мерчанта; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3; - `best_before` — дата и время окончания срока действия платёжной ссылки в формате `YYYY-MM-DDThh:mm:ss±hh:mm`; необходимо указывать таким образом, чтобы срок действия ссылки не превышал 30 суток. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_gate_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. 3. При инициировании оплаты с использованием токена платёжной карты он должен указываться в параметре `token`. 4. Для отправки платёжной ссылки средствами платформы Ecommpay должны передаваться следующие параметры: - `send_email` — указатель необходимости автоматической отправки платёжной ссылки \(должен принимать значение `true`\); - `email` \(в объекте `customer`\) — целевой адрес электронной почты пользователя для отправки платёжной ссылки; - `language` \(в объекте `customer`\) — код языка для оформления письма \(его следует указывать, если предпочитаемый для пользователя язык отличается от используемого по умолчанию английского и для этого языка предварительно был настроен шаблон письма\). 5. Для отправки платёжной ссылки средствами веб-сервиса мерчанта \(и блокировки отправки через платформу Ecommpay\) должен передаваться параметр `send_email` со значением `false`. 6. Для выбора варианты оплаты, отличного от заданного по умолчанию, должен передаваться указатель этого варианта в значении параметра `operation_type`. 7. Для предварительного выбора платёжного метода должен передаваться код этого метода в значении параметра `force_method` \(список таких кодов — представлен в справочнике [Коды платёжных методов](ru_pm_codes.md)\). 8. Для регистрации дальнейших списаний в рамках повторяемой оплаты должен передаваться объект `recurring` с информацией о регистрируемой оплате: - `register` — признак регистрации повторяемой оплаты, со значением `true`; - `type` — указатель категории регистрируемой повторяемой оплаты, в виде одного из следующих значений: - `C` — для экспресс-оплаты, - `U` — для автооплаты, - `R` — для регулярной оплаты; - `period` — периодичность списаний \(в рамках регулярной оплаты\): - `D` — ежедневно, - `W` — еженедельно, - `M` — ежемесячно, - `Q` — ежеквартально, - `Y` — ежегодно; - `time` — время выполнения последующих регулярных списаний \(в рамках регулярной оплаты\) в формате `hh:mm:ss`. 9. Для выполнения списания в рамках сервиса Mastercard MoneySend или Visa Direct необходимо передавать сведения о получателе платежа в объекте `recipient` \(с информацией о требованиях к составу таких сведений можно ознакомиться [в статье о работе с этими сервисами](ru_gate_money_transfer_services.md)\). 10. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на оплату по платёжной ссылке должен содержать идентификаторы проекта и платежа, подпись, идентификатор пользователя, валюту и сумму платежа, дату и время окончания срока действия платёжной ссылкии, при необходимости, токен платёжной карты. Дополнительно, если платёжную ссылку необходимо отправить средствами Ecommpay, запрос должен содержать адрес электронной почты пользователя и индикатор автоматической отправки платёжной ссылки. ```language-json { "general": { "project_id": 1901, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm==" }, "customer": { "id": "stapleton", "email": "baskerville@mail.uk" }, "payment": { "amount": 1500, "currency": "GBP", "best_before": "2026-03-08T09:00:00+03:00" }, "send_email": true, // при передаче ранее созданного токена платёжной карты: "token": "f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654" } ``` ```language-json { "general": { "project_id": 1901, "payment_id": "1234", "signature": "rS3vlABOs/fve6o555OINkQJqlDDZR2rQ==" }, "customer": { "id": "stapleton", "email": "baskerville@mail.uk" }, "payment": { "amount": 1299, "currency": "EUR", "description": "fluorescent paint 400ml", "best_before": "2026-10-20T23:59:59Z" }, "send_email": false, "operation_type": "sale" } ``` ### Формат запроса на отмену платежа {#section_nnb_tgk_tkb .section} При формировании запросов необходимо учитывать следующее: 1. Должен использоваться POST-запрос к конечной точке [/v2/payment/invoice/cancel](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-cancel). 2. В запросе должен использоваться объект `general`, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор того платежа, который необходимо отменить; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); 3. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на отмену платежа должен содержать идентификаторы проекта и платежа, а также подпись. ```language-json { "general": { "project_id": 1901, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm==" } } ``` ## Форматы оповещений {#ru_gate_invoice_format_callback} ### Формат оповещения о создании платёжной ссылки {#section_h1k_nz3_tkb .section} Для оповещений об создании и отправке платёжной ссылки пользователю используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что пользователю `stapleton` на адрес электронной почты `baskerville@mail.uk` отправлена платёжная ссылка для оплаты заказа в размере `12,99 GBP`. Срок действия ссылки истекает 11 октября 2026 года, в 11:50. ```language-json { "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"invoice sent", "date":"2025-11-11T11:50:24+0000", "best_before":"2026-10-11T11:50:00+0000", "force\_payment\_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&operation\_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":\{ "number":"431422\*\*\*\*\*\*0056", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card\_holder":"STAPLETON JACK", "id":1353, "expiry\_month":"11", "expiry\_year":"2028" \}, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"invoice sent", "date":"2025-11-11T11:57:34+0000", "created_date":"2025-11-11T11:56:32+0000", "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3701", "message":"Merchant sent invoice", "eci":"02" }, "signature":"hghwGGyapGUQnI+Qg==" } ``` В следующем примере содержится информация о создании платёжной ссылки, которая должна быть отправлена пользователю `stapleton` через веб-сервис мерчанта. ```language-json { "customer": { "id": "stapleton" }, "project_id": 1901, "payment": { "id": "1234", "type": "invoice", "status": "awaiting payment", "date": "2025-10-13T13:14:46+0000", "sum": { "amount": 1299, "currency": "EUR" }, "description": "fluorescent paint 400ml" }, "paymentLink": "https://cosmoshop-pp.com/3fdsfdfoeV6", "operation": { "sum_initial": { "amount": 1299, "currency": "EUR" }, "sum_converted": { "amount": 1299, "currency": "EUR" }, "code": "9999", "message": "Awaiting processing", "provider": { "id": 0, "payment_id": "" }, "id": 5034534534341907, "type": "invoice", "status": "awaiting payment", "date": "2025-10-13T13:14:47+0000", "created_date": "2025-10-13T13:14:46+0000", "request_id": "3b1ef25371d43bcf061bdfgdf2276a2fb0eb4647-05026527" }, "signature": "oFsfX5SZkzSNubrB3dsfsdf555P3iMTdfsds55VnMgmhLlsmx6cJLQg==" } ``` ### Формат оповещения об отмене платежа {#section_nkb_ntk_tkb .section} Для оповещения об отмене платежа по инициативе мерчанта используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что платёж `456789` отменён, статус платежа — `invoice canceled`. ```language-json { "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"invoice canceled", "date":"2025-11-11T11:57:36+0000", "best_before":"2026-10-11T11:50:00+0000", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&operation\_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":\{ "number":"431422\*\*\*\*\*\*0056", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card\_holder":"STAPLETON JACK", "id":1353091, "expiry\_month":"11", "expiry\_year":"2028" \}, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"invoice canceled", "date":"2025-11-11T11:57:34+0000", "created_date":"2025-11-11T11:56:32+0000", "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3702", "message":"Merchant canceled invoice", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" } ``` ### Формат оповещения об истечении срока действия платёжной ссылки {#section_wv1_yjq_tkb .section} Для оповещения об истечении срока действия платёжной ссылки используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что срок действия платёжной ссылки, отправленной пользователю `stapleton` на адрес электронной почты `baskerville@mail.uk`, истёк 11 февраля 2025 года, в 11:50. ```language-json { "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"expired", "date":"2025-01-11T11:57:36+0000", "best_before":"2025-02-11T11:50:00+0000", "force\_payment\_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2025-02-11T11:50%& interface_type=%7B%22id%22%3A3%7D&operation\_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":\{ "number":"431422\*\*\*\*\*\*0056", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card\_holder":"STAPLETON JACK", "id":1353091, "expiry\_month":"11", "expiry\_year":"2028" \}, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"expired", "date":"2025-01-11T11:57:34+0000", "created_date":"2025-01-11T11:56:32+0000", "request_id":"b3dee0a9d0d2c8d2aa56c36ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"3700", "message":"Best_before has expired", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" } ``` ### Формат оповещения о результате платежа {#section_yd1_4tk_tkb .section} Для оповещения о результате оплаты по платёжной ссылке используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что для пользователя `stapleton` проведена оплата в размере `12,99 GBP`. ```language-json { "project_id":1901, "payment":{ "id":"456789", "type":"invoice", "status":"success", "date":"2025-11-11T11:57:36+0000", "best_before":"2026-10-11T11:50:00+0000", "force\_payment\_method":"card", "method":"card", "email":"baskerville@mail.uk", "sum":{ "amount":1299, "currency":"GBP" }, "description":"fluorescent paint 400ml" }, "paymentLink": ".../payment?project_id=1901&payment_id=456789&customer_country=GB& language_code=en&payment_currency=GBP&best_before=2026-10-11T11:50%& interface_type=%7B%22id%22%3A3%7D&operation\_type=sale& signature=hghwGGyapGUQnI+Qg==", "account":\{ "number":"431422\*\*\*\*\*\*0056", "token":"f365bb1729f9b72fd9c097becc679f29c3e35c91d18070d15654", "type":"visa", "card\_holder":"STAPLETON JACK", "id":1353091, "expiry\_month":"11", "expiry\_year":"2028" \}, "customer":{ "id":"stapleton" }, "operation":{ "id":180001525, "type":"invoice", "status":"success", "date":"2025-11-11T11:57:34+0000", "created_date":""2025-11-11T11:56:32+0000", "request_id":"b3dee0a9d6c36460ada75f71ed0802c6f9", "sum_initial":{ "amount":1299, "currency":"GBP" }, "sum_converted":{ "amount":1299, "currency":"GBP" }, "code":"0", "message":"Success", "eci":"02" }, "signature":"hghwGlmVZ6Z1ZZ5D/aZAmrqdZb+GyapGUQnI+Qg==" } ``` --- # Повторяемые оплаты {#ru_Gate__payments_on_saved_data .concept} статьи о порядке регистрации и проведения через Gate различных категорий оплат с сериями повторяемых списаний, а также о возможностях управления списаниями в рамках таких оплат **Прим.:** Этот подраздел посвящён тому, как проводить повторяемые оплаты через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо статей этого подраздела для работы с повторяемыми оплатами могут быть полезны: - статьи [Повторяемая оплата со списаниями по запросам](ru_platform_recurring_model.md) и [Повторяемая оплата с автоматическими списаниями](ru_platform_sheduled_recurring_model.md) модели проведения платежей с описанием того, как в целом проводятся повторяемые оплаты в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить повторяемые оплаты через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. - [Общая информация](ru_Gate__saved_cards_payments_type.md) - [Регистрация повторяемой оплаты](ru_gate_payment_recurring_registration.md) - [Проведение оплаты со списаниями по запросам](ru_Gate__cof_merchant_side.md) - [Проведение оплаты с автоматическими списаниями](ru_Gate__cof_gate_side.md) - [Управление списаниями в рамках оплаты](ru_gate_payment_recurring_manage.md) - [Работа с повторными попытками автоматических списаний](ru_gate_cof_retry_attempts.md) - **[Общая информация](ru_Gate__saved_cards_payments_type.md)** статья с общей информацией о повторяемых оплатах, их классификации и порядке проведения - **[Регистрация повторяемой оплаты](ru_gate_payment_recurring_registration.md)** статья о порядке регистрации через Gate оплат с сериями повторяемых списаний - **[Проведение оплаты со списаниями по запросам](ru_Gate__cof_merchant_side.md)** статья о порядке проведения через Gate повторяемых оплат со списаниями по запросам \(без фиксированного расписания\) - **[Проведение оплаты с автоматическими списаниями](ru_Gate__cof_gate_side.md)** статья о порядке проведения через Gate повторяемых оплат с автоматическими списаниями \(по заданному расписанию\) - **[Управление списаниями в рамках оплаты](ru_gate_payment_recurring_manage.md)** статья о возможностях управления списаниями в рамках повторяемых оплат при работе через Gate, включая возможности получения сведений о сериях списаний, изменения условий для списаний и отмены дальнейшего выполнения списаний - **[Работа с повторными попытками автоматических списаний](ru_gate_cof_retry_attempts.md)** статья о возможностях работы с повторными попытками автоматических списаний при проведении повторяемых оплат **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Общая информация {#ru_Gate__saved_cards_payments_type .concept} статья с общей информацией о повторяемых оплатах, их классификации и порядке проведения ## Определение {#section_j55_kbl_yjb .section} *Повторяемая оплата* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется повторяемый перевод денежных средств от пользователя к мерчанту. При этом для проведения платежа используются сохранённые платёжные данные, а подтверждение подлинности платёжного инструмента пользователя \(такое, как ввод кода проверки подлинности карты\) не требуется. Каждый перевод денежных средств в рамках такого платежа называется *списанием*. ## Характеристика {#section_fkm_54k_y3b .section} Использование повторяемой оплаты может быть актуальным при выстраивании долгосрочных отношений с пользователями, когда важно предоставлять им возможность удобной оплаты без дополнительных действий с их стороны. В платёжной платформе поддерживаются следующие категории повторяемых оплат: - *Экспресс-оплаты*. Списания в рамках таких оплат инициируются пользователем и выполняются без привязки к расписанию или сумме платежа. Например, пользователь онлайн-кинотеатра может оплатить прокат одного или нескольких фильмов с использованием сохранённых данных карты. - *Автооплаты*. Списания в рамках таких оплат инициируются мерчантом и выполняются нерегулярно или на различные суммы. Например, когда остаток средств на счёте пользователя становится ниже заданного, выполняется списание средств с его карты для пополнения счёта. - *Регулярные оплаты*. Списания в рамках таких оплат инициируются мерчантом по заданному графику и на фиксированную сумму. График таких списаний может храниться как на стороне веб-сервиса, так и на стороне платёжной платформы. Например, с карты пользователя онлайн-кинотеатра может ежемесячно списываться фиксированная сумма для оплаты доступа к просмотру всех фильмов кинотеатра. ![](images/ru_cof.svg) Для проведения любой повторяемой оплаты, вне зависимости от её категории, необходимо получить согласие пользователя на дальнейшее хранение и использование его платёжных данных в соответствии с определёнными условиями \(удовлетворяющими требованиям платёжных систем\). Как правило, получение такого согласия выполняется при регистрации повторяемой оплаты. ## Варианты проведения {#section_fhj_2h1_v3b .section} Каждую повторяемую оплату необходимо предварительно *зарегистрировать*. При работе с платёжной платформой Ecommpay это можно сделать через проведение разовой оплаты или проверку действительности платёжного инструмента — с передачей в исходном запросе соответствующих параметров\([подробнее](ru_gate_payment_recurring_registration.md)\). Кроме того, допустимы ситуации с регистрацией повторяемых оплат через других эквайеров и последующим проведением таких оплат через Ecommpay, с переносом информации об этих оплатах в платформу Ecommpay \([подробнее](ru_gate_data_migration.md)\) или без такого переноса. Информацию о зарегистрированных повторяемых оплатах можно *хранить* внутри или вне платформы Ecommpay \(на стороне веб-сервиса или у другого эквайера\), при этом в рамках одного проекта допустим лишь один способ хранения. Если для какого-либо проекта подключена возможность проводить повторяемые оплаты с хранением информации о них вне платформы Ecommpay, то проведение в рамках этого же проекта повторяемых оплат с хранением информации внутри платформы исключается. И наоборот. Любую зарегистрированную повторяемую оплату можно *проводить* с использованием одного из доступных вариантов. Для регулярных оплат, информация о которых хранится в платформе Ecommpay, допустимы два варианта проведения: - [с автоматическими списаниями](ru_Gate__cof_gate_side.md), когда каждое списание инициируется на стороне платформы в соответствии с предварительно заданным графиком; - [со списаниями по запросам](ru_Gate__cof_merchant_side.md), когда каждое списание инициируется со стороны мерчанта. Для всех остальных повторяемых оплат \(которые не относятся к категории регулярных или информация о которых не хранится в платформе\) доступен только второй вариант — со списаниями по запросам. Также, вне зависимости от варианта проведения, повторяемые оплаты могут проводиться по базовым сценариям или с добавлением вспомогательной процедуры — [дополнения информации о платеже](ru_Gate_Clarification.md). **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) --- # Регистрация повторяемой оплаты {#ru_gate_payment_recurring_registration} статья о порядке регистрации через Gate оплат с сериями повторяемых списаний ## Общая информация {#section_qx5_hhm_dlb .section} Для регистрации повторяемой оплаты на стороне платёжной платформы необходимо предварительно сохранить данные платёжного инструмента пользователя. Это можно сделать разными способами, в том числе при проведении платежей через Gate, Payment Page \([подробнее](ru_pp_recurring.md)\), Dashboard \([подробнее](ru_dbl_payments.md)\)и при переносе информации о повторяемых оплатах от стороннего эквайера \([подробнее](ru_gate_data_migration.md)\). При регистрации повторяемой оплаты через Gate необходимо отправить запрос на проведение разовой оплаты, оплаты по ссылке или на проверку действительности платёжного инструмента с параметрами, указывающими на необходимость сохранения данных. Каждая повторяемая оплата регистрируется на заданный срок, при этом если какие-либо параметры, определяющие срок действия, не задаются со стороны мерчанта, в платформе устанавливаются значения, соответствующие сроку действия используемой платёжной карты или сроку в 10 лет с месяца регистрации этой оплаты \(подробнее [далее](ru_gate_payment_recurring_registration.md#section_vdl_vqb_cjb)\). После истечения срока действия повторяемой оплаты к веб-сервису мерчанта направляется оповещение, а выполнение списаний в рамках этой оплаты становится недоступным: запросы на списания отклоняются и к веб-сервису направляются оповещения с кодом ошибки `3184` \(или `3301`\). Регистрация повторяемых оплат может быть запрещена в рамках проекта мерчанта или для провайдера, участвующего в проведении платежа. В таком случае запрос на проведение оплаты с регистрацией повторяемой оплаты может быть отклонён. Чтобы избежать отклонения платежа можно настроить игнорирование параметров, указывающих на необходимость зарегистрировать повторяемую оплату, при наличии таких запретов. Для этого необходимо обратиться к специалистам службы технической поддержки — [support@ecommpay.com](mailto:support@ecommpay.com). При изменениях в настройках системы провайдера может требоваться новая регистрация повторяемых оплат. В таких случаях от службы технической поддержки Ecommpay мерчанту направляется письмо со списком идентификаторов повторяемых оплат, по которым следует выполнить регистрацию заново. Для этой регистрации необходимо уведомить пользователей о прекращении прежних списаний и необходимости инициирования новых, предварительно отвязав сохранённую карту, после чего инициировать регистрацию в платформе. Каждая вновь зарегистрированная повторяемая оплата получает новый идентификатор, который отправляется мерчанту в оповещении об успешной регистрации. ## Схема выполнения {#section_p3r_frb_cjb .section} Для регистрации повторяемой оплаты необходимо отправить запрос на инициирование одной из операций: `sale`, `auth`, `account verification` или `invoice`. В таком запросе необходимо передать не только параметры, обязательные для инициирования операции, но и параметры, необходимые для регистрации повторяемой оплаты. После получения запроса на инициирование одной из перечисленных операций в платёжной платформе выполняется стандартное выполнение такой операции, которое может включать в том числе выполнение вспомогательных процедур. В случае хранения данных на стороне платёжной платформы при успешном завершении операции на стороне платёжной системы или провайдера \(то есть при получении статуса операции `success`\) на стороне платёжной платформы создаётся запись о серии списаний. Этой записи присваиваются следующие атрибуты: - *Идентификатор*. После создания записи о серии списаний этот идентификатор передаётся к веб-сервису в параметре `id` объекта `recurring` оповещения о результате операции и должен использоваться в запросах на проведение повторяемой оплаты и для управления ей. - *Статус*. Как правило, при создании записи о серии списаний ей присваивается статус `active`. Этот статус может измениться на статус `canceled`, если повторяемая оплата отменена по запросу мерчанта или пользователя, а также в некоторых других случаях. В случае хранения данных на стороне веб-сервиса запись о серии списаний не создаётся. Далее от платёжной платформы к веб-сервису направляется оповещение о результате операции, в котором содержится присвоенный записи о серии списаний идентификатор, если эта запись была создана. Такое оповещение свидетельствует об успешной регистрации повторяемой оплаты. ## Регистрация с хранением данных на стороне веб-сервиса {#section_smg_vqb_cjb .section} При формировании запросов на регистрацию повторяемой оплаты с хранением платёжных данных пользователя на стороне веб-сервиса необходимо учитывать следующее: 1. Должен использоваться POST-запрос к одной из следующих конечных точек: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale), - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth), - [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification), - [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token). 2. В запросе должны использоваться обязательные для этого запроса объекты и параметры. 3. Помимо обязательных объектов и параметров в запросе должен использоваться параметр `stored_card_type` с одним из следующих значений: - `3` — для автооплаты, - `5` — для регулярной оплаты \(кроме запросов к конечной точке [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)\). Таким образом, помимо обязательных параметров корректный запрос должен содержать признак регистрации определённой категории повторяемой оплаты. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNeR+CqGrNxYyilUwSm...==" }, "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JUDY DOE", "cvv": "123", "stored_card_type": 3 // Регистрация автооплаты }, "customer": { "id": "customer_12", "ip_address": "202.144.196.0" }, "payment": { "amount": 400, "currency": "USD" } } ``` Информация о регистрации повторяемой оплаты передаётся от платёжной платформы к веб-сервису в составе оповещения о результате операции. Для этого оповещения используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). ```language-json { "project_id":42, "payment":{ "id":"567890", "type":"purchase", "status":"success", "date":"2019-05-14T12:52:45+0000", "method":"card", "sum":{ "amount":400, "currency":"USD" }, "description":"" }, "account":{ "number":"431422******0056", "token":"d927d3f006008edf5c07661", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"08", "expiry_year":"2025" }, "customer":{ "id":"customer_12" }, "scheme\_id":"MCS38A0790706", "operation":{ "id":22136002040, "type":"sale", "status":"success", "date":"2019-05-14T12:52:45+0000", "created_date":"2019-05-14T12:52:42+0000", "request_id":"8c53d11-1160d2c", "sum_initial":{ "amount":400, "currency":"USD" }, "sum_converted":{ "amount":400, "currency":"USD" }, "provider":{ "id":414, "payment_id":"00200011764", "date":"2019-05-14T12:52:55+0000", "auth_code":"231567", "endpoint_id":414 }, "code":"0", "message":"Success", "eci":"07" }, "signature":"v7KN5D/aZAdeR+CqGrNxYyilUwSm...==" } ``` ## Регистрация с хранением данных на стороне платёжной платформы {#section_vdl_vqb_cjb .section} При формировании запросов на регистрацию повторяемой оплаты с хранением платёжных данных пользователя на стороне платёжной платформы необходимо учитывать следующее: 1. Должен использоваться POST-запрос к одной из следующих конечных точек: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) — при проведении разовой оплаты в одну стадию, - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth) — при проведении разовой оплаты в две стадии, - [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification) — при проверке платёжного инструмента, - [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create) — при проведении оплаты по ссылке, - [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create) — при проведении оплаты по ссылке с использованием токена. 2. В запросе должны использоваться обязательные для этого запроса объекты и параметры. 3. Помимо обязательных объектов и параметров в запросе должен использоваться объект `recurring`, содержащий параметры с информацией о регистрируемой оплате: - `register` — указатель необходимости зарегистрировать повторяемую оплату; - `type` — категория регистрируемой повторяемой оплаты, с одним из следующих значений: - `C` — для экспресс-оплаты; - `U` — для автооплаты; - `R` — для регулярной оплаты; - `period` — указатель базового периода списаний \(для регулярной оплаты\), с одним из следующих значений: - `D` — ежедневно; - `W` — еженедельно; - `M` — ежемесячно \(если установленный день отсутствует в следующем месяце, например 31, — списание происходит в последний день месяца\); - `Q` — ежеквартально; - `Y` — ежегодно; - `time` — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`. 4. Для регистрации регулярной оплаты также могут использоваться и другие параметры в объекте `recurring`: - `amount` — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты; - `interval` — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`, например чтобы списания выполнялись раз в три недели, в параметре `period` надо задать значение `W`, а в параметре `interval` значение `3`; - `start_date` — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`; - `expiry_day` — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\); - `expiry_month` — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\); - `expiry_year` — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\); **Прим.:** Если какой-либо из параметров, определяющих дату завершения повторяемой оплаты, не указывается в запросе, для него по умолчанию применяются следующие значения: - для классической карточной оплаты — значение соответствующего параметра \(дня, месяца, года\) из срока действия указанной платёжной карты; - для других доступных методов — значение соответствующего параметра согласно следующим правилам: - для календарного дня — последний календарный день актуального месяца \(указанного в параметре `expiry_month` или соответствующего дате регистрации повторяемой оплаты\); - для месяца — месяц регистрации повторяемой оплаты; - для года — год, превышающий год регистрации повторяемой оплаты на 10 лет. Так, при указании только года для классической карточной оплаты применяются число и месяц из срока действия используемой карты и указанный год, а для альтернативного метода — последний календарный день того месяца, в который была зарегистрирована повторяемая оплата, и указанный год. - `scheduled_payment_id` — идентификатор платежа, в рамках которого следует выполнять списания, должен отличаться от идентификатора платежа, в рамках которого выполняется регистрация повторяемой оплаты, и быть уникальным в рамках проекта \(также не стоит путать его с идентификатором серии списаний, передаваемым в параметре `id` объекта `recurring` оповещения о регистрации повторяемой оплаты\). **Внимание:** Если идентификаторы платежа, который необходимо присвоить повторяемой оплате \(`scheduled_payment_id`\), и платежа, в рамках которого эта оплата регистрируется \(`payment_id`\), совпадают, запрос на регистрацию отклоняется. Таким образом, помимо обязательных параметров корректный запрос должен содержать признак регистрации повторяемой оплаты и её категорию, а также, при регистрации регулярной оплаты, время и периодичность списаний. В зависимости от особенностей провайдеров, участвующих в проведении платежа, набор обязательных параметров может варьироваться. Подробную информацию о требованиях провайдеров можно уточнить у курирующего менеджера Ecommpay. ```language-json { "general": { "project_id": 42, "payment_id": "567890", "signature": "v7KN1ZZ5D/aZAeR+CqGrwSm...==" }, "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JUDY DOE", "cvv": "123" }, "customer": { "id": "customer_12", "ip_address": "202.144.196.0" } "payment": { "amount": 400000, "currency": "USD" }, "recurring": { "type": "R", // Регистрация регулярной оплаты "period": "W", "interval": 3, // Списания каждые 3 недели "expiry_year": 2025, "expiry_month": 5, "expiry_day": 5, // Последнее списание 5-го мая 2025 года "time": "10:00:00", // Выполнение списаний в 10:00:00 "register": true, // Регистрация повторяемой оплаты "scheduled_payment_id": "567891", "start_date": "10-10-2020" } } ``` Информация о регистрации повторяемой оплаты передаётся от платёжной платформы к веб-сервису в составе оповещения о результате операции. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md).При этом в состав оповещений можно включить идентификаторы соответствующих операций на стороне международной платёжной системы — в параметре `scheme_id`. Для этого необходимо обратиться к специалистам технической поддержки Ecommpay. В примере далее оповещение свидетельствует о том, что повторяемая оплата зарегистрирована и записи о серии списаний присвоен идентификатор `1001648059`. ```language-json { "project_id":42, "payment":{ "id":"567890", "type":"purchase", "status":"success", "date":"2019-05-14T12:52:45+0000", "method":"card", "sum":{ "amount":400, "currency":"USD" }, "description":"" }, "account":{ "number":"431422******0056", "token":"d927d3f006008edf5c07661", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"08", "expiry_year":"2025" }, "customer":{ "id":"customer_12" }, "recurring":{ "id":1001648059, // Идентификатор записи о серии списаний на стороне платёжной платформы "currency":"USD", "valid_thru":"2019-05-20T00:00:00+0000" }, "scheme\_id":"MCS38A0790706", "operation":{ "id":22136002040, "type":"sale", "status":"success", "date":"2019-05-14T12:52:45+0000", "created_date":"2019-05-14T12:52:42+0000", "request_id":"8c77279053d011-1160421d51e11f87d2c", "sum_initial":{ "amount":400, "currency":"USD" }, "sum_converted":{ "amount":400, "currency":"USD" }, "provider":{ "id":414, "payment_id":"00200011764", "date":"2019-05-14T12:52:55+0000", "auth_code":"231567", "endpoint_id":414 }, "code":"0", "message":"Success", "eci":"07" }, "signature":"v7KNMpZ1ZZ5D/aZAebR+CqGrUwSm...==" } ``` **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) --- # Проведение оплаты со списаниями по запросам {#ru_Gate__cof_merchant_side .concept} статья о порядке проведения через Gate повторяемых оплат со списаниями по запросам \(без фиксированного расписания\) ## Общая информация {#section_knp_r41_v3b .section} *Повторяемая оплата со списаниями по запросам* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется один \(повторяемый\) перевод денежных средств от пользователя к мерчанту с использованием сохранённых платёжных данных и без подтверждения подлинности платёжного инструмента пользователя \(такого, как ввод кода проверки подлинности карты\). Повторяемые оплаты со списаниями по запросам могут проводиться при выполнении одного из следующих условий: - если эти оплаты были изначально зарегистрированы на стороне платёжной платформы \([подробнее](ru_gate_payment_recurring_registration.md)\); - если информация об этих оплатах была перенесена в платформу от другого эквайера \([подробнее](ru_gate_data_migration.md)\); - если информация об этих оплатах не была перенесена в платформу, но их проведение согласовано с курирующим менеджером Ecommpay и настроено в рамках используемого проекта. Оплаты со списаниями по запросам проводятся в платёжной платформе Ecommpay в соответствии с моделью проведения платежей \([подробнее](ru_platform_recurring_model.md)\) и представленной в этой статье схемой. При этом для оплат, зарегистрированных вне платформы Ecommpay, не актуальны условия и шаги, касающиеся регистрации. И, кроме того, для оплат, которые регистрировались вне платформы и информация о которых не была импортирована в платформу, актуально следующее: - Если для какого-либо проекта подключена возможность проводить такие оплаты, в рамках этого же проекта исключается проведение других повторяемых оплат \(зарегистрированных в платформе или перенесённых в неё\). - При использовании платёжных карт, выпущенных в Европейской экономической зоне, ответственность за регистрацию повторяемой оплаты с соблюдением требований второй директивы Европейского союза об оказании платёжных услуг \(PSD2\) к аутентификации покупателей \(Strong Customer Authentication, SCA\) возлагается на мерчанта. ## Схема проведения {#section_mft_gvd_w3b .section} Для проведения повторяемой оплаты со списаниями по запросам необходимо: 1. [Зарегистрировать](ru_gate_payment_recurring_registration.md) повторяемую оплату. 2. Передать [запрос на проведение повторяемой оплаты](ru_Gate__cof_merchant_side.md#section_jbj_flf_dlb) с идентификатором записи о серии списаний. 3. Принять от платёжной платформы [оповещение о результате списания](ru_Gate__cof_merchant_side.md#section_wxc_s41_v3b). Для каждого последующего списания необходимо повторно передавать запросы на проведение повторяемой оплаты и принимать оповещения о результате. ![](images/ru_gate_uml_oneclick.svg) 1. Пользователь на стороне веб-сервиса инициирует списание. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на списание. 3. Этот запрос поступает в платёжную платформу. 4. В платёжной платформе выполняется обработка запроса. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. От платёжной платформы к платёжной системе направляется запрос на оплату. 7. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 8. На стороне эмитента выполняется обработка платежа и списание средств пользователя. 9. От эмитента к платёжной системе направляется уведомление о результате оплаты. 10. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты. 11. От платёжной платформы к веб-сервису направляется оповещение о результате списания. 12. От веб-сервиса пользователю направляется результат списания. 13. Далее со стороны пользователя инициируются последующие списания и для каждого из них повторяются шаги 1—12. ![](images/ru_gate_uml_autopayment.svg) 1. От веб-сервиса на заданный URL Ecommpay передаётся запрос на списание. 2. Этот запрос поступает в платёжную платформу. 3. В платёжной платформе выполняется обработка запроса. 4. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 5. От платёжной платформы к платёжной системе направляется запрос на оплату. 6. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 7. На стороне эмитента выполняется обработка платежа и списание средств пользователя. 8. От эмитента к платёжной системе направляется уведомление о результате оплаты. 9. От платёжной системы к платёжной платформе направляется уведомление о результате оплаты. 10. От платёжной платформы к веб-сервису направляется оповещение о результате списания. 11. От веб-сервиса пользователю направляется результат списания. 12. Далее со стороны веб-сервиса инициируются последующие списания и для каждого из них повторяются шаги 1—11. Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API— в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_payment_model.md). ## Формат запроса {#section_jbj_flf_dlb .section} Формат запросов в этом разделе представлен для инициирования повторяемых оплат со списаниями по запросу с использованием *платёжных карт*.При формировании запросов необходимо учитывать следующее: 1. Должен использоваться POST-запрос к одной из следующих конечных точек: - [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring) — для всех категорий повторяемых оплат, которые были изначально зарегистрированы в платформе Ecommpay или информация о которых была перенесена в платформу, вне зависимости от места хранения платёжных данных \(на стороне платёжной платформы или на стороне веб-сервиса\); - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) — для повторяемых оплат при хранении платёжных данных на стороне веб-сервиса, вне зависимости от того, где была зарегистрирована оплата; - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth) — только для автооплат и регулярных оплат при хранении платёжных данных на стороне веб-сервиса, вне зависимости от того, где была зарегистрирована оплата; - [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token) — только для автооплат, которые были изначально зарегистрированы в платформе Ecommpay или информация о которых была перенесена в платформу, при хранении платёжных данных на стороне веб-сервиса. 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемой операции; - `id` — идентификатор пользователя, уникальный в рамках проекта и имеющий то же значение, которое было использовано при регистрации данной повторяемой оплаты; **Внимание:** Использование разных идентификаторов пользователя для операций в рамках одной повторяемой оплаты не допускается. - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3. - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. 3. В зависимости от конечной точки, к которой направляется запрос, в запросе также должны использоваться следующие объекты и параметры: - В запросах к конечной точке [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring) — идентификатор записи о серии списаний, полученный в оповещении с данными о регистрации, в параметре `id` объекта `recurring`. - В запросах к конечным точкам [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) и [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth) — объект `card` со следующими параметрами: - `pan` — номер карты; - `year` — год окончания срока действия карты; - `month` — месяц окончания срока действия карты; - `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта \(это имя должно указываться в соответствии с написанием на карте, а исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\); - `stored_card_type` — указатель категории, к которой относится повторяемая оплата \(`4` для автооплаты и `6` для регулярной оплаты\); - `scheme_id` — идентификатор операции, в рамках которой была зарегистрирована повторяемая оплата, на стороне международной платёжной системы \(Mastercard или Visa\); должен указываться для карт, выпущенных в Европейской экономической зоне, но также может указываться и в остальных случаях. - В запросах к конечной точке [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token) — параметр `stored_card_type` объекта `card` со значением `4` \(автооплата\). 4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, валюту и сумму проведения платежа, а также идентификатор записи о серии списанийили данные платёжной карты и указатель категории повторяемой оплаты. В зависимости от особенностей провайдеров, участвующих в проведении платежа, набор обязательных параметров может варьироваться. Подробную информацию о требованиях провайдеров можно уточнить у курирующего менеджера Ecommpay. ```language-json { "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 // Идентификатор записи о серии списаний } } ``` ```language-json { "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, // Проведение автооплаты "scheme_id": "MDS60JXCH0209" } } ``` ```language-json { "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 // Проведение автооплаты } } ``` ## Формат оповещений {#section_wxc_s41_v3b .section} Информация о результатах проведения повторяемых оплат передаётся от платёжной платформы к веб-сервису в виде оповещений о каждом выполняемом списании. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md).При этом в состав оповещений можно включить идентификаторы операций, в рамках которых были зарегистрированы повторяемые оплаты, на стороне международной платёжной системы — в параметре `scheme_id`. Для этого необходимо обратиться к специалистам технической поддержки Ecommpay. В следующем примере оповещение свидетельствует о том, что в рамках проекта `42` было выполнено списание в размере `4,00 USD` с платёжной карты `№ 424242******4243`. ```language-json { "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" }, "scheme_id": "MCS38A0790706", "signature":"MpfogAxZ5D/b0VMdeR+xYyilUwSm...==" } ``` **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) --- # Проведение оплаты с автоматическими списаниями {#ru_Gate__cof_gate_side} статья о порядке проведения через Gate повторяемых оплат с автоматическими списаниями \(по заданному расписанию\) **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) ## Общая информация {#ru_gate_cof_gate_side_overview} *Повторяемая оплата с автоматическими списаниями* — это тип платежа, в рамках которого на основании одного исходного запроса осуществляется серия регулярных переводов денежных средств от пользователя к мерчанту \(списаний\) с использованием сохранённых платёжных данных и без подтверждения подлинности платёжного инструмента пользователя\(такого, как ввод кода проверки подлинности карты\). В платёжной платформе Ecommpay такие оплаты проводятся в соответствии с моделью проведения платежей \([подробнее](ru_platform_sheduled_recurring_model.md)\), при этом когда недостаточно одной попытки выполнить очередное автоматическое списание \(например, при недостатке средств на карте пользователя\), в платформе предусмотрена возможность автоматически инициировать повторные попытки таких списаний \([подробнее](ru_gate_cof_retry_attempts.md)\). ## Схемы проведения {#ru_gate_cof_gate_side_workflow} ### Проведение с инициированием списаний при регистрации платежа {#section_oqf_hvd_w3b .section} В базовом случае, когда при регистрации повторяемой оплаты передаётся параметр `scheduled_payment_id`, для проведения повторяемой оплаты с автоматическими списаниями необходимо: 1. [Зарегистрировать](ru_gate_payment_recurring_registration.md) повторяемую оплату. 2. Принять от платёжной платформы [оповещение о результате списания](ru_Gate__cof_gate_side.md). 3. Продолжать принимать оповещения о результате каждого списания в рамках платежа. Для изменения условий повторяемой оплаты или её отмены, а также для возврата средств после одного или нескольких списаний необходимо передать соответствующие запросы в платёжную платформу \(подробнее — в статье [Управление списаниями в рамках оплаты](ru_gate_payment_recurring_manage.md)\). ![](images/ru_gate_uml_scheduled_recurring_auto.svg) 1. В соответствии с графиком, в необходимое время от платёжной платформы к платёжной системе направляется запрос на очередное списание. 2. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 3. На стороне эмитента выполняется обработка списания и перевод средств от пользователя к мерчанту. 4. От эмитента к платёжной системе направляется информация о результате списания. 5. От платёжной системы к платёжной платформе направляется информация о результате списания. 6. От платёжной платформы к веб-сервису направляется оповещение о результате списания. 7. На стороне веб-сервиса обеспечивается информирование пользователя о результате списания. 8. Далее со стороны платёжной платформы инициируются последующие плановые списания и для каждого из них повторяются шаги 1—7. Информация о форматах запросов и оповещений приведена далее; общая информация о работе с API — в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). Информацию о возможных статусах такой оплаты можно найти [в соответствующей статье](ru_platform_payment_model.md). ### Проведение с отдельным инициированием списаний {#section_u5g_ytb_gzb .section} В случае, если при регистрации повторяемой оплаты не передаётся параметр `scheduled_payment_id`, для проведения повторяемой оплаты с автоматическими списаниями необходимо: 1. [Зарегистрировать](ru_gate_payment_recurring_registration.md) повторяемую оплату. 2. Передать [Формат запроса](ru_Gate__cof_gate_side.md) с идентификатором записи о серии списаний. 3. Принять от платёжной платформы [оповещение о результате списания](ru_Gate__cof_gate_side.md). 4. Продолжать принимать оповещения о результате каждого списания в рамках платежа. ![](images/ru_gate_uml_scheduled_recurring.svg) 1. От веб-сервиса на заданный URL Ecommpay передаётся запрос на инициирование списаний. 2. Этот запрос поступает в платёжную платформу. 3. В платёжной платформе выполняется обработка запроса. 4. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 5. От платёжной платформы к платёжной системе направляется запрос на списание. 6. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 7. На стороне эмитента выполняется обработка списания и перевод средств от пользователя к мерчанту. 8. От эмитента к платёжной системе направляется информация о результате списания. 9. От платёжной системы к платёжной платформе направляется информация о результате списания. 10. От платёжной платформы к веб-сервису направляется оповещение о результате списания. 11. На стороне веб-сервиса обеспечивается информирование пользователя о результате списания. 12. Далее со стороны платёжной платформы инициируются последующие плановые списания и для каждого из них повторяются шаги 5—11. ## Формат запроса {#ru_gate_cof_gate_side_request} При работе с запросами на инициированиекарточных повторяемых оплат с автоматическими списаниями необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта и имеющий то же значение, которое было использовано при регистрации данной повторяемой оплаты; **Внимание:** Использование разных идентификаторов пользователя для операций в рамках одной повторяемой оплаты не допускается - `ip_address` — IP-адрес пользователя, актуальный для инициируемой операции; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют ччерез платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. - `recurring` — объект, содержащий сведения повторяемой оплате: - `id` — идентификатор записи о серии списаний, полученный в оповещении после регистрации повторяемой оплаты или заданный при переносе информации об этой оплате от стороннего эквайера. 3. С учётом региональных особенностей и специфики провайдеров, участвующих в проведении платежей, могут быть обязательны и некоторые другие параметры. Информацию о таких особенностях и требованиях провайдеров можно уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, в общем случае корректный запрос должен содержать идентификаторы проекта и платежа, подпись, IP-адрес пользователя, код валюты и сумму проведения платежа, а также идентификатор серии списаний. ``` {#codeblock_ehx_5fm_13c .language-json} { "general":{ "project_id":42, "payment_id":"456789", "signature":"K5D/aZAMdeR+YyilUwS==" }, "customer":{ "ip_address":"202.144.196.0", "id":"customer_12" }, "payment":{ "amount":400, "currency":"USD" }, "recurring":{ "id":1079 } } ``` ## Формат оповещений {#ru_gate_cof_gate_side_callback} От платёжной платформы к веб-сервису передаются оповещения с информацией о результате каждого списания в рамках повторяемой оплаты.Для этих оповещений используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `42` для пользователя `customer_12` было выполнено списание в размере `4,00 USD` с платёжной карты `№ 424242******4243` и ожидаются последующие списания. ```language-json { "customer":{ "id":"customer_12" }, "account":{ "number":"431422******0056", "type":"visa", "card_holder":"JOHN SMITH", "id":45678, "expiry_month":"08", "expiry_year":"2026" }, "payment":{ "sum":{ "amount":400, "currency":"USD" }, "method":"card", "date":"2023-06-07T06:18:02+0000", "status":"scheduled recurring processing", // Статус платежа "type":"recurring", // Тип платежа "id":"456789", "description":"" }, "project_id":42, "recurring":{ "valid_thru":"2023-07-31T00:00:00+0000", "currency":"USD", "id":1079 // Идентификатор серии списаний }, "operation":{ "id":39690002636, "type":"recurring", // Тип операции "status":"success", // Статус операции "date":"2023-06-07T06:18:02+0000", "created_date":"2023-06-07T06:18:02+0000", "request_id":"5cfa0199c33071", "sum_initial":{ "amount":400, "currency":"USD" }, "sum_converted":{ "amount":400, "currency":"USD" }, "provider":{ "id":6, "payment_id":"1192", "date":"2023-02-07T08:34:24+0000", "auth_code":"5253", "endpoint_id":6 }, "code":"0", "message":"Success" }, "signature":"v7KNMpfZZ5D/aZMdeR+YyilUwSm...==" } ``` В случае, если подключена возможность повторных попыток списаний, в такие оповещения также включается дополнительный объект `recurring_retry`, формат которого описан [в отдельной статье](ru_gate_cof_retry_attempts.md). --- # Управление списаниями в рамках оплаты {#ru_gate_payment_recurring_manage} статья о возможностях управления списаниями в рамках повторяемых оплат при работе через Gate, включая возможности получения сведений о сериях списаний, изменения условий для списаний и отмены дальнейшего выполнения списаний ## Общая информация {#section_lbz_nv5_5jb .section} В платёжной платформе поддерживаются возможности управления списаниями для повторяемых оплат любой категории. К таким возможностям относятся: - получение сведений о серии списаний; - изменение условий: суммы и срока действия, а для регулярных оплат — параметров, задающих график списаний; - отмена дальнейшего выполнения списаний со стороны мерчанта. Необходимо отметить, что отмена дальнейшего выполнения списаний может быть осуществлена и со стороны пользователя при его обращении к эмитенту. В этом случае последующее списание отклоняется, а платёжные данные удаляются из списка сохранённых на стороне платёжной платформы. Помимо этого, управлять списаниями для регулярных оплат можно через интерфейс [Dashboard](ru_dbl_payments.md). ## Получение сведений о серии списаний {#section_vkt_cf2_5jb .section} При формировании запроса на получение сведений о серии списаний необходимо учитывать следующее: 1. Должен использоваться POST-запрос к конечной точке [/v2/payment/recurring/info](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-recurring-info). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - Объект `recurring` с идентификатором записи о серии списаний `id`, полученным в оповещении с данными о регистрации. Таким образом, корректный запрос должен содержать идентификатор проекта, подпись и идентификатор записи о серии списаний. ```language-json { "general":{ "project_id":42, "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "recurring":{ "id":1079 } } ``` Сведения о серии списаний передаются от платёжной платформы к веб-сервису в ответе стандартного формата, описание которого представлено в разделе [Формат ответа](ru_gate_interaction_organisation.md). В данном случае ответ свидетельствует о том, что в рамках проекта `42` для пользователя `customer_12` было выполнено списание в размере `4,00 USD` с платёжной карты `№ 424242******4243` и ожидаются последующие списания. ```language-json { "project_id": 42, "recurring":{ "id": 1079, // Идентификатор записи о серии списаний "type": "R", "period": "W", "period_interval": 3, "start_date": "2020-10-10", "start_time": "10:00:00", "amount": 400, "last_payment_at": "0000-00-00 00:00:00", "valid_thru": "2025-05-25 00:00:00", "status": "active", "currency": "USD", "payment\_method": "card" } } ``` ## Изменение условий серии списаний {#section_lpp_df2_5jb .section} При формировании запроса на изменение условий проведения повторяемой оплаты необходимо учитывать следующее: 1. Должен использоваться POST-запрос к конечной точке [/v2/payment/card/recurring/update](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring-update). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - Объект `recurring` с идентификатором записи о серии списаний `id`, полученным в оповещении с данными о регистрации. 3. Дополнительно следует использовать параметры, задающие условия повторяемой оплаты. К таким параметрам относятся: - `period` — указатель базового периода списаний \(`D` — ежедневно, `W` — еженедельно, `M` — ежемесячно, `Q` — ежеквартально, `Y` — ежегодно\); - `time` — время выполнения последующих списаний \(для регулярной оплаты\), актуальное при указании параметра `period` и указываемое в формате `чч:мм:сс`; - `interval` — множитель для кратного увеличения периода списаний \(для регулярной оплаты\), актуальный при указании параметра `period` и указываемый в виде числа от `1` до `100`, например чтобы списания выполнялись раз в три недели, в параметре `period` надо задать значение `W`, а в параметре `interval` значение `3`; - `amount` — фиксированная сумма последующих списаний \(для регулярной оплаты\) в дробных единицах валюты; - `start_date` — дата первого списания \(для регулярной оплаты\), актуальная при указании параметра `scheduled_payment_id` и указываемая в формате `ДД-ММ-ГГГГ`; - `expiry_day` — номер календарного дня, в который должна быть завершена повторяемая оплата \(в виде числа от `1` до `31`, без ведущего нуля, по григорианскому календарю\); - `expiry_month` — порядковый номер месяца, в котором должна быть завершена повторяемая оплата \(в виде числа от `1` до `12`, без ведущего нуля, по григорианскому календарю\); - `expiry_year` — порядковый номер года, в котором должна быть завершена повторяемая оплата \(в четырёхзначном формате `ГГГГ`, по григорианскому календарю\); - `scheduled_payment_id` — идентификатор платежа, в рамках которого следует выполнять списания, должен отличаться от идентификатора платежа, в рамках которого выполнялась регистрация повторяемой оплаты, и быть уникальным в рамках проекта. Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись, идентификатор записи о серии списаний и параметры, значения которых необходимо изменить. ```language-json { "general":{ "project_id":42, "payment_id":"456789", "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "recurring":{ "id":1079, "interval":3, "period":"M", "time":"12:00:00" } } ``` Информация об обновлённых условиях проведения оплаты передаётся от платёжной платформы к веб-сервису в оповещении стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В данном случае оповещение свидетельствует о том, что условия повторяемой оплаты изменены на следующие: периодичность списаний — каждые три месяца, время выполнения последующих списаний — 12:00:00. ```language-json { "project_id":123, "recurring":{ "id":1079, // Идентификатор записи о серии списаний "currency":"USD", "status":"active", // Статус записи о серии списаний "type":"R", "expiry_month":"5", // Месяц окончания действия повторяемой оплаты "expiry_year":"2025", // Год окончания действия повторяемой оплаты "period":"M", // Периодичность списаний "period_interval":3, "time":"12:00:00" // Время выполнения последующих списаний }, "signature":"IL9tVftZ1ZZ5D/b0VMdeR+YyilUwSm...==" } ``` ## Отмена дальнейшего выполнения списаний {#section_wkc_2f2_5jb .section} При формировании запроса на отмену проведения повторяемой оплаты необходимо учитывать следующее: 1. Должен использоваться POST-запрос к конечной точке [/v2/payment/card/recurring/cancel](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring-cancel). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - Объект `recurring` с идентификатором записи о серии списаний `id`, полученным в оповещении с данными о регистрации. Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и идентификатор серии списаний. ```language-json { "general":{ "project_id":42, "payment_id":"456789", "signature":"VftZ1ZZ5D/aMdeR+CqilUwSm...==" }, "recurring":{ "id":1079 } } ``` Результат отмены проведения оплаты передаётся от платёжной платформы к веб-сервису в оповещении стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В данном случае оповещение свидетельствует о том, что повторяемая оплата с идентификатором `1079` отменена. ```language-json { "project_id":42, "recurring":{ "id":1079, // Идентификатор серии списаний "currency":"USD", "status":"canceled", // Статус, свидетельствующий об отмене повторяемой оплаты "type":"R", "expiry_month":"5", "expiry_year":"2025", "period":"M", "period_interval":3, "time":"12:00:00" }, "signature":"MpfogAxwRItZ1Z/AeMde+GrNYyUwSm...==" } ``` **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) --- # Работа с повторными попытками автоматических списаний {#ru_gate_cof_retry_attempts} статья о возможностях работы с повторными попытками автоматических списаний при проведении повторяемых оплат **На уровень выше:**[Повторяемые оплаты](ru_Gate__payments_on_saved_data.md) ## Общая информация {#ru_gate_cof_retry_attempts_overview} ### Введение {#section_ep1_czr_yhc .section} В случаях, когда автоматическое списание в рамках регулярной оплаты отклоняется, например из-за недостатка средств на счёте пользователя,в платёжной платформе Ecommpay могут автоматически инициироваться повторные попытки выполнить такое списание спустя заданное время.По согласованию с курирующим менеджером Ecommpay такая возможность может подключаться по отдельным проектам и использоваться для заданной группы платёжных методов. При этом уведомления пользователей о применении такой функциональности, а также о том, что в конкретных случаях плановые списания были отклонены и для них запланированы повторные попытки, должны обеспечиваться со стороны мерчанта. В случаях, когда возможность повторных попыток автоматических списаний не применяется, при отклонении любого из очередных списаний в платформе ожидается следующее \(согласно графику; [подробнее](ru_gate_cof_retry_attempts.md)\) и со стороны мерчанта должны приниматься решения относительно необходимости дополнительного внеочередного списания или завершения серии списаний в целом. ### Особенности {#section_l3p_vzr_yhc .section} При работе с повторными попытками автоматических списаний стоит учитывать следующие особенности: - для каждого проекта может использоватьсясвой график выполнения повторных попыток — базовыйот Ecommpay или индивидуально заданныйсо стороны мерчанта; - повторные попытки применимы дляограниченного числа глобальных платёжных методов — классических карточных платежей, Apple Pay и Google Pay; - повторные попытки применимы только для регулярных оплат с хранением графика списаний на стороне платёжной платформы\(с типом `R`\); - повторные попытки могут выполняться тольков тех случаях, когда предшествующие попытки списаний были отклонены на стороне платёжной системы или эмитента; - применение повторных попыток не гарантирует итогового списания средств — если допустимое число попыток не приводит к списанию,такое списание считается отклонённым \(со статусом операции `decline`\) и целевая оплата проводится в платформе дальше согласно её графику. ### Варианты применения {#section_zvq_21s_yhc .section} Способы применения повторных попыток списаний можно рассмотреть на частных примерах. ![](images/universal/retry_attempt_1.svg "1 — без повторных попыток") ![](images/universal/retry_attempt_2.svg "2 — с базовым графиком") ![](images/universal/retry_attempt_3.svg "3 — с базовым графиком и отменой") ![](images/universal/retry_attempt_4.svg "4 — с индивидуальным графиком") Если в рамках повторяемой оплаты плановые списания инициируются по понедельникам в 12:00 и по графикудолжны быть выполнены 02, 09, 16 и 23 ноября, но 09 и 16 ноября плановыхсписаний средств не происходит, то реагирование на такую ситуацию может обеспечиваться следующим образом: 1. Если повторные попытки для такой оплаты недоступны, тонезависимо от того, было ли выполнено или отклонено очередное списание, за нимпланируется и выполняется следующее. 2. Если для повторных попыток используется базовый график от Ecommpay, то вслед за отклонением исходной попытки любого из очередных списаний для негообеспечивается актуальное число повторныхпопыток: две первые с интервалом в 12 часов и последующие с интервалом в 24 часа и остановкой не менее чем за 24,5 часа до очередного списания в понедельник. 3. Если для повторных попыток используется базовый график от Ecommpay и со стороны веб-сервиса отменяются дальнейшие повторные попытки после трёх подряд отклонённых, то вслед за отклонением исходной попытки любого из очередных списаний для негообеспечивается актуальное число повторныхпопыток, но не более трёх подряд. 4. Если для повторных попыток используется индивидуальный график от мерчанта, то вслед за отклонением исходной попытки любого из очередных списаний для негообеспечивается актуальное число повторныхпопыток: с интервалами, кратными 24 часам, и остановкой не менее чем за 24,5 часа до очередного списания в понедельник. С учётом вариативности графиков самих регулярных оплат и возможностей гибкого применения повторных попыток списаний подобные схемы можно адаптировать к широкому кругу ситуаций.При этом со стороны мерчанта в любом случае целесообразно контролировать статусы всех операций и выстраивать работу с пользователями с учётом этих статусов и графика повторных попыток. ## Схема работы {#ru_gate_cof_retry_attempts_workflow} Технически повторные попытки списаний выполняются следующим образом: 1. При отклонении со стороны платёжной системы или эмитента исходной попытки очередного списания в платёжной платформе Ecommpayпроверяется возможность повторить попытку, и если эта возможность подтверждается, то к веб-сервису направляется оповещение об отклонении списания со статусом операции `decline` и с плановыми датой и временем повторной попытки. 2. В заданное время автоматически выполняется повторная попытка списания. 3. Исходя из результата повторной попытки выполняются последующие действия: - Если попытка приводит к переводу необходимых средств от пользователя к мерчанту, то к веб-сервису направляется оповещение о результате списания \(со статусом операции `success`\) и оплата проводится дальше согласно графику. - Если попытка отклоняется ив платёжной платформе подтверждается возможность выполнить следующую попытку, то к веб-сервису направляется повторное оповещение об отклонении списания \(со статусом операции `decline` и с плановыми датой и временем следующей попытки\) и шаг 2 повторяется. - Если попытка отклоняется ив платёжной платформе не подтверждается возможность выполнить следующую попытку, то к веб-сервису направляетсяитоговое оповещение об отклонении списания \(со статусом операции `decline` и без информации о следующей попытке\) и оплата проводится дальше согласно графику.В таком случае решения относительно необходимости дополнительных списаний или завершения серии списаний и оплаты в целом должны приниматься на стороне мерчанта. Общая схема этого процесса выглядит следующим образом. ![](images/ru_gate_uml_scheduled_recurring_retry.svg) 1. Если исходная попытка списания не завершилась переводом средств, то для этого списания в платёжной платформе проверяется возможность выполнения повторной попытки. 2. От платёжной платформы к веб-сервису направляется оповещение об отклонении планового списания \(со статусом операции `decline`\) с датой и временем выполнения повторной попытки. 3. На стороне веб-сервиса обеспечивается информирование пользователя об отклонении списания и планировании новой попытки. 4. От платёжной платформы к платёжной системе в соответствующие дату и время направляется запрос на списание. 5. В платёжной системе выполняется дальнейшая обработка запроса и его отправка эмитенту. 6. На стороне эмитента выполняется обработка списания. 7. От эмитента к платёжной системе направляется информация о результате списания. 8. От платёжной системы к платёжной платформе направляется информация о результате списания. 9. В платёжной платформе проверяются необходимость и возможность выполнения повторной попытки. Если актуально, со стороны платёжной платформы инициируются следующие попытки списания и для каждой из них повторяются шаги 2–8. 10. От платёжной платформы к веб-сервису направляется итоговое оповещение о результате списания: со статусом `decline` \(если ни одна из попыток не привела к переводу средств от пользователя к мерчанту\) или `success` \(если одна из попыток привела к переводу средств\). 11. На стороне веб-сервиса обеспечивается информирование пользователя о результате списания. 12. Со стороны платёжной платформы инициируются последующие плановые списания и для каждого из них могут повторяться шаги 1–11. Формат оповещений, используемых в рамках этого процесса, описан [далее](ru_gate_cof_retry_attempts.md). ## Подключение {#ru_gate_cof_retry_attempts_integration} Чтобы подключить возможность работы с повторными попытками автоматических списаний, со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpayподключение этой возможности и необходимость её тестирования. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работы с использованием этой возможностии сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении возможности. ## Управление графиками попыток {#ru_gate_cof_retry_attempts_schedule} ### Общая информация {#section_kk5_pds_yhc .section} Платёжная платформа позволяет задавать для каждого проекта отдельный график повторных попыток списаний\(действительный для каждой регулярной оплаты в рамках этого проекта\) — с помощью соответствующих программных запросов через Gate \(подробнее далее\) или инструментов интерфейса Dashboard \([подробнее](ru_dbl_payments.md)\). При этом может использоваться базовый график, заданный со стороны Ecommpay в качестве варианта по умолчанию, или индивидуальный график, настроенный со стороны мерчанта с учётом специфики конкретного проекта. Основные свойства этих графиков можно сопоставить следующим образом. - В базовом случае для каждого очередного списания допускается не более 7 повторных попыток, которые могут быть выполнены в течение 6 суток. Первые две попытки \(между исходной попыткой очередного списания и первой повторной попыткой, а также между первой и второй повторными попытками\) в этом варианте выполняются с интервалом 12 часов и с ограничением, что до следующего планового списания \(согласно графику списаний\) остаётся не менее 12,5 часов. Последующие пять попыток — с интервалом 24 часа и со временем до следующего планового списания не менее 24,5 часов. - В случае с индивидуальным графиком для каждого очередного списания допускается от 1 до 10 повторных попыток, которые могут быть выполнены в течение 10 суток. При этом интервал перед выполнением любой повторной попытки может быть произвольным, но должен быть кратным 24 часам и с ограничением, что до следующего планового списания \(согласно графику списаний\) остаётся не менее 24,5 часов. Например, для ежемесячных списаний четыре попытки повторных списаний могут быть выстроены с увеличивающимися интервалами в 24, 48, 72 и 96 часов \(на 1, 3, 6 и 10 сутки, с соблюдением ограничений на общий период в 10 суток и на время до очередного списания не менее 24,5 часов\). График любого проекта можно менять, настраивая индивидуальные параметры или сбрасывая их значения к базовым. При этом стоит учитывать, что каждая повторная попытка, которая относится к целевому проекту ибыла запланирована при отклонении исходной или очередной попытки списаниядо изменения графика, выполняется согласно запланированным дате и времени\(по предыдущему графику\), но если какая-либо из таких попыток отклоняется уже после изменения графика и в платёжной платформе подтверждается возможность выполнить следующую попытку этого списания, то новая попытка планируется и выполняется по обновлённому графику.И в любом случае информация о каждой последующей попытке направляется к веб-сервису в оповещении об отклонении очередной попытки списания \([подробнее](ru_gate_cof_retry_attempts.md)\). Также при работе с Gate API следует учитывать, что для выполнения запросов по работе с графиком повторных попыток списаний используется синхронная схема взаимодействия между веб-сервисом и платёжной платформой. В рамках этой схемы каждый запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа \(`200`\) и запрошенная информация без указания статуса запроса. В случаях, когда запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса `error` и описание причины обнаруженной ошибки. Описание типового формата ответа представлено [в отдельной статье](ru_gate_interaction_organisation.md). ### Настройка индивидуального графика {#section_ess_133_qhc .section} Чтобы настроитьчерез Gate API индивидуальный график повторных попыток для автоматических списаний в рамках конкретного проекта, следует: 1. Отправить POST-запрос к конечной точке [/v2/recurring/retry-custom-schedule/save](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-save). 2. Принять синхронный ответ об изменении графика в платформе. При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\); - `interval_days` — массив с порядковыми номерами дней для выполнения повторных попыток, отсчитываемых от того дня, в который была отклонена исходная попытка целевого списания, иуказываемыхв виде последовательности возрастающих чисел в диапазоне от 1 до 10,через запятую в качестве разделителя\(например: `[1,5,9]`\). Таким образом, корректный запрос должен содержать идентификатор проекта, подпись и массив `interval_days`. В следующем примере повторные попытки списаний должны быть запланированы на 1, 5 и 9 сутки с момента отклонения исходной попытки списания. ``` {#codeblock_erz_wk1_c3c .language-json} { "general":{ "project_id": 42, "signature": "K5D/aZAsdsg ... R+YyilEtbS=" }, "interval_days": [1,5,9] } ``` ``` {#codeblock_grz_wk1_c3c .language-json} { "general":{ "project_id": 42, "signature": "K5D/aZAsdsg ... R+YyilEtbS=" }, "interval_days": [1,5,9] } ``` При выполнении запросана настройку индивидуального графика от платёжной платформы к веб-сервису передаётся ответ с кодом `200 OK`, а при отклонении — с указанием статуса обработки запроса `error` и поясняющего описания, например `Recurring retry not enabled`. ### Проверка графика {#section_gl4_qds_yhc .section} Чтобы проверитьчерез Gate API график повторных попыток для автоматических списаний, используемый в рамках конкретного проекта, следует: 1. Отправить POST-запрос к конечной точке [/v2/recurring/retry-custom-schedule/info](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-info). 2. Принять синхронный ответ с информацией о графике. При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\). Таким образом, корректный запрос должен содержать идентификатор проекта и подпись. ``` {#codeblock_ojj_vf3_qhc .language-json} { "general":{ "project_id": 42, "signature": "K5D/kyky...il8l=" } } ``` ``` {#codeblock_cbm_dvn_c3c .language-json} { "general":{ "project_id": 42, "signature": "K5D/kyky...il8l=" } } ``` При выполнении запросана получение сведений об используемом графике от платёжной платформы к веб-сервису передаётся ответ с кодом `200 OK` и с актуальной информацией, а при отклонении — с указанием статуса обработки запроса `error` и поясняющего описания. В теле ответа со сведениями о графике указываются идентификатор проекта и объект `schedule`. Если для целевого проекта в платформе задан индивидуальный график повторных попыток, в объект `schedule` включаются следующие параметры: - `interval_days` — массив с порядковыми номерами дней для выполнения повторных попыток, отсчитываемых от того дня, в который была отклонена исходная попытка целевого списания, иуказываемыхв виде последовательности возрастающих чисел в диапазоне от 1 до 10,через запятую в качестве разделителя\(например: `[1,5,9]`\). - `status` — указатель использования индивидуального графика \(со значением `active`, подтверждающим, что для целевого проекта был задан и не деактивирован индивидуальный график\). Если для целевого проекта используется базовый график от Ecommpay, объект `schedule` передаётся с пустым значением. В следующем примере содержится информация о том, что для проекта `42` используется индивидуальный график, в рамках которого предусмотрены повторные попытки списаний на 1, 5 и 9 сутки с момента отклонения исходной попытки списания. ``` {#codeblock_snw_5g3_qhc .language-json} { "project_id": 42, "schedule": { "interval_days": [1,5,9], "status": "active" } } ``` ``` {#codeblock_h22_1xn_c3c .language-json} { "project_id": 42, "schedule": { "interval_days": [1,5,9], "status": "active" } } ``` В следующем примере отсутствуют сведения об индивидуальном графике, что свидетельствует об использовании для проекта `42` базового графика повторных попыток. ``` {#codeblock_lwx_vg1_c3c .language-json} { "project_id": 42, "schedule": {} } ``` ``` {#codeblock_jd1_wg1_c3c .language-json} { "project_id": 42, "schedule": {} } ``` ### Сброс графика к базовым значениям {#section_hf1_sds_yhc .section} Чтобы вернуть к базовым значениям график повторных попыток для автоматических списаний в рамках конкретного проекта, используя Gate API, следует: 1. Отправить POST-запрос к конечной точке [/v2/recurring/retry-custom-schedule/disable](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-custom-schedule-disable). 2. Принять синхронный ответ о выполнении запроса. При работе с такими запросами каждый раз должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\). Таким образом, корректный запрос должен содержать идентификатор проекта и подпись. ``` {#codeblock_d4s_jtn_qhc .language-json} { "general":{ "project_id": 42, "signature": "K5D/aZAMdeR+YyilUwS=" } } ``` ``` {#codeblock_hdj_k5z_b3c .language-json} { "general":{ "project_id": 42, "signature": "K5D/aZAMdeR+YyilUwS=" } } ``` При выполнении запросана сброс графика к базовым значениям от платёжной платформы к веб-сервису передаётся ответ с кодом `200 OK`, а при отклонении — с указанием статуса обработки запроса `error` и поясняющего описания. ## Контроль выполнения попыток {#ru_gate_cof_retry_attempts_monitoring} Повторные попытки списаний выполняются на стороне платёжной платформы автоматически, в соответствии сактуальным графиком и общей [схемой](ru_gate_cof_retry_attempts.md). Со стороны веб-сервиса при этом важно обеспечивать контроль таких попыток и выстраивать работу с пользователями с учётом итоговых результатов списаний. Для получения информации о планировании и выполнении каждой повторной попытки списания можно использовать оповещения от платформы. Общая информация о работе с такими оповещениями представлена [в отдельной статье](ru_platform_callbacks.md). В случаях, когда для автоматических списаний по проекту используются повторные попытки, в оповещения включается дополнительный объект `recurring_retry`, в структуре которого, в зависимости от ситуации, могут использоваться следующие параметры: - `trigger_operation_id` — идентификатор очередного списания, для которого была выполнена повторная попытка. Указывается в тех случаях, когда была выполнена по крайней мере одна повторная попытка. - `retry_count` — число использованных повторных попыток\(в виде числа от 1 до 7при использовании базового графика либо от 1 до 10 при использовании индивидуального\). Указывается в тех случаях, когда была выполнена по крайней мере одна повторная попытка. - `next_retry_exists` — индикатор наличия следующей запланированной попытки \(со значением `true`, если перевод средств не был выполнен и в платформе подтверждена возможность повторить попытку списания, и со значением`false`в остальных случаях\). Указывается во всех случаях. - `next_retry_date` — дата и время следующей запланированной попытки. Указывается в тех случаях, когда была запланирована очередная повторная попытка. В следующем примере содержится информация о том, что для одного из очередных списаний повторяемой оплаты не выполнялось и не планируется ни одной повторной попытки. Оповещения с такой информацией могут отправляться, когда исходная попытка списания привела к переводу средств или повторные попытки не могут выполняться. ``` {#codeblock_xsk_ybp_qhc .language-json} "recurring_retry": { "next_retry_exists": false } ``` В следующем примере содержится информация о том, что вслед за отклонённой исходной попыткой очередного списания запланирована первая повторная попытка \(`"next_retry_exists": true`\). В этом случае не указываются идентификатор целевого списания и идентификатор повторной попытки, поскольку ни одна повторная попытка ещё не выполнялась. ``` {#codeblock_usk_ybp_qhc .language-json} "recurring_retry": { "next_retry_exists": true, "next_retry_date": "2026-01-21T16:58:02+0000" } ``` В следующем примере содержится информация о том, что первая повторная попытка \(`"retry_count": 1`\) списания `344589675` была отклонена и для этого списания запланирована вторая повторная попытка \(`"next_retry_exists" : true`\) на `2026-01-25T16:58:02+0000`. ``` {#codeblock_vsk_ybp_qhc .language-json} "recurring_retry": { "trigger_operation_id": 344589675, "retry_count": 1, "next_retry_exists": true, "next_retry_date": "2026-01-25T16:58:02+0000" } ``` В следующем примере содержится информация о том, что для списания `344589675` была выполнена вторая повторная попытка \(`"retry_count": 2`\) и последующих попыток не планируется \(`"next_retry_exists" : false`\). Это может быть связано с тем, что вторая повторная попытка привела к переводу средств от пользователя к мерчанту \(об этом должен свидетельствовать статус операции `success`\), либо с тем, что повторные попытки исчерпаны, не приведя к переводу средств \(об этом должен свидетельствовать статус операции `decline`\). ``` {#codeblock_wsk_ybp_qhc .language-json} "recurring_retry": { "trigger_operation_id": 344589675, "next_retry_exists": false, "retry_count": 2 } ``` ## Отмена дальнейших попыток {#ru_gate_cof_retry_attempts_cancel} Чтобы отменитьчерез Gate API выполнение дальнейших повторных попыток для конкретного списания, следует: 1. Отправить POST-запрос к конечной точке [/v2/recurring/retry\_stop](https://api-developers.ecommpay.com/api.html/post-v2-recurring-retry-stop). 2. Принять синхронный ответ о прекращении повторных попыток для указанного списания. Следует учитывать, что для выполнения таких запросов используется синхронная схема взаимодействия между веб-сервисом и платёжной платформой, когда каждый запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса с предоставлением актуального ответа. Описание типового формата синхронного ответа представлено [в отдельной статье](ru_gate_interaction_organisation.md). Общая схема выполнения запроса на отмену дальнейших попыток для конкретного списания выглядит следующим образом. ![](images/ru_gate_uml_scheduled_recurring_retry_stop.svg) 1. От веб-сервиса на заданный URL Ecommpay направляется запрос на отмену дальнейших повторных попыток, запланированных в платформе для отклонённого списания. 2. Этот запрос поступает в платёжную платформу. 3. В платёжной платформе выполняется обработка запроса и отменяются дальнейшие попытки выполнить это списание. 4. От платёжной платформы к веб-сервису направляется ответ с информацией о выполнении запроса. 5. На стороне веб-сервиса обеспечивается информирование пользователя о результате списания. 6. Со стороны платёжной платформы инициируются последующие плановые списания. При работе с запросами на отмену дальнейших повторных попыток конкретного списания каждый раз должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\); - `recurring` — объект, содержащий сведения о повторяемой оплате: - `id` — идентификатор записи о целевой серии списаний, полученный при регистрации повторяемой оплаты или заданный при переносе информации об этой оплате от стороннего эквайера; - `trigger_operation_id` — идентификатор списания, для которого необходимо прекратить выполнение повторных попыток. Таким образом, корректный запрос на отмену дальнейших повторных попыток должен содержать идентификаторы проекта, серии списаний и целевого списания, а также подпись. ``` {#codeblock_erz_wk1_c3c .language-json} { "general":{ "project_id":42, "signature":"K5D/anjn7fv+YyilUwS==" }, "recurring":{ "id":1079 }, "trigger_operation_id":092384 } ``` ``` {#codeblock_grz_wk1_c3c .language-json} { "general":{ "project_id":42, "signature":"K5D/anjn7fv+YyilUwS==" }, "recurring":{ "id":1079 }, "trigger_operation_id":092384 } ``` При выполнении запросана отмену дальнейших попыток списания от платёжной платформы к веб-сервису передаётся ответ с кодом `200 OK`, а при отклонении — с указанием статуса обработки запроса `error` и поясняющего описания. ## Дополнительные материалы {#ru_gate_cof_retry_attempts_useful_links} При работе с повторными попытками автоматических списаний могут быть полезны следующие материалы: - [Контроль и проведение платежей](ru_dbl_payments.md)— статья с информацией о работе с платежами через интерфейс , включая работу с регулярными оплатами и управление повторными попытками списаний в рамках таких оплат. - [Проведение оплаты с автоматическими списаниями](ru_Gate__cof_gate_side.md)— статья о проведении повторяемых оплат с автоматическими списаниями через , включая общую информацию о таких оплатах и описания схем их проведения и форматов данных при работе с классическими карточными платежами. - [Организация взаимодействия](ru_gate_interaction_organisation.md)— статья о порядке работы с платёжной платформой через , включая описание применяемых схем взаимодействия и общих требований к форматам данных. - [Работа с оповещениями](ru_platform_callbacks.md)— статья о работе с программными оповещениями, позволяющими максимально оперативно получать значимую информацию о проведении каждого платежа, с описанием применяемых типов оповещений и структуры используемых данных. - [Работа с подписью к данным](ru_platform_signature.md)— статья о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. --- # Возвраты средств после оплат {#ru_Gate_Refund .concept} статья о порядке выполнения через Gate возвратов по проведённым ранее оплатам разных типов *Возвратом* в рамках платёжной платформы Ecommpay считается перевод пользователю средств, ранее списанных при проведении оплаты. Если средства были не списаны, а, например, заблокированы, то возвращение пользователю доступа к этим средствам выполняется в платформе через операцию отмены блокировки, а не операцию возврата \(подробнее — [Оплата в две стадии](ru_gate_payment_auth.md)\). Платёжная платформа поддерживает выполнение возвратов через Gate или через Dashboard. В этом разделе представлена информация о выполнении возвратов через Gate.Общие сведения актуальны как для работы с платёжными картами, так и для работы с другими платёжными инструментами, а техническая информация актуальна только для работы с картами. Техническая информация о возврате средств при работе с другими платёжными инструментами представлена в разделе [Методы](ru_pm_about.md). ## Общая информация {#section_bj4_z21_sjb .section} Платёжная платформа поддерживает возможности возврата средств пользователю после проведения разовой и повторяемой оплаты. В общем случае срок, в течение которого после оплаты можно выполнить возврат, не ограничивается, однако для некоторых платёжных методов могут быть установлены ограничения или дополнительные комиссии, взимаемые за выполнение возврата по истечении заданного времени. Чтобы инициировать возврат при работе через Gate, со стороны веб-сервиса необходимо отправить запрос к конечной точке `/v2/payment/\{название метода\}/refund`. При этом следует учитывать особенности и ограничения, перечисленные далее в соответствующих разделах. В общем случае в зависимости от того, когда и на какую сумму инициируется возврат, для его выполнения формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия операционного дня и на всю сумму оплаты; - `refund`, если возврат инициируется до закрытия операционного дня и на часть суммы оплаты или после закрытия операционного дня вне зависимости от суммы. Исключением является возврат после оплаты, проведённой с использованием карты платёжной системы Visaили American Express. Для выполнения такого возврата в зависимости от того, когда он инициируется, и вне зависимости от суммы формируется одна из следующих операций: - `reversal`, если возврат инициируется до закрытия операционного дня; - `refund`, если возврат инициируется после закрытия операционного дня. **Прим.:** Под операционным днём понимается временной диапазон, за который выполненные операции учитываются для проведения клиринга. Этот диапазон равен одним суткам с учётом варьирования их продолжительности при переходах на летнее и зимнее время. Начало и окончание операционного дня в разных случаях могут варьироваться с учётом разных факторов, информацию о которых следует уточнять у курирующего менеджера Ecommpay. Таким образом, возврат инициируется одним запросом и может выполняться для двух типов платежей — разовых и повторяемых оплат — с помощью одной из двух операций: `refund` или `reversal`. ![Схема соответствия между запросом, платежами и операциями](images/ru_gate_model_refund.svg "Схема соответствия между запросом, платежами и операциями") После выполнения возврата к веб-сервису передаётся оповещение, в котором содержится информация о результате выполнения возврата и о статусе платежа после возврата. Статус платежа может принимать следующие значения: - `success` — платёж проведён, возврат для платежа не выполнен; - `reversed` — до закрытия операционного дня для платежа выполнен возврат всей суммы; - `refunded` — после закрытия операционного дня для платежа выполнен возврат всей суммы; - `partially reversed` — до закрытия операционного дня для платежа выполнен возврат части суммы \(только для карт платёжных систем Visaи American Express\); - `partially refunded` — для платежа выполнен возврат части суммы \(для карт платёжных систем Visaи American Express — после закрытия операционного дня\); - `scheduled recurring processing` — для повторяемой оплаты выполнен возврат всей суммы или части суммы, при этом ожидаются дальнейшие списания средств в рамках этой оплаты. ## Особенности {#section_o1n_dwl_5jb .section} Срок выполнения возврата, как правило, зависит от банка-эмитента или платёжного провайдера, выполняющего операцию, и может занять длительное время. При выполнении возврата изменяются данные о сумме платежа. В оповещении о результате возврата указывается актуальная сумма платежа, доступная для дальнейших возвратов. Актуальная сумма платежа рассчитывается как разница между исходной суммой платежа и суммой, возвращённой пользователю. Допустим, исходная сумма равна `13,70` долларов США. Тогда при возврате на сумму `10,00` долларов актуальная сумма платежа принимает значение `3,70` долларов, а при ещё одном возврате на сумму `3,70` долларов — `0,00` долларов. Это правило справедливо в том числе для регулярных оплат, при которых актуальную сумму платежа составляют суммы всех списаний в рамках этого платежа за вычетом суммы всех выполненных возвратов. В зависимости от используемого платёжного метода могут быть актуальны и другие особенности выполнения возвратов. К ним может относиться, например, удержание дополнительной комиссии за выполнение возврата по истечении заданного времени. Информацию о таких особенностях можно получитьв разделе с описанием платёжных методов \([Методы](ru_pm_about.md)\) и у курирующего менеджера Ecommpay. ## Ограничения {#section_g2m_fpf_5jb .section} Выполнение возвратов возможно с учётом следующих ограничений: - В рамках оплаты, для которой выполняется возврат, должно быть выполнено хотя бы одно списание средств пользователя, при этом самой оплате должен соответствовать один из следующих статусов: `success`, `sсheduled recurring processing` или `partially refunded`. Если в рамках оплаты не выполнено ни одного успешного списания или статус оплаты не соответствует ни одному из перечисленных, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки, например `3081`. - Валюта возврата должна соответствовать валюте оплаты, для которой выполняется возврат. Если в запросе передана валюта, не соответствующая валюте оплаты, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3284` \(подробнее о таких кодах — в разделе [Работа с информацией об операциях](ru_platform_payment_info_codes.md)\). - Должна соблюдаться допустимая частота отправки запросов. Если повторный запрос на возврат отправлен ранее, чем через две минуты, то этот запрос отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3285`. - Остаток средств на счёте мерчанта должен быть достаточным для выполнения возврата. Информацию об остатке средств можно получить с помощью запроса через Data API \([Использование Data API](ru_dbl_api_protocol.md)\) или в интерфейсе Dashboard \(раздел [Ведение финансового учёта](ru_dbl_balances.md)\), а также при обращении к курирующему менеджеру Ecommpay. - Должны соблюдаться актуальные для этого возврата специфические региональные требования, а также требования провайдеров и платёжных систем. Например, для одной оплаты, осуществляемой на территории Белоруссии или с использованием платёжной карты этой страны, допускается только один возврат.Информацию о специфике выполнения возвратов в зависимости от используемого платёжного метода можно получить в разделе [Методы](ru_pm_about.md) и при обращении к курирующему менеджеру Ecommpay. - Оплата, для которой выполняется возврат, не должна быть оспариваемой. Если для оплаты начался процесс опротестования, то запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3288`. Помимо перечисленных ограничений для частичных возвратов действуют следующие: - При выполнении частичного возврата его сумма не должна превышать актуальную сумму платежа, иначе запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3283`. - Если частичный возврат выполняется для карточного платежа, после выполнения такого возврата актуальная сумма платежа должна быть не менее 0,01 USD. Актуальная сумма проверяется на стороне платёжной платформы после инициирования возврата, в том числе с учётом валютных курсов, если валюта платежа отличается от USD. В случае несоответствия ограничению запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3117`. - Инициировать новый частичный возврат можно только после выполнения предыдущего, иначе запрос на возврат отклоняется и к веб-сервису направляется оповещение с кодом ошибки `3285`. Информация о форматах запросов и оповещений при использовании платёжных карт представлена далее, а о форматах запросов и оповещений при использовании других платёжных инструментов — в разделе [Методы](ru_pm_about.md). ## Формат запроса {#section_jwj_mf1_sjb .section} Формат запроса на возврат соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md), конечной точкой API для этого запроса выступает [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund), а в теле запроса должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись к данным запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - `payment` — объект, содержащий сведения о платеже: - `description` — описание причины возврата; относится только к операции возврата и не меняет описание оплаты, если оно было передано ранее. Описание причины возврата может указываться в оповещениях в параметре `operation_description`. По умолчанию этот параметр не используется, но он может быть включён в состав оповещений по согласованию со специалистами технической поддержки. Перечисленных параметров достаточно для возврата пользователю всей суммы платежа. Чтобы возвратить часть суммы, в объекте `payment` дополнительно необходимо использовать следующие параметры: - `amount` — сумма возврата, не превышающая актуальную сумму платежа, в дробных единицах валюты; - `currency` — код валюты возврата в формате ISO-4217 alpha-3; указываемая валюта должна быть той же, что и валюта платежа. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос для возврата средств должен содержать идентификаторы проекта и платежа, подпись, описание причины возврата, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 239, "payment_id": "payment2", "signature": "of8k9xeKJ7KLTZYO56lCv+f1M0Sf/7eg==" }, "payment": { "description": "refund", // При частичном возврате: "amount": 1000, "currency": "USD" } } ``` ## Формат оповещений {#section_ens_mf1_sjb .section} Формат оповещения о результате возврата соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md). Информация об актуальной сумме платежа содержится в объекте `payment`, а о сумме, возвращённой пользователю, — в объекте `operation`. Также оповещение может содержать описание причины возврата в объекте `operation_description`, если это было настроено специалистами технической поддержки по запросу мерчанта. **Прим.:** В случае, если для одной оплаты выполняются несколько частичных возвратов, при разборе оповещений следует учитывать, что каждому отдельному частичному возврату \(то есть каждой отдельной операции\) соответствует свой идентификатор. Его значение передаётся в параметре `operation_id` объекта `operation`. Далее представлены примеры информации из оповещений о полном и частичном возврате для разовой оплаты на исходную сумму `13,70 USD`: 1. на сумму `10,00 USD`, при этом актуальная сумма платежа равна `3,70 USD`, а статус платежа соответствует `partially refunded`; 2. на сумму `13,70 USD`, при этом актуальная сумма платежа равна `0,00 USD`, а статус платежа соответствует `refunded`. В каждом из этих примеров содержится описание оплаты, так как оно было передано в запросе на оплату, и описание причины возврата. ```language-json { "project_id":239, "payment":{ "id":"payment2", "type":"purchase", // Тип платежа — разовая оплата "status":"partially refunded", // Статус платежа после частичного возврата "date":"2019-11-13T14:52:14+0000", "method":"card", "sum":{ "amount":370, // Актуальная сумма платежа "currency":"USD" // Код валюты платежа }, "description":"Thai massage session" // Описание оплаты }, "account":{ "number":"431422******0056", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"03", "expiry_year":"2023" }, "operation_description":"Deficient service", // Описание причины возврата "operation":{ "id":3862, "type":"refund", // Тип операции "status":"success", // Статус операции "date":"2019-11-13T14:52:15+0000", "created_date":"2019-11-13T14:52:12+0000", "request_id":"0c4457b5fe8dada59-e7b58eceb8aecfa791-00049391", "sum_initial":{ "amount":1000, // Сумма возврата "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа) }, "sum_converted":{ "amount":1000, "currency":"USD" }, "code":"0", "message":"Success", "provider":{ "id":414, "payment_id":"", "endpoint_id":414 } }, "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` ```language-json { "project_id":239, "payment":{ "id":"payment2", "type":"purchase", // Тип платежа — разовая оплата "status":"refunded", // Статус платежа после полного возврата "date":"2019-11-13T13:52:09+0000", "method":"card", "sum":{ "amount":0, // Актуальная сумма платежа "currency":"USD" // Валюта платежа }, "description":"Thai massage session" // Описание оплаты }, "account":{ "number":"431422******0056", "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"03", "expiry_year":"2023" }, "customer":{ "id":"1478" }, "operation_description":"Service cancellation", // Описание причины возврата "operation":{ "id":3861, "type":"refund", // Тип операции "status":"success", // Статус операции "date":"2019-11-13T13:52:09+0000", "created_date":"2019-11-13T13:52:08+0000", "request_id":"67a97cd6b14f1aa0543c81e18cd270b66-aadc6e790206d5-00038611", "sum_initial":{ "amount":1370, // Сумма возврата "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа) }, "sum_converted":{ "amount":1370, "currency":"USD" }, "code":"0", "message":"Success", "provider":{ "id":414, "payment_id":"", "endpoint_id":414 } }, "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` В следующем примере содержится информация о том, что для повторяемой оплаты с суммой всех списаний, равной `7,99 EUR`, выполнен возврат на сумму `7,99 EUR` и до выполнения следующего списания актуальная сумма платежа равна `0,00 EUR`. Статус платежа в данном случае не изменился, так как в рамках этого платежа ожидаются дальнейшие списания \(подробнее о статусах — в разделе [Проведение платежей](ru_platform_payment_model.md)\). ```language-json { "project_id":239, "payment":{ "id":"payment3", "type":"recurring", // Тип платежа — повторяемая оплата "status":"scheduled recurring processing", // Статус платежа после возврата "date":"2019-11-13T17:23:26+0000", "method":"card", "sum":{ "amount":0, // Актуальная сумма платежа "currency":"EUR" // Валюта платежа }, "description":"Thai massage session" // Описание оплаты }, "account":{ "number":"431422******0056", "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"03", "expiry_year":"2023" }, "customer":{ "id":"1478" }, "recurring":{ "id":1061, "currency":"EUR", "valid_thru":"2027-05-31T00:00:00+0000" }, "operation_description":"Refund for payment3 order", // Описание причины возврата "operation":{ "id":3861, "type":"refund", // Тип операции "status":"success", // Статус операции при успешном возврате "date":"2019-11-13T17:23:26+0000", "created_date":"2019-11-13T17:23:25+0000", "request_id":"bb36c8b4bce2c4-0198d59676189b0e344d1-00056689", "sum_initial":{ "amount":799, // Сумма возврата "currency":"EUR" // Код валюты возврата (в соответствии с валютой платежа) }, "sum_converted":{ "amount":799, "currency":"EUR" }, "code":"0", "message":"Success", "provider":{ "id":414, "payment_id":"", "endpoint_id":6 } }, "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` В следующем примере содержится информация о том, что для разовой оплаты отклонён возврат на сумму `60,00 USD` в связи с нехваткой средств на счёте мерчанта, о чём свидетельствует код ошибки `3028` \(подробнее о таких кодах — в разделе [Работа с информацией об операциях](ru_platform_payment_info_codes.md)\). Сумма и статус платежа в данном случае не изменились. ```language-json { "project_id":239, "payment":{ "id":"payment7", "type":"purchase", // Тип платежа — разовая оплата "status":"success", // Статус платежа при отказе в возврате "date":"2019-12-29T15:29:47+0000", "method":"card", "sum":{ "amount":6000, // Сумма платежа "currency":"USD" // Валюта платежа }, "description":"Thai massage session" // Описание оплаты }, "account":{ "number":"431422******0056", "token":"14c24c8a5384b413f11b2956a82ddaeea609ea49", "type":"visa", "card_holder":"JUDY DOE", "expiry_month":"03", "expiry_year":"2023" }, "operation_description":"Error", // Описание причины возврата "operation":{ "id":3869, "type":"reversal", // Тип операции "status":"decline", // Статус операции при отказе в возврате "date":"2019-12-29T15:32:29+0000", "created_date":"2019-12-29T15:32:29+0000", "request_id":"713446e4b43-06bfc7eed42c4c854697846a-00059692", "sum_initial":{ "amount":6000, // Сумма возврата "currency":"USD" // Код валюты возврата (в соответствии с валютой платежа) }, "sum_converted":{ "amount":6000, "currency":"USD" }, "code":"3028", // Код ошибки "message":"Insufficient funds on merchant balance", // Описание ошибки "provider":{ "id":120, "payment_id":"", "endpoint_id":120 } }, "signature":"of8k9xerKSK4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` ## Дополнительные материалы {#section_bgg_xhl_5jb .section} При работе с возвратами также могут быть полезны следующие материалы: - [Проведение платежей](ru_platform_payment_model.md) — раздел с общей информацией о типах поддерживаемых платежей и операций, а также об их возможных статусах. - [Методы](ru_pm_about.md) — раздел с подробной информацией о проведении платежей с использованием различных платёжных методов. - [Работа с оповещениями](ru_platform_callbacks.md) — раздел с информацией об оповещениях и работе с ними. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md) — раздел с информацией о кодах ошибок, используемых в платёжной платформе. - [Контроль и проведение платежей](ru_dbl_payments.md) — раздел с информацией о проведении платежей и операций через Dashboard. **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Выплаты {#ru_Gate_payout} статья о порядке проведения через Gate выплат **Прим.:** Эта статья посвящена тому, как проводить выплаты через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с выплатами могут быть полезны: - статья [Выплата](ru_platform_payout_model.md) модели проведения платежей с описанием того, как в целом проводятся выплаты в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить выплаты через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. ## Общая информация {#section_htd_ylv_cjb .section} Выплата — это тип платежа, в рамках которого осуществляется один \(разовый\) перевод денежных средств от мерчанта к пользователю. В платёжной платформе поддерживается один вариант для работы с выплатами через Gate — разовые единичные выплаты,в том числе выплаты P2P \(person-to-person\), но дополнительно обеспечивается возможность проведения массовых выплат через Dashboard \(с автоматическим формированием требуемого количества платежей; подробнее — в разделе [Контроль и проведение платежей](ru_dbl_payments.md)\). В запросах на инициирование выплат реквизиты платёжных инструментов, как правило, необходимо передавать в явном виде, однако при работе с платёжными картами их можно указывать в форме токена, ассоциированного с реквизитами карты\(подробнее о токенах — в разделе [Использование токенов](ru_Gate_Token.md)\). ## Схема проведения {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate со стороны веб-сервиса необходимо: 1. Отправить запрос на выплату к конечной точке `/v2/payment/{название метода}/payout[/token]`. 2. При необходимости выполнить вспомогательную процедуру — дополнить информацию о платеже\(в настоящее время процедура не используется для работы с альтернативными платёжными методами\). Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md). 3. Принять от платёжной платформы оповещение о результате выплаты. Схема проведения выплаты в базовом случае — без выполнения вспомогательной процедуры — представлена далее. ![](images/ru_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату. 2. От веб-сервиса к платёжной платформе передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему. 7. Выполняется обработка платежа. 8. К платёжной платформе направляется уведомление о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. От веб-сервиса пользователю направляется результат выплаты. Информация о формате запросов и параметрах инициирования выплат по номеру \(токену\) карты, а также о формате оповещений о результатах выплат приведена далее. Информацию о возможных статусах выплаты можно найти [в соответствующей статье](ru_platform_payout_model.md). ## Формат запросов {#section_t11_mfk_1jb .section} При формировании запросов для выплаты на платёжную карту необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - если выплата по номеру карты — к [/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout); - если выплата по токену, ассоциированному с картой, — к [/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token); - если выплата P2P — к [/v2/payment/individual/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-individual-payout); 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта мерчанта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о получателе выплаты: - `id` — идентификатор получателя \(пользователя\) в рамках проекта мерчанта; - `first_name` — имя получателя; - `middle_name` — отчество или среднее имя получателя; - `last_name` — фамилия получателя; - `ip_address` — используемый IP-адрес. **Прим.:** Имя, отчество \(или среднее имя\) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для последних допускается не передавать эти параметры, но в некоторых случаях это может приводить к отклонению платежей. Чтобы повысить вероятность проведения платежей со стороны эмитентов, для таких карт рекомендуется передавать фамилию и имя получателя или хотя бы один из этих двух параметров. Информацию о передаче имени, отчества и фамилии пользователя для выплат с использованием российских карт можно уточнять у курирующего менеджера Ecommpay. Сведения об имени, отчестве \(или среднем имени\) и фамилии получателя должны передаваться базовой латиницей для всех карт, за исключением карт CUP, для которых эти данные передаются китайским иероглифическим письмом. Также для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, обязательно передавать сведения об имени и фамилии получателя в объекте `recipient`. В таких случаях сведения об имени и фамилии получателя в объекте `customer` можно не передавать \([подробнее](ru_Gate_payout.md#li_mpn_wmt_tqb)\). Это правило действует для всех карт, независимо от страны их выпуска. - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3. - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. 3. В запросе должны содержаться сведения о платёжной карте пользователя, на которую осуществляется выплата: - Если выплата по номеру карты — номер карты в параметре `pan` объекта `card`. Для проведения международных выплат вместе с номером карты также может понадобиться указать срок её действия и имя держателя в параметрах `year`, `month` и `card_holder` объекта `card` соответственно. Подробную информацию о проведении таких выплат можно получить у курирующего менеджера Ecommpay. - Если выплата по токену — токен, полученный от Ecommpay, в параметре `token`. 4. В случае проведения выплаты на карту платёжной системы Visa в запросе необходимо передавать дату рождения пользователя, указываемую в формате `ДД-ММ-ГГГГ` в параметре `day_of_birth` объекта `sender`. 5. В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект `recipient`, содержащий сведения о местонахождении получателя выплаты: - `country` — код страны получателя в формате ISO 3166-1 alpha-2; - `city` — город получателя; - `address` — адрес получателя; - если код страны соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), дополнительно следует передать параметр `state` — штат, провинция или другой регион получателя выплаты. 6. В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре `phone` объекта `sender`. 7. В случае проведения выплаты на карту платёжной системы Mastercard стоит учитывать, что при передаче адреса пользователя в параметре `address` объекта `customer` его длина не должна превышать 50 символов. 8. В случае проведения выплаты в рамках программ сервиса MoneySend платёжной системы Mastercard, в которой отправителем является физическое лицо, в запросе необходимо передавать информацию об имени и фамилии получателя в параметрах `first_name` и `last_name` объекта `recipient`, а также информацию об отправителе выплаты в объекте `sender`: - номер платёжного инструмента отправителя — `pan` для карты или `wallet_id` для электронного кошелька; - `first_name` — имя отправителя; - `last_name` — фамилия отправителя; - `address` — адрес отправителя; - `city` — город отправителя; - `zip` — почтовый индекс отправителя; - `country` — код страны отправителя в формате ISO 3166-1 alpha-2; - если код страны соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), дополнительно следует передать параметр `state` — штат, провинция или другой регион отправителя выплаты. 9. В случае проведения P2P-выплаты в запросе рекомендуется передавать сведения об отправителе средств: - `first_name` — имя отправителя; - `last_name` — фамилия отправителя; - `citizenship` — гражданство отправителя; - `residence` — страна, резидентом которой является отправитель; - `birthplace` — место рождения отправителя; - `billing` — объект с информацией о платёжном адресе отправителя. 10. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос для выплаты по номеру \(токену\) карты должен содержать идентификаторы проекта и платежа, подпись, идентификатор и IP-адрес пользователя, валюту и сумму платежа, а также номер или токен карты для зачисления средств. ```language-json { "general": { "project_id": 874, "payment_id": "1553840734526111", "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ==" }, //Номер карты для выплаты по номеру карты "card": { "pan": "5413330000000019" }, "customer": { "id": "1", "ip_address": "185.123.193.224" }, "payment": { "amount": 15000, "currency": "EUR" }, //Токен карты для выплаты по токену "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7" } ``` ``` {#codeblock_xbn_spb_f1c} { "general": { "project_id": 100, "payment_id": "Payment 12", "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJgu...==" }, "card": { "pan": "4242424242424242", "year": 2020, "month": 11 }, "customer": { "ip_address": "127.0.0.1", "id": "New", "phone": "999123456", "first_name": "John", "middle_name": "Jr", "last_name": "Jonson", "datetime": "2017-10-04T19:06:31+05:00", "birthplace": "Manchester", "identify": { "doc_number": "4666 123456", "doc_type": "Passport", "doc_issue_date": "20.12.2012", "doc_issue_by": "12346" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 23", "postal": "112233" }, "day_of_birth": "05-06-1981" }, "sender": { "phone": "39999999999", "first_name": "Jack", "middle_name": "Willy", "last_name": "Jackson", "datetime": "2018-12-05T19:06:31+05:00", "birthplace": "Manchester", "residence": "BL", "citizenship": "LV", "identify": { "doc_number": "1234 654321", "doc_type": "Passport", "doc_issue_date": "07-08-2014", "doc_issue_by": "23456" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 25", "postal": "406879" }, "day_of_birth": "07-08-1993" }, "payment": { "amount": 5000, "currency": "GBP" } } ``` ## Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат на платёжные карты используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `874` проведена выплата в размере `100,00 USD` на карту `553691******0802` пользователя `customer_10`. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...==" } } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении выплаты. Платёж отклонён из-за превышения максимально допустимого размера выплаты. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "3104", "message": "Payment Constraint Invalid Payout Amount" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...==" } } ``` **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Проверка платёжных инструментов {#ru_gate_account_verification} статья о порядке проверки через Gate действительности платёжных инструментов с условными списаниями или временными блокировками средств **Прим.:** Эта статья посвящена тому, как проверять действительность платёжных инструментов через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с проверкой действительности могут быть полезны: - статья [Проверка действительности платёжного инструмента](ru_platform_account_verification_model.md) модели проведения платежей с описанием того, как в целом проверяется действительность платёжных инструментов через платёжную платформу Ecommpay и какие статусы при этом могут использоваться; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проверять действительность платёжных инструментов через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. Информацию о возможности проведения проверки действительности платёжного инструмента необходимо уточнять у курирующего менеджера Ecommpay. ## Общая информация {#section_zzf_ddh_cjb .section} Проверка действительности платёжного инструмента — это тип платежа, в рамках которого для проверки возможности использования платёжного инструмента на основании одного исходного запроса осуществляется один условный \(нулевой\) перевод денежных средств от пользователя к мерчантуили одна реальная \(ненулевая\) блокировка средств пользователя с последующей отменой. При этом сумма блокировки может согласовываться с мерчантом, а срок отмены блокировки может составлять до 45 дней. Например, это может быть актуально при регистрации подписок на товары и услуги без списания средств за первый \(пробный\) период или перед проведением выплат пользователям. Подробная информация о регистрации повторяемых оплат представлена в разделе [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md).Также эта возможность актуальна и для так называемых оплат Mail Order/Telephone Order \(MO/TO\), при проведении которых пользователь предоставляет реквизиты с использованием почты, телефона или иных средств связи. Подробная информация об оплатах MO/TO представлена в разделе [Проведение оплат MO/TO](ru_Gate_moto.md). Для дополнительной оценки рисков мошенничества и опротестования платежей вместе с проверкой действительности можно оценивать достоверность имён держателей карт \([подробнее](ru_gate_cardholder_name_verification.md)\). ## Схема проведения {#section_lsx_3jl_ggb .section} Для проверки действительности платёжного инструмента через Gate со стороны веб-сервиса необходимо: 1. Отправить запрос к конечной точке `/v2/payment/\{название метода\}/account_verification[/token]`. 2. При необходимости выполнить вспомогательные процедуры, инициируемые со стороны платёжной платформы. Это может быть один из вариантов аутентификации пользователя или дополнение информации о платеже. - *Аутентификация 3‑D Secure*. Такая аутентификация предназначена для обеспечения безопасности проведения оплаты с использованием карт через интернет. Подробная информация об этой процедуре представлена в разделе [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md). - *Дополнение информации о платеже*. Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md). 3. Принять от платёжной платформы оповещение о результате проверки. Схема проведения проверки в базовом случае — без выполнения дополнительных процедур — представлена далее. ![](images/ru_gate_account_verification.svg) 1. Пользователь на стороне веб-сервиса вводит реквизиты платёжного инструмента. 2. От веб-сервиса к платёжной платформе передаётся запрос на проверку действительности платёжного инструмента. 3. Запрос на проверку действительности поступает в платёжную платформу. 4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему. 7. Выполняется проверка действительности платёжного инструмента. 8. К платёжной платформе направляется уведомление о результате проверки. 9. От платёжной платформы к веб-сервису направляется оповещение о результате проверки. Далее приведена информация о формате запросов на проверку действительности платёжных карт и о формате оповещений с результатами проверки. Информацию о возможных статусах проверки действительности можно найти [в соответствующей статье](ru_platform_account_verification_model.md). ## Формат запросов {#section_t11_mfk_1jb .section} При формировании запросов на проверку действительности платёжных карт необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - если проверка по номеру карты — [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification); - если проверка по токену, ассоциированному с картой, — [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта мерчанта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — используемый IP-адрес; - `id` — идентификатор пользователя в рамках проекта мерчанта; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа, равная нулю; - `currency` — валюта платежа в формате ISO-4217 alpha-3. 3. В запросе должны содержаться сведения о платёжной карте пользователя: - при передаче реквизитов карты в явном виде — следующие данные в объекте `card`: - `pan` — номер карты; - `year` — год окончания срока действия карты; - `month` — месяц окончания срока действия карты; - `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта \(это имя должно указываться в соответствии с написанием на карте, а исключить его из числа обязательных параметров можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\); - `cvv` — код проверки подлинности карты \(в соответствии с указанным на карте\);при проведении MO/TO оплат данный параметр необязателен, подробнее — в разделе [Проведение оплат MO/TO](ru_Gate_moto.md); - при передаче токена — токен, полученный от Ecommpay, и код проверки подлинности карты в параметрах `token` и `cvv`\(при проведении MO/TO оплат последний параметр необязателен, подробнее — в разделе [Проведение оплат MO/TO](ru_Gate_moto.md)\). 4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. **Прим.:** Сумма платежа должна быть равна нулю. Таким образом, корректный запрос для проверки действительности платёжной карты пользователя должен содержать идентификаторы проекта и платежа, подпись, сведения о платёжной карте пользователя, IP-адрес пользователя, валюту и сумму платежа. ``` { "general":{ "project_id":874, "payment_id":"15538406111", "signature":"1wR1YgD5PxxTIJfQ==" }, "customer":{ "ip_address":"185.123.193.224", "id":"customer_10" }, "payment":{ "amount":0, "currency":"USD" }, //при передаче реквизитов карты в явном виде: "card":{ "pan":"4314220000000056", "year":2021, "month":9, "card_holder":"John Smith", "cvv":"123" }, //при передаче токена, ассоциированного с картой: "token":"f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654", "cvv":"123" //при необходимости зарегистрировать повторяемую оплату: "recurring":{ "register":true } } ``` ## Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах проверки платёжной карты на действительность используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере содержится информация о том, что в рамках проекта `874` карта `431422******0056` пользователя `customer_10` действительна — может использоваться при проведении платежей — и зарегистрирована для проведения повторяемых оплат. ```language-json { "project_id":874, "payment":{ "id":"15538406111", "type":"account_verification", "status":"success", "date":"2019-09-10T13:45:59+0000", "method":"card", "sum":{ "amount":0, "currency":"EUR" }, "description":"Добавить карту" }, "account":{ "number":"431422******0056", "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f", "type":"visa", "card_holder":"JOHN SMITH", "id":8861226, "expiry_month":"09", "expiry_year":"2021" }, "customer":{ "id":"customer_10" }, "recurring":{ "id":10505, "currency":"EUR", "valid_thru":"2022-09-30T00:00:00+0000" }, "operation":{ "id":4314220000000056, "type":"account verification", "status":"success", "date":"2019-09-10T13:45:59+0000", "created_date":"2019-09-10T13:45:57+0000", "request_id":"5cb898347e62b2c1-52dac6c8c", "sum_initial":{ "amount":0, "currency":"EUR" }, "sum_converted":{ "amount":0, "currency":"EUR" }, "provider":{ "id":120, "payment_id":"306449667", "date":"2019-09-10T13:45:59+0000", "auth_code":"188591", "endpoint_id":120 }, "code":"0", "message":"Success" }, "signature":"P9g0U+eF2QWs2A==" } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении проверки действительности. Проведение платежа отклонено платёжной системой без объяснения причины. ```language-json { "project_id":874, "payment":{ "id":"15538406111", "type":"account_verification", "status":"decline", "date":"2019-09-16T06:06:53+0000", "method":"card", "sum":{ "amount":0, "currency":"EUR" }, "description":"Добавить карту" }, "account":{ "number":"431422******0056", "type":"visa", "card_holder":"JOHN SMITH", "expiry_month":"09", "expiry_year":"2021" }, "customer":{ "id":"customer_10" }, "operation":{ "id":4314220000000056, "type":"account verification", "status":"decline", "date":"2019-09-16T06:06:53+0000", "created_date":"2019-09-16T06:06:47+0000", "request_id":"9120271eb02-83e0e70fc0a0a3c1b4d", "sum_initial":{ "amount":0, "currency":"EUR" }, "sum_converted":{ "amount":0, "currency":"EUR" }, "provider":{ "id":120, "payment_id":"308822001", "date":"2019-09-16T06:06:49+0000", "auth_code":"", "endpoint_id":120 }, "code":"10100", "message":"Declined by external provider" }, "signature":"P9g0U+eaZ9EeNiWiaQWs2A==" } ``` **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Вспомогательные процедуры {#ru_gate_procedures} статьи о вспомогательных процедурах, которые могут быть обязательны при проведении отдельных платежей через Gate В этом разделе представлена информация о различных процедурах, которые могут быть необходимы при проведении отдельных платежей. - [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md) — об основных вариантах аутентификации пользователей с применением протокола 3‑D Secure 2 для обеспечения безопасности платежей. - [Аутентификация 3‑D Secure на стороне мерчанта](ru_gate_merchant_3ds.md)— о дополнительном варианте аутентификации пользователей с применением протокола 3‑D Secure на стороне веб-сервиса мерчанта. - [Аутентификация по инициативе мерчанта](ru_gate_payment_merch_auth.md)— о процедуре дополнительной аутентификации пользователей, которая может применяться как альтернатива аутентификации 3‑D Secure и выполняется по запросу со стороны мерчанта. - [Проверка Address Verification Service](ru_Gate_avs.md)— о процедуре проверки почтовых индексов и адресов пользователей для обеспечения безопасности платежей с использованием карт American Express, Mastercard и Visa. - [Проверка имён пользователей с помощью сервиса Verification of Payee](ru_verification_of_payee.md)— о процедуре проверки имён пользователей при инициировании ими получения средств для обеспечения соответствия банковских переводов с использованием платёжной схемы SEPA постановлению Европейского союза Instant Payments Regulation. - [Дополнение информации о платеже](ru_Gate_Clarification.md)— о процедуре предоставления дополнительных данных, которые могут запрашиваться платёжными системами в отдельных случаях. - [Конвертация валют](ru_Gate_Conversion.md)— о проведении платежей с применением разных валют для пользователя и мерчанта и встроенной в этот процесс конвертацией. - **[Аутентификация 3‑D Secure](ru_gate_payment_3ds.md)** статья об основных вариантах аутентификации пользователей с применением протокола 3‑D Secure при проведении через Gate карточных платежей, с использованием платформы Ecommpay - **[Аутентификация 3‑D Secure на стороне мерчанта](ru_gate_merchant_3ds.md)** статья о дополнительном варианте аутентификации пользователей с применением протокола 3‑D Secure при проведении через Gate карточных платежей, с использованием сторонних решений по инициативам мерчантов - **[Аутентификация по инициативе мерчанта](ru_gate_payment_merch_auth.md)** статья об аутентификации пользователей по запросам мерчантов, которая может применяться для дополнительной защиты и в качестве альтернативы аутентификации 3‑D Secure при проведении платежей через Gate - **[Проверка Address Verification Service](ru_Gate_avs.md)** статья о процедуре проверки почтовых индексов и адресов пользователей при проведении через Gate платежей с использованием карт American Express, Mastercard и Visa - **[Проверка имён пользователей с помощью сервиса Verification of Payee](ru_verification_of_payee.md)** статья о процедуре проверки имён пользователей при инициировании выплат через Gate на банковские счета с использованием платёжной схемы SEPA - **[Дополнение информации о платеже](ru_Gate_Clarification.md)** статья о процедуре предоставления дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Gate - **[Конвертация валют](ru_Gate_Conversion.md)** статья о порядке проведения через Gate платежей с применением разных валют и встроенной в этот процесс конвертацией **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Аутентификация 3‑D Secure {#ru_gate_payment_3ds} статья об основных вариантах аутентификации пользователей с применением протокола 3‑D Secure при проведении через Gate карточных платежей, с использованием платформы Ecommpay **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) ## Общая информация {#ru_gate_payment_3ds_overview} ### Обзор {#section_jg3_pjk_rvb .section} Аутентификация пользователей с использованием протокола 3‑D Secure \(Three-Domain Secure\) предназначена для защиты от мошенничества при проведении онлайн-платежей с использованием платёжных карт. Она может выполняться с применением различных способов проверки подлинности пользователей: например, через указание пользователем одноразового проверочного кода \(One Time PIN, OTP\), через распознавание лица пользователя, с помощью проверки отпечатка пальца пользователя на его мобильном устройстве или даже без каких-либо действий со стороны пользователя, на основе имеющейся информации о нём, его устройстве и инициированном платеже. При этом в разных случаях со стороны эмитентов могут поддерживаться различные способы проверки. **Прим.:** В настоящее время как со стороны платёжных систем American Express, Mastercard и Visa, так и со стороны Ecommpay поддерживается вторая версия протокола — 3‑D Secure 2. И представленная в этой статье информация относится к данной версии протокола. В аутентификации 3‑D Secure задействуются три домена: - *Домен эквайера*. В рамках работы с платёжной платформой Ecommpay к нему относятся веб-сервисы мерчантов, платёжная платформа и связанный с ней 3DS-сервер. - *Домен совместимости*. К нему относятся серверы каталогов \(Directory Servers, DS\) международных платёжных систем. - *Домен эмитента*. К нему относятся серверы управления доступом \(Access Control Servers, ACS\) эмитентов, а также страницы аутентификации \(ACS-страницы\), открываемые при обращениях к этим серверам. Между этими доменами осуществляется обмен сообщениями, необходимыми для аутентификации пользователей. К таким сообщениям могут относиться запросы на аутентификацию \(Authentication Request Message, AReq\) и ответы на них \(Authentication Response Message, ARes\), а также запросы на подтверждение личности пользователя \(Challenge Request, CReq\) и ответы с информацией о результатах такого подтверждения \(Challenge Response, CRes\). При работе с аутентификацией 3‑D Secure следует учитывать, что информация о возможности аутентификации держателей карт хранится на серверах управления доступом, и эту информацию в случае с каждой картой можно получить только после отправки запроса на проведение платежа. Также со стороны веб-сервиса и платёжной платформы невозможно отслеживать действия пользователей на страницах аутентификации — доступно лишь получение информации о результатах аутентификации. ### Варианты аутентификации {#section_sb4_qjy_svb .section} При работе с протоколом 3‑D Secure могут применяться два варианта аутентификации: - Аутентификация с подтверждением пользователем своей личности \(*challenge flow*\). В этом случае подтверждение личности пользователя выполняется, например, с использованием одноразового кода или биометрических данных, если такая возможность поддерживается эмитентом. - Аутентификация без участия пользователя \(*frictionless flow*\). В этом случае личность пользователя подтверждается исходя из информации, которой располагает эмитент. ![](images/3ds2_flow.svg) Со стороны мерчанта выбирать варианты аутентификации нельзя — можно лишь указывать предпочтения по такому выбору для конкретных платежей, но итоговое решение каждый раз принимается на стороне эмитента.Также, помимо указания предпочтений, в запросах на проведение платежей можно передавать ряд других необязательных параметров, применение которых может повышать вероятность выбора варианта аутентификации frictionless flow и, как следствие, способствовать повышению проходимости и улучшению пользовательского опыта. Информация о таких параметрах представлена [далее](ru_gate_payment_3ds.md). ### Особенности {#ru_gate_payment_3ds_special_aspects} #### Область применения {#section_ufm_mps_kdc .section} Выполнение аутентификации 3‑D Secure, как правило, обязательно для платежей с прямым использованием платёжных карт. Это связано с требованиями второй директивы о платёжных услугах \(Payment Services Directive 2, PSD2\), включающими в себя необходимость выполнения строгой аутентификации пользователя \(Strong Customer Authentication, SCA\) при проведении таких платежей. К платежам, на которые не распространяются требования PSD2 к строгой аутентификации, относятся: - Оплаты с использованием платёжных карт, выпущенных за пределами Европейской экономической зоны. - Оплаты с использованием анонимных предоплаченных платёжных карт, например с использованием подарочной карты или виртуальной карты с предоплаченной стоимостью. - Оплаты категории Mail Order/Telephone Order \(MO/TO\). - Оплаты, инициируемые мерчантом \(Merchant-initiated transactions, MIT\), к которым в платёжной платформе Ecommpay относятся регулярные оплаты и автооплаты \(с типом платежа `recurring`\), а также операции по изменению суммы предварительной блокировки \(с типом операции `incremental`\). - Оплаты с использованием большинства альтернативных платёжных методов. В платёжной платформе Ecommpay поддерживается определение таких платежей, и аутентификация для них не выполняется. #### Допустимые исключения {#section_oks_mps_kdc .section} Среди тех платежей, на которые распространяются базовые требования к строгой аутентификации, директива PSD2 допускает наличие исключений \(SCA Exemptions\), при которых аутентификация может не выполняться по решениям эмитентов. Такими исключениями могут выступать платежи следующих категорий: - Платежи на незначительные суммы \(Low value\) — оплаты на суммы до 25 фунтов стерлингов \(в пределах Великобритании\) или 30 евро \(в пределах Европейской экономической зоны\), в случаях, когда с момента последней успешной аутентификации было проведено не более пяти платежей и общая сумма этих платежей не превышает 85 фунтов стерлингов или 100 евро соответственно. - Платежи с низким уровнем риска \(Transaction Risk Analysis\) — оплаты, проводимые эквайером, уровень мошенничества в платёжном трафике которого соответствует порогам PSD2. - Платежи доверенным мерчантам \(Trusted beneficiaries\) — оплаты в пользу тех мерчантов, которые по инициативе или с согласия держателя карты занесены в список доверенных. - Безопасные корпоративные платежи \(Corporate payments\) — оплаты, инициируемые юридическими лицами с использованием процессов и протоколов, обеспечивающих высокий уровень защиты от мошенничества \(таких как Electronic Banking Internet Communication Standard, EBICS\). В платёжной платформе Ecommpay поддерживается работа с исключениями для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa в рамках первых двух категорий \(на незначительные суммы и с низким уровнем риска\). #### Работа с допустимыми исключениями {#section_tfb_nps_kdc .section} Применение исключений может уменьшать количество действий со стороны пользователей и положительно влиять на проходимость платежей. При этом ответственность за возможные мошеннические действия для таких платежей возлагается на мерчанта. Если эта возможность подключена, то применение соответствующих исключений инициируется автоматически, кроме тех случаев, когда со стороны мерчанта указано предпочтительное выполнение аутентификации. При этом следует учитывать, что в случае проведения платежа, который относится к исключениям, итоговое решение о необходимости аутентификации так же остаётся за эмитентом. С его стороны может быть направлен „мягкий отказ“ \(soft decline\), означающий необходимость выполнения аутентификации. В случае получения такого отказа аутентификация для искомого платежа выполняется стандартно, без применения исключений, и, как правило, в варианте *challenge flow*. Кроме того, исключения не могут применяться при регистрации повторяемых оплат — в таких случаях выполнение аутентификации 3‑D Secure обязательно. Информация о применённых исключениях передаётся в оповещениях о результатах платежей и отображается в карточках платежей в интерфейсе Dashboard. По вопросам, касающимся подключения возможности применения исключений, можно обращаться к курирующему менеджеру Ecommpay. ### Пользовательские сценарии {#ru_gate_payment_3ds_user_scenarios} С учётом допустимости разных вариантов аутентификации 3‑D Secure, а также с учётом других факторов \(в частности, способов оформления страниц ожидания и используемого платёжного интерфейса\), процесс аутентификации может выглядеть для пользователей по-разному. В случае с вариантом challenge flow и с перенаправлением пользователя к ACS-странице на стороне эмитента для ввода одноразового кода сценарий может соответствовать следующим иллюстрациям. ![](images/ecommpay/ru_gate_3ds_interface_1.svg "Страница указания платёжных данных") ![](images/ecommpay/ru_gate_3ds_interface_2.svg "Страница ожидания") ![](images/ecommpay/ru_gate_3ds_interface_3.svg "Страница ACS") ![](images/ecommpay/ru_gate_3ds_interface_4.svg "Страница ожидания") ![](images/ecommpay/ru_gate_3ds_interface_5.svg "Итоговая страница") В случае с вариантом frictionless flow из такого сценария исключаются шаги с перенаправлением пользователя к ACS-странице и последующим возвращением к веб-сервису. ## Схемы работы {#ru_gate_payment_3ds_workflow} ### Общая информация {#section_fct_smf_tvb .section} Как и пользовательские сценарии, схемы работы веб-сервиса и других сторон при выполнении аутентификации 3‑D Secure могут различаться. При этом существенными факторами для веб-сервиса выступают внешние решения относительно необходимости сбора дополнительных сведений об устройстве пользователя и относительно варианта аутентификации — каждое из этих решений может вызывать необходимость выполнения соответствующей процедуры дополнительно к базовым действиям по проведению искомого платежа. |Варианты работы|без сбора сведений|со сбором сведений| |---------------|------------------|------------------| |frictionless flow|- базовые действия |- базовые действия - сбор сведений | |challenge flow|- базовые действия - перенаправление |- базовые действия - сбор сведений - перенаправление | Самостоятельно выбирать какие-либо из этих сценариев со стороны мерчантов нельзя. Но можно влиять на решения других сторон — через передачу рекомендуемых параметров и указание предпочтений по варианту аутентификации \(frictionless flow или challenge flow\) для конкретных платежей. ### Общая схема работы {#section_j4f_3wk_3jc .section} Общую схему проведения оплаты с аутентификацией 3‑D Secure можно представить следующим образом. ![](images/ru_gate_3ds_workflow.svg) 1. В платёжной платформе выполняется обработка исходного запроса на проведение платежа и выявляется необходимость аутентификации 3‑D Secure \(согласно действующим требованиям к проведению платежей\). 2. От платёжной платформы к 3DS‑серверу, связанному с платёжной платформой, передаётся запрос на проверку возможности аутентификации для указанной карты и необходимости сбора сведений об устройстве пользователя. 3. На стороне 3DS‑сервера проверяются возможность аутентификации и необходимость сбора сведений. 4. От 3DS‑сервера к платёжной платформе направляется ответ с информацией о возможности аутентификации и о необходимости сбора дополнительных сведений об устройстве пользователя. 5. В платёжной платформе обрабатывается полученная информация. При этом в случае, если сбор дополнительных сведений не требуется, инициируется выполнение следующего шага \(шага 6\), а в случае необходимости сбора дополнительных сведений выполняются следующие шаги: 1. От платёжной платформы к веб-сервису направляется оповещение с данными для сбора дополнительных сведений об устройстве пользователя. 2. От веб-сервиса к платёжной платформе направляется синхронный ответ о приёме данных. 3. На стороне веб-сервиса выполняется код для сбора дополнительных сведений об устройстве пользователя, с открытием служебного объекта iframe. 4. На устройстве пользователя автоматически выполняются сбор необходимых сведений и их отправка к серверу управления доступом \(Access Control Server\) эмитента. 5. От эмитента к веб-сервису передаётся уведомление о приёме данных. 6. От веб-сервиса на заданный URL Ecommpay передаётся запрос на аутентификацию пользователя. 7. Запрос поступает в платёжную платформу. 8. В платёжной платформе выполняется приём запроса с проверкой его корректности. 9. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. От платёжной платформы к 3DS-серверу передаётся запрос на аутентификацию пользователя. 7. Запрос передаётся от 3DS‑сервера к серверу каталогов международной платёжной системы \(Directory Server\). 8. Запрос передаётся от сервера каталогов к серверу управления доступом. 9. На стороне эмитента выполняется аутентификация пользователя. При этом в случае выбора эмитентом варианта аутентификации frictionless flow от сервера управления доступом к платёжной платформе \(через сервер каталогов и 3DS-сервер\) передаётся информация о результате аутентификации, а в случае выбора варианта аутентификации challenge flow выполняются следующие шаги: 1. От сервера управления доступом к серверу каталогов и далее к 3DS-серверу и платёжной платформе передаются данные для перенаправления пользователя на страницу аутентификации \(ACS URL\). 2. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления. 3. Со стороны веб-сервиса выполняется перенаправление пользователя на страницу аутентификации. 4. Пользователю отображается страница аутентификации, после чего он осуществляет требуемые действия. 5. На стороне эмитента выполняется аутентификация пользователя. 6. От сервера управления доступом к серверу каталогов и далее к 3DS-серверу передаётся информация о результате проверки. 7. От 3DS‑сервера к серверу каталогов и далее к серверу управления доступом передаётся ответ о приёме этой информации. 8. Со стороны сервера управления доступом выполняется перенаправление пользователя к веб-сервису с передачей данных о результате аутентификации. 9. Пользователю отображается страница ожидания веб-сервиса. 10. От веб-сервиса на заданный URL Ecommpay передаётся запрос на продолжение проведения платежа с учётом результата аутентификации. 11. Запрос поступает в платёжную платформу. 12. В платёжной платформе выполняется приём запроса с проверкой его корректности. 13. От платёжной платформы к веб-сервису направляется синхронный ответ с информацией о получении запроса и его корректности, после чего обрабатывается информация о результате аутентификации и осуществляется переход к оставшимся действиям для проведения искомого платежа. Информация о форматах оповещений и запросов, используемых в рамках этой схемы, приведена [далее](ru_gate_payment_3ds.md) в этой статье; общая информация о работе с Gate API — в статье [Организация взаимодействия](ru_gate_interaction_organisation.md). Также стоит учитывать, что в различных случаях эта схема может дополняться другими процедурами и действиями, не касающимися непосредственно аутентификации и описанными в соответствующих статьях настоящей документации. ### Сбор сведений об устройстве пользователя {#section_xw2_jwk_3jc .section} В случаях, когда для эмитента актуален сбор дополнительных сведений об устройстве пользователя, к веб-сервису от платформы отправляется соответствующее [оповещение](ru_gate_payment_3ds.md#section_jnw_q24_cjb). При получении такого оповещения необходимо: 1. Проверить целостность данных путём сличения расчётной подписи с представленной в оповещении. 2. Подтвердить приём оповещения, отправив положительный синхронный ответ \(200 OK\) к платформе. 3. Открыть в клиентской части веб-сервиса элемент iframe для сбора сведений об устройстве пользователя с использованием данных из оповещения \([подробнее](ru_gate_payment_3ds.md#fig_zly_wq2_bjb)\). 4. Принять [уведомление о приёме сведений](ru_gate_payment_3ds.md#section_d4n_vky_svb) от сервера управления доступом \(ACS\) эмитента. 5. Отправить [запрос на аутентификацию](ru_gate_payment_3ds.md#section_o1k_yky_svb) в платёжную платформу. **Прим.:** Частоту применения этой процедуры по запросам эмитентов можно минимизировать, если обеспечивать со стороны веб-сервиса предварительные сбор и отправку информации об устройствах пользователей \([подробнее](ru_gate_payment_3ds.md)\). ### Перенаправление пользователя к странице аутентификации {#section_ms4_hcm_3jc .section} В случаях, когда для эмитента актуален вариант аутентификации challenge flow с перенаправлением пользователя к ACS-странице, к веб-сервису от платформы отправляется соответствующее [оповещение](ru_gate_payment_3ds.md#section_drq_xq1_1jb). При получении такого оповещения необходимо: 1. Проверить целостность данных путём сличения расчётной подписи с представленной в оповещении. 2. Подтвердить приём оповещения, отправив положительный синхронный ответ \(200 OK\) к платформе. 3. Перенаправить пользователя на страницу аутентификации с использованием данных из оповещения \([подробнее](ru_gate_payment_3ds.md#fig_k3g_qr2_bjb)\) и с соблюдением ограничения в 30 секунд с момента приёма оповещения о необходимости перенаправления. 4. Принять [уведомление о результате аутентификации](ru_gate_payment_3ds.md#section_cjg_rss_njb) от эмитента. 5. Отправить [запрос на продолжение проведения платежа](ru_gate_payment_3ds.md#section_gps_1fc_t3b) с учётом результата аутентификации с соблюдением ограничения в 30 минут с момента приёма оповещения о необходимости перенаправления. 6. Если используется возможность каскадного проведения платежей \([подробнее](ru_gate_cascading.md)\) и повторно получено оповещение о необходимости перенаправления пользователя \(со значением `true` для параметра `cascading_with_redirect`\): 1. Повторить шаги 1–2 этой процедуры, с проверкой и подтверждением приёма оповещения. 2. Отобразить пользователю сообщение об ошибке при предыдущей попытке аутентификации. 3. Получить согласие пользователя на повторную аутентификацию. 4. Повторить шаги 3–5 этой процедуры. **Прим.:** Частоту применения этой процедуры по запросам эмитентов можно минимизировать, если обеспечивать со стороны веб-сервиса предварительные сбор и отправку рекомендуемых сведений \([подробнее](ru_gate_payment_3ds.md#section_f32_tfl_lxb)\). ## Работа со сведениями об устройстве пользователя {#ru_gate_payment_3ds_collecting_data} Чтобы улучшать пользовательский опыт и проходимость платежей, уместно минимизировать число действий в рамках аутентификации пользователей. Для этого в запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, полезно передавать ряд таких параметров, которые помогают уменьшать вероятность применения процедур со сбором дополнительных сведений об устройствах пользователей и с перенаправлениями пользователей к страницам аутентификации. В число таких параметров, полный перечень которых представлен [далее](ru_gate_payment_3ds.md), наряду со сведениями о пользователе и платеже входят следующие сведения об устройстве и браузере пользователя: - Сведения об устройстве, определяемые на клиентской стороне веб-сервиса: - `accept_header` — значение HTTP-заголовка Accept; - `accept_language_header` — значение параметра Accept-Language, которое указывает предпочтения в языке локализации; - `browser` — значение HTTP-заголовка User-Agent; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. - Сведения об устройстве, получаемые из запроса от используемого браузера к веб-сервису: - `color_depth` — глубина цвета используемого устройства, в битах на пиксель; - `java_enabled` — индикатор поддержки сценариев Java в используемом браузере; - `js_enabled` — индикатор поддержки сценариев JavaScript в используемом браузере; - `language` — код языка, выбранного для работы в используемом браузере; - `screen_res` — разрешение экрана используемого устройства, в пикселях и с символом `x` в качестве разделителя \(например, `1920x1080`\); - `timezone_name` — название часового пояса, который актуален для используемого браузера \(например, `Australia/Adelaide`\); - `timezone_offset` — разница между временем для используемого браузера и UTC, в минутах \(например, `570`\). ``` {#codeblock_ihr_13v_33c .language-json} "customer": { "ip_address": "188.113.253.90", "browser": "Mozilla/5.0 (Linux; Android 14; SM-A155F Build/UP1A.231005.007; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/138.0.7204.67 Mobile Safari/537.36", "screen_res": "1920x1080", "language": "en_US", "accept_header": "*/*", "accept_language_header": "en-GB,en;q=0.8,fr;q=0.3", "color_depth": 24, "java_enabled": false, "js_enabled": true, "timezone_offset": "570" } ``` Со стороны веб-сервиса сбор и использование таких сведений об устройстве и браузере пользователя можно организовать следующим образом. 1. Определить сведения об устройстве пользователя в клиентской части веб-сервиса. ``` {#codeblock_cvf_lz5_33c .language-javascript} function collectClientData() { return { // разрешение экрана устройства screen_res: `${screen.width}x${screen.height}`, // код языка, выбранного в браузере language: navigator.language, // глубина цвета браузера color_depth: screen.colorDepth, // индикатор поддержки сценариев Java в браузере java_enabled: navigator.javaEnabled(), // индикатор поддержки сценариев JavaScript в браузере js_enabled: true, // разница между временем для браузера и UTC timezone_offset: new Date().getTimezoneOffset().toString(), }; } ``` 2. Отправить собранные сведения из клиентской части веб-сервиса в серверную. ``` {#codeblock_lnp_lz5_33c .language-javascript} async function sendClientDataToServer(endpoint = '/api/collect-client-data') { try { const clientData = collectClientData(); const response = await fetch(endpoint, { method: 'POST', headers: { 'Content-Type': 'application/json', 'Accept': '*/*' }, body: JSON.stringify(clientData) }); const result = await response.json(); return result; } catch (error) { console.error('Ошибка отправки данных:', error); throw error; } } ``` 3. Дополнить эти сведения полученными из запроса от браузера пользователя к веб-сервису и использовать их наряду с другими актуальными параметрами для формирования и отправки запроса на проведение искомого платежа. ``` {#codeblock_n4t_kz5_33c .language-php} interface CustomerData { public function getIpAddress(): ?string; public function getAcceptHeader(): ?string; public function getAcceptLanguageHeader(): ?string; public function getScreenRes(): ?string; public function getBrowser(): ?string; public function getLanguage(): ?string; public function getColorDepth(): ?int; public function getJavaEnabled(): ?bool; public function getJsEnabled(): ?bool; public function getTimezoneOffset(): ?string; } interface CardData { public function getPan(); public function getYear(); public function getMonth(); public function getCardHolder(); public function getCvv(); } interface PaymentData { public function getPaymentId(): string; public function getAmount(): int; public function getCurrency(): string; public function getCardData(): CardData; public function getCustomerData(): CustomerData; } interface HttpClient { public function sendRequest(array $request): bool; } interface Signer { public function sign(array $params): string; } final class PaymentController { public function __construct( private Signer $signer, private HttpClient $httpClient, private int $projectId, ) {} public function processPayment(PaymentData $paymentData): void { $paymentRequest = [ 'general' => [ 'project_id' => $this->projectId, 'payment_id' => $paymentData->getPaymentId(), ], 'customer' => $this->prepareCustomerData($paymentData->getCustomerData()), 'payment' => [ 'amount' => $paymentData->getAmount(), 'currency' => $paymentData->getCurrency(), ], 'card' => [ 'pan' => $paymentData->getCardData()->getPan(), 'year' => $paymentData->getCardData()->getYear(), 'month' => $paymentData->getCardData()->getMonth(), 'card_holder' => $paymentData->getCardData()->getCardHolder(), 'cvv' => $paymentData->getCardData()->getCvv(), ], ]; $paymentRequest['general']['signature'] = $this->signer->sign($paymentRequest); $this->httpClient->sendRequest($paymentRequest); } private function prepareCustomerData(CustomerData $customerData): array { return array_filter([ 'ip_address' => $customerData->getIpAddress(), 'browser' => $customerData->getBrowser(), 'screen_res' => $customerData->getScreenRes(), 'language' => $customerData->getLanguage(), 'accept_header' => $customerData->getAcceptHeader(), 'accept_language_header' => $customerData->getAcceptLanguageHeader(), 'color_depth' => $customerData->getColorDepth(), 'java_enabled' => $customerData->getJavaEnabled(), 'js_enabled' => $customerData->getJsEnabled(), 'timezone_offset' => $customerData->getTimezoneOffset(), ]); } } ``` ``` {#codeblock_lbz_g1v_33c} package main import "encoding/json" // CustomerData interface type CustomerData interface { GetIpAddress() *string GetAcceptHeader() *string GetAcceptLanguageHeader() *string GetScreenRes() *string GetBrowser() *string GetLanguage() *string GetColorDepth() *int GetJavaEnabled() *bool GetJsEnabled() *bool GetTimezoneOffset() *string } // CardData interface type CardData interface { GetPan() interface{} GetYear() interface{} GetMonth() interface{} GetCardHolder() interface{} GetCvv() interface{} } // PaymentData interface type PaymentData interface { GetPaymentId() string GetAmount() int GetCurrency() string GetCardData() CardData GetCustomerData() CustomerData } // HttpClient interface type HttpClient interface { SendRequest(request map[string]interface{}) bool } // Signer interface type Signer interface { Sign(params map[string]interface{}) string } // PaymentController struct type PaymentController struct { signer Signer httpClient HttpClient projectId int } // NewPaymentController constructor func NewPaymentController(signer Signer, httpClient HttpClient, projectId int) *PaymentController { return &PaymentController{ signer: signer, httpClient: httpClient, projectId: projectId, } } // ProcessPayment processes the payment func (pc *PaymentController) ProcessPayment(paymentData PaymentData) { cardData := paymentData.GetCardData() paymentRequest := map[string]interface{}{ "general": map[string]interface{}{ "project_id": pc.projectId, "payment_id": paymentData.GetPaymentId(), }, "customer": pc.prepareCustomerData(paymentData.GetCustomerData()), "payment": map[string]interface{}{ "amount": paymentData.GetAmount(), "currency": paymentData.GetCurrency(), }, "card": map[string]interface{}{ "pan": cardData.GetPan(), "year": cardData.GetYear(), "month": cardData.GetMonth(), "card_holder": cardData.GetCardHolder(), "cvv": cardData.GetCvv(), }, } // Add signature general := paymentRequest["general"].(map[string]interface{}) general["signature"] = pc.signer.Sign(paymentRequest) // Send request pc.httpClient.SendRequest(paymentRequest) } // prepareCustomerData filters and prepares customer data func (pc *PaymentController) prepareCustomerData(customerData CustomerData) map[string]interface{} { result := make(map[string]interface{}) if v := customerData.GetIpAddress(); v != nil { result["ip_address"] = *v } if v := customerData.GetBrowser(); v != nil { result["browser"] = *v } if v := customerData.GetScreenRes(); v != nil { result["screen_res"] = *v } if v := customerData.GetLanguage(); v != nil { result["language"] = *v } if v := customerData.GetAcceptHeader(); v != nil { result["accept_header"] = *v } if v := customerData.GetAcceptLanguageHeader(); v != nil { result["accept_language_header"] = *v } if v := customerData.GetColorDepth(); v != nil { result["color_depth"] = *v } if v := customerData.GetJavaEnabled(); v != nil { result["java_enabled"] = *v } if v := customerData.GetJsEnabled(); v != nil { result["js_enabled"] = *v } if v := customerData.GetTimezoneOffset(); v != nil { result["timezone_offset"] = *v } return result } ``` **Прим.:** Следует учитывать, что представленные здесь примеры кода для работы со сведениями об устройстве пользователя носят информативный характер и не допускают их использования в прямом виде \(«как есть»\) без проверки и доработки на соответствие всем актуальным требованиям на стороне веб-сервиса, включая [требования PCI DSS](ru_faq_integration.md#fig_fgk_rgs_4nb). ## Формат запросов на проведение платежей {#ru_gate_payment_3ds_formats_request} ### Общая информация {#section_pj3_4gr_k3c .section} Общий формат запросов на проведение платежей с возможностью выполнения аутентификации 3‑D Secure должен соответствовать описанному в статье [Организация взаимодействия](ru_gate_interaction_organisation.md). При этом для каждого запроса может быть актуальным свой набор параметров: - в любом случае должны использоваться параметры, обязательные для соответствующего типа платежа \(подробнее — в статьях о типах платежей\), и параметры, перечисленные далее как [обязательные](ru_gate_payment_3ds.md#section_ppq_gfl_lxb) для выполнения аутентификации 3‑D Secure; - в случаях, когда предпочтительны сценарии без сбора дополнительных сведений об устройстве пользователя и без перенаправления пользователя к странице аутентификации \(с вариантом frictionless flow\), желательно передавать максимальное число параметров, которые перечислены далее как [рекомендуемые](ru_gate_payment_3ds.md#section_f32_tfl_lxb) для выполнения аутентификации 3‑D Secure; - дополнительно могут использоваться любые другие параметры из числа допустимых для конкретного типа платежа. ### Обязательные параметры {#section_ppq_gfl_lxb .section} В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, вместе с обязательными для соответствующего типа платежа параметрами необходимо передавать следующие объекты и параметры. |Параметр|Описание| | |--------|--------|--| |`acs_return_url` object |Объект с адресами веб-сервиса, используемыми для аутентификации|1| |`return_url` string |Адрес веб-сервиса для перенаправления пользователя после аутентификации|1-11| |`3ds_notification_url` string |Адрес веб-сервиса для получения уведомления о том, что данные приняты сервером управления доступом|1-21| |`customer` object |Объект со сведениями о пользователе|2| |`ip_address` string |IP-адрес пользователя, актуальный для инициируемого платежа|2-12| |`screen_res` string |Разрешение экрана используемого устройства, в пикселях и с символом `x` в качестве разделителя \(например, `1920x1080`\)|2-22| |`email` string |Адрес электронной почты пользователя|2-32| |`phone` string |Номер телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей|2-42| |`card` object |Объект со сведениями о платёжной карте пользователя|3| |`card_holder` string |Имя держателя карты, в соответствии с указанным на карте|3-13| ``` {#codeblock_gmn_gbx_x3c .language-json} { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "customer": { // сведения о пользователе "ip_address": "248.121.176.220", // IP-адрес пользователя "id": "customer_12", "screen_res": "1920x1080", // разрешение экрана используемого устройства "phone": "44991234567", // номер телефона пользователя "email": "john_smith@email.com" // адрес электронной почты пользователя }, "payment": { "amount": 400000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "decline": "https://example.com/decline" }, "card": { "pan": "4314220000000056", "year": 2025, "month": 8, "card_holder": "JOHN SMITH", // имя держателя карты "cvv": "123" }, "acs_return_url": { // сведения об адресах веб-сервиса "return_url": "https://3DS_result_url", // адрес для перенаправления пользователя после аутентификации "3ds_notification_url": "https://3DS_result_url" // адрес для получения уведомления о принятии данных } ``` ### Рекомендуемые параметры {#section_f32_tfl_lxb .section} В запросах на проведение платежей, для которых применима аутентификация 3‑D Secure, рекомендуется передавать ряд необязательных параметров, указание которых может повышать вероятность выбора эмитентами варианта аутентификации frictionless flow, без участия пользователя, а также отказ от сбора дополнительных сведений об устройстве пользователя. Со стороны веб-сервиса можно передавать как полный, так и неполный набор таких параметров, с учётом наличия соответствующей информации. К базовому минимуму параметров, влияющих на решения эмитентов о варианте аутентификации и сборе сведений, при этом можно отнести платёжный адрес пользователя и сведения о его устройстве и браузере. |Параметр|Описание| | |--------|--------|--| |`customer` object |Объект со сведениями о пользователе|2| |`accept_header` string |Значение HTTP-заголовка Accept в соответствии с полученным со стороны используемого браузера|2-12| |`accept_language_header` string |Значение параметра Accept-Language в соответствии с полученным со стороны используемого браузера. Представляет собой строку с перечислением кодов и уровней приоритетности \(q-values\) использования языков \(например, `en-GB,en;q=0.8,fr;q=0.3`\)|2-192| |`browser` string |Значение HTTP-заголовка User-Agent в соответствии с полученным со стороны используемого браузера|2-22| |`color_depth` integer |Глубина цвета используемого устройства, в битах на пиксель|2-32| |`java_enabled` boolean |Индикатор поддержки сценариев Java в используемом браузере|2-42| |`js_enabled` boolean |Индикатор поддержки сценариев JavaScript в используемом браузере|2-52| |`language` string |Код языка, выбранного для работы в используемом браузере|2-62| |`timezone_name` string |Название часового пояса, который актуален для используемого браузера \(например, `Australia/Adelaide`\)|2-82| |`timezone_offset` string |Разница между временем для используемого браузера и UTC, в минутах \(например, `570`\)|2-92| |`address_match` boolean |Указатель совпадения расчётного адреса пользователя с адресом доставки, указанным в объекте `shipping`, который может принимать оно из следующих значений: - `true` — адреса совпадают - `false` — адреса не совпадают |2-102| |`home_phone` string |Номер домашнего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44991234567`\)|2-112| |`work_phone` string |Номер рабочего телефона пользователя, в виде последовательности от четырёх до двадцати четырёх цифр без использования разделителей \(например, `44997654321`\)|2-122| |`account` object |Объект со сведениями об учётной записи пользователя на стороне веб-сервиса мерчанта|2-132| |`additional` string |Дополнительная информация об учётной записи пользователя, например её идентификатор, в произвольном формате с использованием до 64 символов|2-13-12-13| |`activity_day` integer |Количество попыток проведения оплаты за последние 24 часа, в виде числа от 0 до 999 \(`999`\)|2-13-22-13| |`activity_year` integer |Количество попыток проведения оплаты за последние 365 дней, в виде числа от 0 до 999 \(`999`\)|2-13-32-13| |`age_indicator` string |Индикатор давности учётной записи, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(при инициировании платежа без аутентификации пользователя\) - `02` — при нулевой давности \(при создании учётной записи для инициирования платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |2-13-42-13| |`auth_data` string |Дополнительная информация об аутентификации на стороне веб-сервиса, в произвольном формате с использованием не более 255 символов|2-13-52-13| |`auth_method` string |Указатель способа последней аутентификации пользователя на стороне веб-сервиса, который может принимать одно из следующих значений:- `01` — отсутствие аутентификации - `02` — аутентификация с использованием данных, сохранённых на стороне веб-сервиса мерчанта - `03` — аутентификация с использованием технологии Federated Identity \(например, Google Account или Facebook\) - `04` — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online \(FIDO\) |2-13-62-13| |`auth_time` string |Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате `ДД-ММ-ГГГГчч:мм`|2-13-72-13| |`date` string |Дата создания учётной записи в формате `ДД-ММ-ГГГГ`|2-13-82-13| |`change_date` string |Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате `ДД-ММ-ГГГГ`|2-13-92-13| |`change_indicator` string |Индикатор давности изменений в учётной записи, за исключением изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при нулевой давности \(при изменениях в день проведения платежа\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней |2-13-102-13| |`pass_change_date` string |Дата последнего изменения или сброса пароля в формате `ДД-ММ-ГГГГ`|2-13-112-13| |`pass_change_indicator` string |Индикатор давности последнего изменения или сброса пароля, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(пароль не был изменён или сброшен\) - `02` — при нулевой давности \(пароль был изменён или сброшен в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |2-13-122-13| |`payment_age` string |Дата добавления реквизитов платёжного инструмента в формате `ДД-ММ-ГГГГ`|2-13-132-13| |`payment_age_indicator` string |Индикатор давности сохранения данных платёжного инструмента, используемых для проведения платежа, который может принимать одно из следующих значений:- `01` — при невозможности оценить давность \(платёж проводится без аутентификации в учётной записи\) - `02` — при нулевой давности \(данные карты сохранены в день проведения платежа\) - `03` — при давности менее 30 дней - `04` — при давности от 30 до 60 дней - `05` — при давности более 60 дней |2-13-142-13| |`provision_attempts` integer |Количество попыток сохранения реквизитов для новых платёжных инструментов за последние 24 часа, от 0 до 999 \(`999`\)|2-13-152-13| |`purchase_number` integer |Количество покупок, совершённых через учётную запись за последние 6 месяцев, от 0 до 9999 \(`9999`\)|2-13-162-13| |`suspicious_activity` string |Индикатор подозрительной активности, который может принимать одно из следующих значений:- `01` — без выявления подозрительной активности - `02` — с выявлением подозрительной активности |2-13-172-13| |`billing` object |Объект со сведениями о расчётном адресе пользователя|2-162| |`address` string |Название улицы в расчётном адресе пользователя|2-16-12-16| |`city` string |Название города в расчётном адресе пользователя|2-16-22-16| |`country` string |Код страны в расчётном адресе пользователя в формате ISO 3166-1 alpha-2|2-16-32-16| |`postal` string |Почтовый индекс в расчётном адресе пользователя|2-16-42-16| |`region_code` string |Внутренний код региона \(штата, провинции или иной территориальной области\) в расчётном адресе пользователя. Представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. При указании значения этого параметра также необходимо указать значение параметра `country` этого же объекта |2-16-52-16| |`shipping` object |Объект со сведениями о доставке|2-172| |`address` string |Название улицы и номер дома в адресе доставки \(с обозначением корпуса или строения, где это актуально\), в виде строки длиной не более 150 символов|2-17-12-17| |`address_usage` string |Дата первого использования указанного адреса, в формате `ДД-ММ-ГГГГ`|2-17-22-17| |`address_usage_indicator` string |Индикатор давности первого использования указанного адреса доставки, который может принимать одно из следующих значений:- `01` — при нулевой давности \(указанный адрес используется впервые\) - `02` — при давности менее 30 дней - `03` — при давности от 30 до 60 дней - `04` — при давности более 60 дней |2-17-32-17| |`city` string |Название города \(или иного населённого пункта\) в адресе доставки, в виде строки длиной не более 50 символов|2-17-42-17| |`country` string |Код страны в адресе доставки в формате ISO 3166-1 alpha-2 \(например, [GB](references/ru/countries/GB.md)\)|2-17-52-17| |`delivery_email` string |Адрес электронной почты в случае доставки на этот адрес, который может содержать не более 255 символов|2-17-62-17| |`delivery_time` string |Индикатор срока доставки, который может принимать одно из следующих значений:- `01` — в день покупки в электронном виде - `02` — в день покупки в материальном виде - `03` — на следующий день после покупки - `04` — позднее чем на следующий день после покупки |2-17-72-17| |`name_indicator` string |Индикатор совпадения имени пользователя с именем получателя доставки, который может принимать одно из следующих значений:- `01` — имена совпадают - `02` — имена не совпадают |2-17-82-17| |`postal` string |Почтовый индекс в адресе доставки, представляет собой строку длиной не более 16 символов|2-17-92-17| |`region_code` string |Внутренний код региона в адресе доставки, представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса, например `DOR` для графства Дорсет. При указании значения этого параметра также необходимо указать значение параметра `country` этого же объекта |2-17-102-17| |`type` string |Указатель варианта доставки, который может принимать одно из следующих значений:- `01` — доставка на расчётный адрес держателя карты - `02` — доставка на другой подтверждённый адрес - `03` — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым - `04` — доставка в магазин мерчанта - `05` — доставка в электронном виде - `06` — отсутствие доставки - `07` — другой вариант |2-17-112-17| |`mpi_result` object |Объект со сведениями о предыдущей аутентификации пользователя|2-182| |`acs_operation_id` string |Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре `acs_operation_id` оповещения о результате проведения предыдущего платежа|2-18-12-18| |`authentication_flow` string |Указатель варианта предыдущего прохождения аутентификации пользователем, полученный в параметре `authentication_flow` оповещения о результате проведения предыдущего платежа, который может принимать оно из следующих значений: - `01` — frictionless flow - `02` — challenge flow |2-18-22-18| |`authentication_timestamp` string |Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре `mpi_timestamp` оповещения о результате проведения предыдущего платежа|2-18-32-18| |`payment` object |Объект со сведениями о платеже|3| |`challenge_indicator` string |Индикатор предпочтения по использованию варианта аутентификации challenge flow, который может принимать одно из следующих значений:- `01` — без предпочтений - `02` — предпочтительно не использовать - `03` — предпочтительно использовать - `04` — обязательно использовать - `05` — не использовать, анализ рисков выполнен на стороне мерчанта - `06` — не использовать, применить сценарий Data Only - `07` — не использовать, Strong Customer Authentication уже выполнена иным способом - `08` — не использовать, мерчант включен в список доверенных для этого пользователя - `09` — обязательно использовать, предпочтительно предложить пользователю добавить мерчанта в список доверенных |3-13| |`challenge_window` string |Индикатор размера окна для открытия страницы аутентификации, который может принимать одно из следующих значений:- `01` — 250 x 400 пикселей - `02` — 390 x 400 пикселей - `03` — 500 x 600 пикселей - `04` — 600 x 400 пикселей - `05` — полноэкранный режим |3-23| |`preorder_date` string |Планируемая дата поступления товара или услуги в формате `ДД-ММ-ГГГГ`|3-33| |`preorder_purchase` string |Индикатор предварительного заказа, который может принимать одно из следующих значений:- `01` — не является предварительным заказом - `02` — является предварительным заказом |3-43| |`reorder` string |Индикатор первичной или повторной покупки данного товара или услуги пользователем, который может принимать одно из следующих значений:- `01` — первичная покупка - `02` — повторная покупка |3-53| |`gift_card` object |Объект со сведениями о покупке предоплаченных или подарочных карт|3-63| |`amount` integer |Сумма покупки, в дробных единицах валюты, указанной в параметре `currency` этого же объекта|3-6-13-6| |`currency` string |Код валюты для суммы покупки в формате ISO 4217 alpha-3 \(например, [GBP](references/ru/currencies/GBP.md)\)|3-6-23-6| |`count` integer |Количество приобретаемых предоплаченных или подарочных карт|3-6-33-6| ## Форматы промежуточных сообщений {#ru_gate_payment_3ds_formats_messages} ### Формат оповещения о необходимости сбора дополнительных сведений {#section_jnw_q24_cjb .section} Для сбора эмитентом дополнительных сведений об устройстве пользователя при выполнении аутентификации необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `iframe` объекта `threeds2` — чтобы сформировать служебный элемент iframe на странице веб-сервиса. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `iframe` включаются сведения, которые необходимо использовать следующим образом: адрес из параметра `url` — в атрибуте `action` используемой формы в клиентской части веб-сервиса, а данные из других параметров — в тегах `input` этой же формы. ``` {#codeblock_on5_hfm_njc .language-json} { "threeds2":{ "iframe":{ "url":"https://example.com", "params":{ "3DSMethodData":"eyAidGhyZWVNrkthelJSUFQwaWZYMCUzQ", "threeDSMethodData":"eyAidGhjNjMGQ4YWU4LTA2u0wyWmtObGRdwR" } } } } ``` ``` {#codeblock_pn5_hfm_njc .language-xml}
``` ### Формат уведомления о приёме дополнительных сведений {#section_d4n_vky_svb .section} Для уведомлений о приёме дополнительных сведений об устройствах пользователей используются форматы эмитентов. Такие уведомления передаются от серверов управления доступом \(ACS\) эмитентов на адреса веб-сервисов, указанные в запросах на проведение платежей \(в параметре `3ds_notification_url`\). С вопросами о работе с такими уведомлениями можно обращаться к специалистам технической поддержки Ecommpay. ``` {#codeblock_qn5_hfm_njc .language-xml} threeDSMethodData:eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImRiNmFjM2UwLWI5ZWQtNWQ3NS04MDAwLTAwMDAwMDAwMTA0MiJ9 threeDSServerTransID=3abd37b3-afa6-53cf-8000-000000006455 ``` ### Формат запроса на инициирование аутентификации {#section_o1k_yky_svb .section} Для инициирования аутентификации, когда это актуально после сбора дополнительных сведений об устройстве пользователя, каждый раз должен использоваться POST-запрос к конечной точке [/v2/payment/card/3ds\_check\_iframe](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-check-iframe). В каждом таком запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор используемого проекта; - `payment_id` — идентификатор проводимого платежа; - `signature` — подпись к данным запроса, составленная после указания целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\). - `threeds_completion_indicator` — индикатор своевременного получения уведомления о приёме сведений — со значением `true`, если такое [уведомление](ru_gate_payment_3ds.md#section_d4n_vky_svb) получено в течение 10 секунд с момента открытия элемента iframe для сбора дополнительных сведений об устройстве пользователя, или `false`, если уведомление получено позже. Таким образом, корректный запрос на инициирование аутентификации 3‑D Secure после сбора дополнительных сведений об устройстве пользователя должен содержать идентификаторы проекта и платежа, индикатор получения уведомления о сборе сведений в допустимый период и подпись. ``` {#codeblock_kzn_2hx_x3c .language-json} { "general":{ "project_id":42, "payment_id":"456789", "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "threeds_completion_indicator":true } ``` ### Формат оповещения о необходимости перенаправления {#section_drq_xq1_1jb .section} Для перенаправления пользователей от веб-сервиса мерчанта к страницам аутентификации \(ACS URL\) эмитентов необходимо принимать промежуточные оповещения от платёжной платформы и использовать информацию из них, включённую в объект `redirect` объекта `threeds2`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect` включаются сведения, которые необходимо использовать следующим образом: адрес из параметра `url` — в атрибуте `action` используемой формы в клиентской части веб-сервиса, а данные из других параметров — в тегах `input` этой же формы. ``` {#codeblock_xvv_cfx_x3c .language-json} { "threeds2":{ "redirect":{ "url":"https://example.com/ACS", "params":{ "creq":"ewogICAiYWNzVHJhbnNJCIDAtMDAwMDAwMDAwN2Q5Ip9", "threeDSSessionData":"240000549" } } } } ``` ``` {#codeblock_yvv_cfx_x3c .language-xml} 3D Secure Processing

3D Secure Processing

Please wait.. Verified by VISA
``` ### Формат уведомления о результате аутентификации {#section_cjg_rss_njb .section} Для уведомлений со сведениями о результатах аутентификации используются форматы эмитентов, при этом в состав таких уведомлений должен включаться параметр `cres`, который должен передаваться далее в платформу со стороны веб-сервиса в запросах на продолжение платежа. ``` {#codeblock_rn5_hfm_njc} **cres**=ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMiLAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1N0YXR1cyIgOiAiWSIKfQ&threeDSSessionData=240000554 ``` ``` {#codeblock_sn5_hfm_njc} **cres**=ewogICAiYWNzUmVmZXJlbmNlTnVtYmVyIiA6ICJBQ1NFbXUyIiwKICAgImFjc1RyYW5zSUQiIDog%0D%0AIjAwMDAwMDAwLTAwMDUtNWE1YS04MDAwLTAxNmQzZTI2ZWU2YyIsCiAgICJtZXNzYWdlVHlwZSIg%0D%0AOiAiQ1JlcyIsCiAgICJtZXNzYWdlVmVyc2lvbiIgOiAiMi4xLjAiLAogICAidGhyZWVEU1NlcnZl%0D%0AclRyYW5zSUQiIDogIjhiMjM0Y2ZmLTkzNjAtNTc5Yy04MDAwLTAwMDAwMDAwMDlhNiIsCiAgICJ0%0D%0AcmFuc1N0YXR1cyIgOiAiTiIKfQ==&threeDSSessionData=240000622 ``` ### Формат запроса на продолжение платежа {#section_gps_1fc_t3b .section} Для продолжения проведения платежа, когда это актуально после аутентификации с вариантом challenge flow, каждый раз должен использоваться POST-запрос к конечной точке [/v2/payment/card/3ds\_result](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-3ds-result). В каждом таком запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор используемого проекта; - `payment_id` — идентификатор проводимого платежа; - `signature` — подпись к данным запроса, составленная после указания целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\). - `cres` — сведения о результате аутентификации 3‑D Secure, полученные [в соответствующем уведомлении](ru_gate_payment_3ds.md#section_cjg_rss_njb). Таким образом, корректный запрос на продолжение проведения платежа с учётом результата аутентификации 3‑D Secure должен содержать идентификаторы проекта и платежа, сведения о результате аутентификации от эмитента и подпись. ``` {#codeblock_tn5_hfm_njc .language-json} { "general": { "project_id": 42, "payment_id": "456789", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "cres": "ewogICJhY3NUcmFuc0lEIiA6ICJkYTIyNjY0Mi1hYzJhLTQ0N2ItYWFiYS1lNWI2Nzc2MjdmZmMi LAogICJtZXNzYWdlVHlwZSIgOiAiQ1JlcyIsCiAgIm1lc3NhZ2VWZXJzaW9uIiA6ICIyLjEuMCIsCiAgInRocmVlR FNTZXJ2ZXJUcmFuc0lEIiA6ICI5ZjE3OWM0My02NjA2LTU3YWUtODAwMC0wMDAwMDAwMDA3ZGQiLAogICJ0cmFuc1 N0YXR1cyIgOiAiWSIKfQ" // Сведения о результате аутентификации } ``` ## Формат оповещений о результатах платежей {#ru_gate_payment_3ds_formats_callback} Информация о результатах платежей, при проведении которых выполнялась аутентификация 3‑D Secure, передаётся от платёжной платформы к веб-сервису в оповещениях типового формата, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом в объекте `mpi_result` таких оповещений дополнительно могут передаваться следующие параметры: - `mpi_operation_id` — идентификатор операции на стороне 3DS‑сервера; - `ds_operation_id` — идентификатор операции на стороне cервера каталогов международной платёжной системы; - `acs_operation_id` — идентификатор операции на стороне сервера управления доступом эмитента; - `mpi_timestamp` — дата и время аутентификации; - `cardholder_info` — информация об аутентификации, которую рекомендуется отобразить пользователю при уведомлении о результате проведения платежа; - `authentication_flow` — указатель использованного варианта аутентификации: `01` — frictionless flow, `02` — challenge flow. В случаях, когда аутентификация не выполнялась в связи с применением одного из допустимых [исключений](ru_gate_payment_3ds.md#section_oks_mps_kdc), в объекте `operation` таких оповещений дополнительно может передаваться параметр `non_3ds_reason` со значением `tra, lve` \(для платежей с низким уровнем риска \(Transaction Risk Analysis\) или на незначительные суммы \(Low value\)\). По умолчанию такие дополнительные параметры не включаются в состав итоговых оповещений. Однако их можно включить в используемую структуру через обращение к специалистам технической поддержки Ecommpay. ```language-json { "account":{ "number":"431422******0056", "token":"f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654", "type":"visa", "card_holder":"JOHN SMITH", "id":45678, "expiry_month":"08", "expiry_year":"2025" }, "customer":{ "id":"customer_12", "phone":"44991234567" }, "payment":{ "date":"2019-01-11T13:02:42+0000", "id":"456789", "method":"card", "status":"success", "sum":{ "amount":400000, "currency":"USD" }, "type":"purchase", "description":"" }, "project_id":42, "operation":{ "id":969000002636, "type":"sale", "status":"success", "date":"2019-01-11T13:02:42+0000", "created_date":"2019-01-11T13:01:45+0000", "request_id":"c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial":{ "amount":400000, "currency":"USD" }, "sum_converted":{ "amount":400000, "currency":"USD" }, "provider":{ "id":408, "payment_id":"330157196", "date":"2019-01-11T13:02:32+0000", "auth_code":"", "endpoint_id":"612266625" }, "mpi_result":{ "mpi_operation_id":"", // Идентификатор операции на стороне 3DS‑сервера "ds_operation_id":"", // Идентификатор операции на стороне сервера каталогов международной платёжной системы "acs_operation_id":"", // Идентификатор операции на стороне сервера управления доступом эмитента "mpi_timestamp":"YYYYMMDDHHMM", // Дата и время выполнения аутентификации "cardholder_info":"Additional authentication is needed for this transaction", // Информация об аутентификации, которую рекомендуется отобразить пользователю "authentication_flow":"02" // Информация о варианте аутентификации }, "code":"0", "message":"Success", "eci":"07" }, "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` --- # Аутентификация 3‑D Secure на стороне мерчанта {#ru_gate_merchant_3ds} статья о дополнительном варианте аутентификации пользователей с применением протокола 3‑D Secure при проведении через Gate карточных платежей, с использованием сторонних решений по инициативам мерчантов ## Общие сведения {#section_ypx_yw4_qmb .section} Прохождение аутентификации 3‑D Secure пользователем может осуществляться как на стороне платёжной платформы Ecommpay, так и на стороне мерчанта. В случае если аутентификация проходит на стороне мерчанта для совершения оплаты в платёжную платформу необходимо передать результат прохождения проверки и повторная проверка на стороне платёжной платформы происходить не будет. Чтобы подключить эту возможность, необходимо обратиться к специалистам технической поддержки \([support@ecommpay.com](mailto:support@ecommpay.com)\). ## Передача результата аутентификации 3‑D Secure {#section_ils_qjq_qmb .section} После подключения возможности в запросах к платёжной платформе Ecommpay можно передавать информацию о результате прохождения аутентификации 3‑D Secure. Такая информация передаётся в объекте `authentication_data` в запросе на проведение разовой оплаты, в том числе по токену или по сохраненным данным карты, или на проверку действительности карты. Данные передаются в следующих параметрах: |Параметр|Тип|Обязательность|Описание| |--------|---|--------------|--------| |`cavv`|string|Обязателен, если `authentication_status=Y или A`|Значение проверки подлинности держателя карты в Base64-кодировке 20-байтового значения| |`ds_operation_id`|string|Обязателен, если `threeds_version=3ds_2`|Уникальный идентификатор операции, зарегистрированный сервером каталогов \(Directory Server\)| |`eci`|string|Обязателен, если `authentication_status=Y или A`|Индикатор, отображающий результат 3‑D Secure аутентификации пользователя, подробнее в разделе [Индикаторы ECI](ru_ECI_codes.md)| |`threeds_version`|string|Необязателен|Индикатор выполнения аутентификации 3‑D Secure:- `3ds_2` - `non_3ds` | |`threeds_full_version`|string|Необязателен|Номер версии протокола 3‑D Secure, например 2.3.1| |`xid`|string|Обязателен|Идентификатор транзакции, полученный в результате обработки аутентификации, в Base64-кодировке 20-байтового значения| |`authentication_status`|string|Обязателен, кроме случаев если `enrollement_status=N или U`|Статус аутентификации держателя карты. Возможные значения: - `Y` — держатель карты успешно прошел аутентификацию у эмитента карты, - `A` — была предпринята попытка аутентификации держателя карты, - `U` — эмитент карты был недоступен во время аутентификации. | |`authentication_status_reason_code`|string|Необязателен|Код причины, по которой аутентификации присвоен соответствующий статус| |`authentication_flow`|string|Необязателен|Указатель варианта прохождения аутентификации пользователем. Возможные значения:- `Frictionless`, - `Challenge` | ``` { "general":{ "project_id":200, "payment_id":"id_15514400636", "signature":"PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQ...==" }, "card":{ "pan":"some_string", "year":2025, "month":12, "card_holder":"JOHN JOHNSON", "cvv":"some_string" }, "customer":{ "id":"123", "ip_address":"217.1.1.0" }, "payment":{ "amount":1000, "currency":"EUR" }, "authentication_data":{ "cavv":"kEMQyiH/ASySYhP1hAErbWFO+mih", "ds_operation_id":"f780a79f-a5e1-44d8-bfa3-5f89432fdb79", "eci":"06", "threeds_version":"3ds_2", "xid":"MDAwMDAwNzYxODEwMDAwMDE3MDE=", "authentication_status":"A", "authentication_flow":"Frictionless", "threeds_full_version":"2.3.1", "authentication_status_reason_code":"01" } } ``` ## Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md) - [Работа с подписью к данным](ru_platform_signature.md) - [Проведение платежей](ru_platform_payment_model.md) - [Работа с информацией об операциях](ru_platform_payment_info_codes.md) - [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md) **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) --- # Аутентификация по инициативе мерчанта {#ru_gate_payment_merch_auth} статья об аутентификации пользователей по запросам мерчантов, которая может применяться для дополнительной защиты и в качестве альтернативы аутентификации 3‑D Secure при проведении платежей через Gate ## Общая информация {#section_zq3_2q2_zhb .section} Аутентификация пользователя со стороны провайдера по инициативе мерчанта предназначена для обеспечения дополнительной безопасности проведения интернет-оплат с использованием платёжных карт. Такая аутентификация используется, как правило, в качестве замены аутентификации 3‑D Secure или для её дополнения. Это может быть уместно в тех случаях, когда аутентификация 3‑D Secure недостаточно надёжна, например из-за поддержки эмитентами устаревших методов подтверждения пользователем своей личности. При аутентификации по инициативе мерчанта подтверждение личности пользователя осуществляется путём ввода пользователем проверочного кода, полученного в информации о списании. Информацию о списании пользователь получает в SMS-сообщении или банковской выписке. В платёжной платформе аутентификация по инициативе мерчанта поддерживается только для некоторых провайдеров, а для её подключения необходимо настроить проект мерчанта. Для этого следует обратиться в службу технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). Со стороны веб-сервиса для аутентификации по инициативе мерчанта необходимо: - принять оповещение с информацией об изменении статуса платежа на `awaiting merchant auth`; - получить согласие пользователя; - отправить запрос на аутентификацию; - принять проверочный код от пользователя; - отправить проверочный код в запросе к платёжной платформе. Более подробные сведения о работе с аутентификацией по инициативе мерчанта представлены далее. ## Схема работы {#section_pjt_5jb_v3b .section} Аутентификация по инициативе мерчанта может выполняться при проведении одностадийных и двухстадийных оплат с применением платёжных карт. *Информирование* о необходимости такой аутентификации осуществляется через оповещения, на которые, как и обычно, необходимо направлять ответы об их приёме. Эти оповещения содержат информацию об изменении статуса платежа на `awaiting merchant auth`. Со стороны веб-сервиса для *реагирования* на такие оповещения необходимо: *получить* от пользователя согласие на аутентификацию, *отправить* в платёжную платформу запрос на аутентификацию, *получить* от пользователя проверочный код и *отправить* этот код в платёжную платформу в запросе на продолжение платежа. Время ожидания запроса на продолжение проведения платежа с учётом результата аутентификации не ограничено, но общее время проведения платежа не должно превышать максимально допустимое, установленное на стороне провайдера. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. После того как в платёжную платформу поступает запрос с проверочным кодом, проведение платежа продолжается дальше. ![](images/ru_gate_scheme_merchant_auth.svg) 1. В платёжной платформе выполняется обработка платежа. 2. От платёжной платформы к веб-сервису направляется оповещение о необходимости аутентификации. 3. Выполняется перенаправление пользователя на страницу с информацией об аутентификации. 4. Пользователь соглашается с выполнением аутентификации. 5. От веб-сервиса на заданный URL Ecommpay передаётся запрос на инициирование аутентификации. 6. Запрос поступает в платёжную платформу. 7. В платёжной платформе выполняется обработка запроса. 8. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 9. От платёжной платформы к сервису провайдера направляется запрос на инициирование аутентификации. 10. На стороне провайдера выполняется обработка запроса и отправка проверочного кода пользователю. 11. Пользователь вводит проверочный код. 12. От веб-сервиса на заданный URL Ecommpay передаётся запрос на завершение аутентификации и продолжение проведения платежа. 13. Запрос поступает в платёжную платформу. 14. В платёжной платформе выполняется обработка запроса. 15. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 16. От платёжной платформы к сервису провайдера направляется запрос на завершение аутентификации и продолжение проведения платежа. Информация о формате запросов и оповещений приведена далее; общая информация о работе с API — в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). ## Формат оповещения о необходимости аутентификации {#section_gzw_wbd_w3b .section} Информация о необходимости аутентификации передаётся в оповещении стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В данном случае оповещение свидетельствует о том, что платёж и операция переведены в статус `awaiting merchant auth` до получения запроса на продолжение платежа. ```language-json { "project_id":42, "payment":{ "id":"456789", "type":"purchase", "status":"awaiting merchant auth", // Статус платежа "date":"2019-02-20T15:33:11+0000", "method":"card", "sum":{ "amount":400000, "currency":"USD" }, "description":"" }, "account":{ "number":"431422******0056", "type":"visa", "card_holder":"JOHN SMITH", "expiry_month":"08", "expiry_year":"2025" }, "customer":{ "id":"customer_12" }, "operation":{ "id":171200003265, "type":"sale", "status":"awaiting merchant auth", // Статус операции "date":"2019-02-20T15:33:11+0000", "created_date":"2019-02-20T15:33:02+0000", "request_id":"617c2626f873151a1cf5873ceb7cca0ade292ee-646d...ec", "sum_initial":{ "amount":400000, "currency":"USD" }, "sum_converted":{ "amount":400000, "currency":"USD" }, "provider":{ "id":4, "payment_id":"3301571985", "auth_code":"", "endpoint_id":4 }, "code":"9999", "message":"Awaiting processing", "eci":"06" }, "signature":"v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` ## Формат запроса на инициирование аутентификации {#section_r2m_h52_zhb .section} Для инициирования аутентификации по инициативе мерчанта необходимо отправить в платёжную платформу POST-запрос к конечной точке [/v2/payment/card/merchant\_auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-merchant-auth). В этом запросе должен использоваться объект `general`, содержащий основные идентификационные сведения и указатель типа запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `type` — указатель типа запроса, необходимо передать значение `start`; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, указатель типа запроса \(`start`\) и подпись. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "type": "start", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } } ``` ## Формат запроса на продолжение проведения платежа {#section_mm2_xv1_v3b .section} Для продолжения проведения платежа с учётом результата аутентификации необходимо отправить в платёжную платформу POST-запрос к конечной точке [/v2/payment/card/merchant\_auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-merchant-auth). В этом запросе должны использоваться следующие объекты и параметры: 1. `general` — объект, содержащий основные идентификационные сведения и указатель типа запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `type` — указатель типа запроса, необходимо передать значение `finish`; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); 2. `confirmation_code` — проверочный код, полученный от пользователя. Таким образом, корректный вопрос должен содержать идентификаторы проекта и платежа, указатель типа запроса \(`finish`\), подпись и проверочный код. ```language-json { "general": { "project_id": 42, "payment_id": "456789", "type": "start", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "confirmation_code": "835" } ``` **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) --- # Проверка Address Verification Service {#ru_Gate_avs .concept} статья о процедуре проверки почтовых индексов и адресов пользователей при проведении через Gate платежей с использованием карт American Express, Mastercard и Visa ## Общая информация {#section_ofb_dcx_ydb .section} При использовании карт платёжных систем Visa и Mastercard проверка AVS обязательна для операций, совершаемых на территории Великобритании, и опциональна для США, Австралии, Канады и Новой Зеландии. При использовании карт платёжной системы American Express такая проверка обязательна для США и Канады и опциональна для других стран.Поэтому при отправке запроса на проведение платежа может потребоваться введение пользователем дополнительных обязательных параметров: почтовые индекс `avs_post_code` и адрес `avs_street_address` пользователя. Отправка данных параметров возможна с помощью запроса на уточнение параметров, подробную информацию см. в [Дополнение информации о платеже](ru_Gate_Clarification.md). В случае если полученные данные не проходят проверку, не переданы или не заполнены, вы получите соответствующие код и сообщение об отказе в проведении платежа. Результат проверки AVS передается в оповещении в параметре `avs_result`. Существует две схемы работы с учетом AVS: передача полей AVS в каждом запросе или передача полей AVS в запросе на уточнение параметров, если в настройках проекта включен AVS для страны-эмитента карты. **Прим.:** Требование по предоставлению полей AVS сохраняется даже если платеж осуществляется по токену или сохраненной карте. ## Результаты проверки {#section_gq3_n12_pfb .section} Возможные коды параметра avs\_result и соответствующие значения и описания приведены в таблицах ниже. |Код|Значение|Описание| |---|--------|--------| |W, Z|Частичное совпадение|Почтовый индекс пользователя совпадает, адрес — нет| |A|Частичное совпадение|Адрес пользователя совпадает, почтовый индекс — нет| |X, Y|Полное совпадение|Адрес и почтовый индекс пользователя совпадают| |N|Полное несовпадение|Ни адрес, ни почтовый индекс не совпадают| |S, U|Информация недоступна|Для текущего аккаунта информация об адресе недоступна, либо банк-эмитент не поддерживает AVS| |R|Система недоступна|Система авторизации банка-эмитента на данный момент недоступна. Можно повторить попытку| |Visa|A, N, R, U, Y, Z| |MasterCard|A, N, R, S, U, W, X, Y, Z| |American Express|A, N, R, S, U, Y, Z| **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) --- # Проверка имён пользователей с помощью сервиса Verification of Payee {#ru_verification_of_payee} статья о процедуре проверки имён пользователей при инициировании выплат через Gate на банковские счета с использованием платёжной схемы SEPA **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) ## Общая информация {#ru_verification_of_payee_overview} В соответствии с постановлением Европейского союза [Instant Payments Regulation \(IPR\)](https://www.ecb.europa.eu/paym/retail/instant_payments/html/instant_payments_regulation.en.html) для проведения банковских переводов с использованием платёжной схемы [SEPA](https://www.ecb.europa.eu/paym/retail/sepa/html/index.en.html) в единой зоне платежей в евро \(ЕЗПЕ\) имена получателей средств должны проходить проверку с помощью сервиса Verification of Payee. Это постановление актуально для тех случаев, когда отправитель и получатель средств зарегистрированы в странах — членах ЕЗПЕ. В рамках такой проверки написание имени получателя средств, представленное со стороны мерчанта, должно сравниваться с написанием, зафиксированным на стороне банка для владельца указанного счёта, и уже по итогам проверки со стороны мерчанта должно приниматься решение о допустимости перевода средств. При работе с платёжной платформой Ecommpay проверка с помощью сервиса Verification of Payee обеспечивается через взаимодействие с сервисным провайдером и может быть актуальна для отдельных платёжных методов, таких как [Выплаты на банковские счета в ЕЗПЕ \(SEPA\)](pm_bankpayout_sepa.md). В случае использования таких методов можно настраивать обработку результатов проверки на стороне веб-сервиса или на стороне платёжной платформы \(подробнее далее\). Также можно настраивать время, в течение которого информация о статусе проверки должна считаться действительной, а саму проверку можно не повторять в идентичных случаях \(с такими парами пользователей и счетов, для которых есть действительный результат\). По умолчанию это время составляет 10 суток. Подключение и настройка работы с процедурой Verification of Payee выполняются через курирующего менеджера Ecommpay, при этом использование проверок не влияет на расчёт комиссий за проведение платежей. С вопросами о возможностях и особенностях применения проверки Verification of Payee для конкретных платёжных методов можно обращаться к описаниям этих методов в настоящей документации и к специалистам технической поддержки Ecommpay. ## Варианты работы {#ru_verification_of_payee_workflow} Со стороны мерчанта в рамках каждого проекта взаимодействия с платформой можно выбирать и использовать один из допустимых вариантов работы с проверкой имён получателей средств. - В случае с обработкой результатов проверки на стороне платформы можно использовать один из предопределённых алгоритмоводобрения и отклонения операций, исходя из итогового статуса проверки. Такой вариант требует со стороны мерчанта лишь согласования подходящего алгоритма и позволяет учитывать результаты проверок через разбор итоговых оповещений о выполнении операций. - В случае с обработкой результатов проверки на стороне веб-сервиса можно использовать любые алгоритмы\(учитывая не только итоговый статус каждой проверки, но и, например, сумму инициируемой операции и показатели истории работы с конкретным пользователем\). Такой вариант требует со стороны мерчанта настройки и реализации соответствующих алгоритмов, а также организации дополнительных взаимодействий между веб-сервисом и платформой для каждой операции с процедурой проверки. Подключение любого из этих вариантов, как и переключения между ними, выполняются через курирующего менеджера Ecommpay.Подробнее процедура подключения и порядок работы с каждым из вариантов описаны далее, в соответствующих разделах настоящей статьи. ## Подключение и настройка {#ru_verification_of_payee_enable} Чтобы подключить и настроить функциональность проверки имён пользователей, со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpayактуальность подключения и вариант использования процедуры, а также необходимость изменения срока действия результатов проверки \(по умолчанию он составляет 10 суток\) и необходимость тестирования функциональности. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работы с использованием процедуры и сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении функциональности. ## Используемые статусы {#ru_verification_of_payee_statuses} При работе с платёжной платформой Ecommpay об итоговом состоянии каждой проверки Verification of Payee свидетельствует один из следующих статусов: - `MATCH` — фиксирует полное соответствие в написанииимени получателя средств, указанного в запросе, и имени, зафиксированного на стороне банка для владельца указанного счёта. - `CLOSE_MATCH` — фиксирует частичное соответствие в написанииимени получателя средств, указанного в запросе, и имени, зафиксированного на стороне банка для владельца указанного счёта. - `NO_MATCH` — фиксирует полное несоответствие в написанииимени получателя средств, указанного в запросе, и имени, зафиксированного на стороне банка для владельца указанного счёта. - `VERIFICATION_NOT_POSSIBLE` — фиксирует невозможность выполнения проверки из-за ошибок на стороне сервисного провайдера. - `VOP_ERROR` — фиксирует невозможность выполнения проверки из-за ошибок при взаимодействии платформы и сервиса провайдера. При этом интерпретация полного и частичного соответствия, как и полного несоответствия в написаниях имён обеспечивается в соответствии с постановлением IPR. Также можно отметить, что многие банки склонны отклонять операции в случаях со статусом проверки `VERIFICATION_NOT_POSSIBLE` даже при технической возможности выполнения таких операций на стороне платформы и низком уровне риска по другим критериям. ## Обработка на стороне платформы {#ru_verification_of_payee_platform} ### Алгоритмы {#section_glk_rld_w3c .section} В рамках варианта с обработкой результатов проверки Verification of Payee на стороне платёжной платформы Ecommpay допустимо выбрать и использовать один из следующих алгоритмов одобрения операций \(с их последующим выполнением, когда статус проверки соответствует одному из одобренных\). - Алгоритм 1 основан на следующих правилах: - статус `MATCH` указывает на возможность выполнения соответствующей операции; - статусы `CLOSE_MATCH`, `NO_MATCH`, `VERIFICATION_NOT_POSSIBLE` и `VOP_ERROR` указывают на невозможность выполнения соответствующей операции. - Алгоритм 2 основан на следующих правилах: - статусы `MATCH` и `CLOSE_MATCH` указывают на возможность выполнения соответствующей операции; - статусы `NO_MATCH`, `VERIFICATION_NOT_POSSIBLE` и `VOP_ERROR` указывают на невозможность выполнения соответствующей операции. - Алгоритм 3 основан на следующих правилах: - статусы `MATCH`, `CLOSE_MATCH` и `VERIFICATION_NOT_POSSIBLE` указывают на возможность выполнения соответствующей операции; - статусы `NO_MATCH` и `VOP_ERROR` указывают на невозможность выполнения соответствующей операции. - Алгоритм 4 основан на следующем правиле: все статусы, включая статус `NO_MATCH` и статусы с фиксацией невозможности проверки, указывают на возможность выполнения соответствующей операции. Кратко эти правила можно представить в виде таблицы. |Статус|Алгоритмы одобрения| |1|2|3|4| |------|-------------------| |--|--|--|--| |`MATCH`|+|+|+|+| |`CLOSE_MATCH`|–|+|+|+| |`NO_MATCH`|–|–|–|+| |`VERIFICATION_NOT_POSSIBLE`|–|–|+|+| |`VOP_ERROR`|–|–|–|+| ### Контроль результатов {#section_tyw_qld_w3c .section} Информацию о результате проверки Verification of Payee для любой из операций, выполняемой в рамках варианта с обработкой результатов на стороне платёжной платформы Ecommpay, можно получать через итоговое оповещение о выполнении этой операции. Для оповещений в таких случаях используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом информация об итоговом статусе проверки указывается в параметрах объекта `provider_extra_fields`, а в случаях с отклонением операций дополнительно можно ориентироваться на итоговые коды их состояния, среди которых могут быть коды, связанные с результатами проверки: - `20450` — при отклонении операции из-за того, что проверку не удалось выполнить\(для статуса `VERIFICATION_NOT_POSSIBLE` в алгоритмах 1–2 и статуса `VOP_ERROR` в алгоритмах 1–3\); - `20451` — при отклонении операции из-за того, что статус выполненной проверки не соответствует одобряемому\(для статуса `CLOSE_MATCH` в алгоритме 1 и статуса `NO_MATCH` в алгоритмах 1–3\). В следующем примере оповещение свидетельствует о том, что в рамках проекта `239` была проведена выплата в размере `10,00 EUR`. В параметре `vop_status` объекта `provider_extra_fields` данных из этого оповещения указывается статус проверки `CLOSE_MATCH`. ``` {#codeblock_jvs_lwq_q3c .language-json} { "provider_extra_fields": { "customer_name": "John Smit", "operation_id_in_ps": "TX55DE3DEFC161XT", "vop_status": "CLOSE_MATCH", "vop_message": "Reasons: NAME_MISMATCH; Details: The account details are a close match.; Matched: name: JOHN SMITH" }, "customer": { "id": "1" }, "account": { "number": "LV35HA******6833" }, "project_id": 239, "payment": { "id": "Test payment 02042026-111", "type": "payout", "status": "success", "date": "2026-04-02T11:12:47+0000", "method": "world", "sum": { "amount": 1000, "currency": "EUR" }, "description": "test payout" }, "operation": { "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1, "currency": "EUR" }, "code": "0", "message": "Success", "provider": { "id": 16711, "payment_id": "P21132ZU06", "auth_code": "", "date": "2026-04-02T11:11:51+0000" }, "id": 94413010223457, "type": "payout", "status": "success", "date": "2026-04-02T11:12:47+0000", "created_date": "2026-04-02T11:11:43+0000", "request_id": "7eee810762d6493a807f30094414" }, "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ==" } ``` В следующем примере оповещение свидетельствует о том, что выплата была отклонена в связи с полным несоответствием имён, о чём свидетельствует статус `NO_MATCH`. ``` {#codeblock_vtb_nwq_q3c .language-json} { "provider_extra_fields": { "vop_status": "NO_MATCH", "vop_message": "Reasons: NAME_MISMATCH, ACCOUNT_MISMATCH; Details: The account and name do not match." }, "customer": { "id": "1" }, "account": { "number": "LV35HA******6833" }, "project_id": 155543, "payment": { "id": "Test payment 02042026-115", "type": "payout", "status": "decline", "date": "2026-04-02T11:22:20+0000", "method": "world", "sum": { "amount": 1, "currency": "EUR" }, "description": "test payout" }, "operation": { "sum_initial": { "amount": 1, "currency": "EUR" }, "sum_converted": { "amount": 1, "currency": "EUR" }, "code": "20451", "message": "Payout or refund cannot be processed based on the Verification of Payee result", "provider": { "id": 16711, "payment_id": "", "auth_code": "" }, "id": 43116010187149, "type": "payout", "status": "decline", "date": "2026-04-02T11:22:21+0000", "created_date": "2026-04-02T11:22:18+0000", "request_id": "231221" }, "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ==" } ``` ## Обработка на стороне веб-сервиса {#ru_verification_of_payee_webservice} ### Схема работы {#section_zbr_tlz_r3c .section} В рамках варианта с обработкой результатов проверки Verification of Payee на стороне веб-сервиса необходимо организовать дополнительные взаимодействия между веб-сервисом и платформой для каждой операции с процедурой проверки. Это включает в себя ряд шагов между приёмом заявки от пользователя на получение средств и инициированием соответствующей операции в платформе: 1. Отправить запрос на проверку имени пользователя\(с требуемыми параметрами и подписью\) на рабочий URL Ecommpay. 2. Принять от платёжной платформы синхронный ответс информацией об инициировании проверки. 3. Спустя не менее чем 10 секунд отправить запрос на получение информации о результате проверки\(с требуемыми параметрами и подписью\) на рабочий URL Ecommpay. 4. Принять от платёжной платформы синхронный ответс информацией о статусе проверки. После такого взаимодействия в каждом случае на стороне веб-сервиса необходимо принять решение о допустимости операции\(в соответствии с реализованным внутренним алгоритмом\) и инициировать эту операцию в платформе либо уведомить пользователя об ошибке. Общая схема взаимодействий при проверке имени получателя средств в рамках выплаты или возврата выглядит следующим образом. ![](images/ru_vop_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует получение средств. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проверку имени пользователя через Gate. 3. Запрос на проверку имени пользователя поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется обработка запроса с проверкой его корректности и инициированием запрошенной проверки. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса, его обработке и инициировании проверки. 6. От платёжной платформы к сервису провайдера отправляется запрос на проверку имени пользователя. 7. В сервисе провайдера выполняется проверка имени пользователя. 8. От сервиса провайдера к платёжной платформе передаётся информация о результате проверки. 9. Спустя не менее чем 10 секунд после получения ответа об инициировании проверки от веб-сервиса на заданный URL Ecommpay передаётся запрос на получение информации о проверке через Gate. 10. Запрос на получение информации о проверке поступает в платёжную платформу Ecommpay. 11. В платёжной платформе выполняется обработка запроса с проверкой его корректности и поиском запрошенной информации. 12. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса, его корректности и информацией о статусе проверки. 13. На стороне веб-сервиса выполняются обработка полученной информации и последующие действия исходя из статуса проверки, с информированием пользователя о статусе запрошенной им операции по получению средств. Информация о форматах данных, используемых для запросов и ответов в рамках такого взаимодействия, представлена далее в этом разделе. ### Формат запроса на проверку имени пользователя {#section_idv_5lz_r3c .section} При формировании запросов на проверку имён пользователей необходимо учитывать следующее: 1. Для инициирования каждой проверки должен использоваться отдельный POST-запрос к конечной точке [/v2/verification-of-payee/create](https://api-developers.ecommpay.com/api-specification/verification-of-payee-service/post-v2-verification-of-payee-create). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись к запросу, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `account` — объект, содержащий сведения о банковском счёте получателя средств: - `customer_name` — полное имя или наименование владельца счёта; - `number` — номер счёта. ``` {#codeblock_dxp_wqx_jfc .language-json} { "general": { "project_id": 12345, "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "currency": "EUR" }, "account": { "customer_name": "John Doe", "number": "DOMESTIC_ACC_NUMBER_12345678" } } ``` ### Формат ответа об инициировании проверки {#section_g2b_vlz_r3c .section} Для ответов о результатах инициирования проверки имён пользователей используется типовой формат, описание которого представлено в статье [Организация взаимодействия](ru_gate_interaction_organisation.md). При этом: - если проверка была инициирована, в объекте `vop` передаются следующие параметры: - `id` — идентификатор проверки, присвоенный на стороне провайдера; - `status` — промежуточный статуспроверки со значением `processing`; - если проверка не была инициирована из-за ошибок на стороне провайдера или платформы, объект `vop` не используется. ``` {#codeblock_icd_1mb_g3c .language-json} { "status": "success", "request_id": "3213123", "project_id": 12345, "vop": { "id": 777888, "status": "processing" } } ``` ### Формат запроса на получение информации о результате проверки {#section_bxf_xlz_r3c .section} При формировании запросов на получение информации о результатах проверки имён пользователей необходимо учитывать следующее: 1. Для получения информации каждый раз должен использоваться отдельный POST-запрос к конечной точке [/v2/verification-of-payee/result](https://api-developers.ecommpay.com/api-specification/verification-of-payee-service/post-v2-verification-of-payee-result). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись к запросу, составленная после указания всех целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\); - `vop` — объект, содержащий сведения об искомой проверке: - `id` — идентификатор проверки, полученный от Ecommpay в ответе о её инициировании. ``` {#codeblock_oxy_ylz_r3c .language-json} { "general": { "project_id": 12345, "signature": "PJkV8ej\/UQVVfBaNIipTv+AWoXW\/9MTO8yJb==" }, "vop": { "id": 777888 } } ``` ### Формат ответа о результате проверки {#section_b3p_xlz_r3c .section} Для ответов о результатах проверки имён пользователей используется типовой формат, описание которого представлено в статье [Организация взаимодействия](ru_gate_interaction_organisation.md). При этом, в зависимости от ситуации, в объекте `vop` в таких ответах могут передаваться следующие параметры: - `id` — идентификатор искомой проверки; - `status` — индикатор состояния проверки, который может принимать одно из следующих значений: - `processing` — при отсутствии итогового статуса проверкисо стороны сервисного провайдера; - `completed` — при получении итогового статуса проверкисо стороны сервисного провайдера; - `decline` — при невозможности выполнения проверкииз-за ошибок при взаимодействии платформы и сервиса провайдера; - `result` — итоговый статус проверки \([подробнее](ru_verification_of_payee.md); не включается в ответ, если в параметре `status` указано значение `processing`\); - `details` — пояснения к итоговому статусу проверки со стороны сервисного провайдера \(не включаются в ответ, если в параметре `status` указано значение `processing` или если в параметре `result` указано значение `VOP_ERROR`\). В случаях с итоговым статусом `VOP_ERROR` рекомендуется обращаться к специалистам технической поддержки Ecommpay для уточнения информации о проверке и возможности её выполнения. ``` {#codeblock_m4y_gzq_23c .language-json} { "general": { "project_id": 12345, "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" }, "vop": { "id": 777888, "status": "completed", "result": "CLOSE_MATCH", "details": "Reasons: CLOSE_MATCH; Details: The account details match.; Matched: name: John Doe, accountType: personal account" } } ``` ## Дополнительные материалы {#ru_verification_of_payee_add_info} При работе с проверками имён получателей могут быть полезны следующие материалы: - [Быстрый старт](ru_gate_quickstart.md) и [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. --- # Дополнение информации о платеже {#ru_Gate_Clarification .concept} статья о процедуре предоставления дополнительных сведений, которые могут запрашиваться платёжными системами при проведении платежей через Gate ## Общая информация {#section_jdm_zr3_m3b .section} Как правило, для проведения платежа достаточно тех данных, которые обязательны для запроса на инициирование этого платежа. Но в отдельных случаях — например, для соблюдения специфических региональных требований или для дополнительной проверки на мошенничество — со стороны платёжной системы или провайдера могут запрашиваться дополнительные данные, необязательные в общем случае, но необходимые в конкретной ситуации. В платёжной платформе для работы с такими ситуациями используется процедура дополнения информации, в рамках которой обеспечиваются информирование о составе запрашиваемых данных и ожидание предоставления этих данных. При этом поддерживается гибкость как со способом информирования, так и с порядком предоставления данных. Подробные сведения об этом представлены далее. Информация, запрашиваемая в качестве дополнительной, обычно касается пользователя и его платёжного средства: для платежей с использованием карт это могут быть параметры объектов `avs_data` \(для проверки Address Verification Service, [AVS](ru_Gate_avs.md)\) и `customer`, а для платежей с использованием альтернативных методов — необязательные параметры из числа допустимых для исходного запроса на проведение платежа. Со стороны веб-сервиса можно обеспечить передачу полной информации во всех запросах на инициирование платежей \(и уйти от необходимости в дополнении информации\) либо настроить реагирование на ситуации с необходимостью дополнения \(и поддерживать проведение платежей в таких случаях\). Далее представлены сведения о работе с дополнением информации. ## Схема работы {#section_ljh_kw5_zgb .section} Необходимость предоставить данные может быть выявлена как на стороне платёжной системы или провайдера, так и на стороне платёжной платформы. В платёжной платформе поддерживаются *два способа информирования* о необходимости дополнить данные: через оповещения и ответы. Обычно эта информация отправляется в оповещениях — без предварительных запросов со стороны веб-сервиса, но в то же время её можно получать в ответах на запросы о статусе платежа. По согласованию с курирующим менеджером Ecommpay можно отключить отправку оповещений и оставить только отправку ответов на запросы. Со стороны веб-сервиса *реагирование* на сообщение о необходимости дополнения данных сводится к составлению и отправке в платформу корректного запроса на продолжение платежа. Время ожидания такого запроса составляет 30 минут и измеряется с момента выявления необходимости дополнить данные и до получения запроса от веб-сервиса. Если время ожидания истекло и запрос в платформе не принят — платёж автоматически отклоняется. Процедура дополнения данных может включать в себя неоднократную отправку таких запросов, при приёме которых отсчёт времени в платформе каждый раз начинается сначала. Время приёма повторных запросов ограничено только предельным временем проведения конкретного платежа. *Состав запрошенных данных* в теле запроса может варьироваться: данные можно указывать в полном объёме, частично или не указывать совсем, но в любом случае в теле запроса должен содержаться объект `additional_data`. При приёме запроса без этого объекта запрос признаётся некорректным и к веб-сервису отправляется ответ с информацией об ошибке. При приёме каждого корректного запроса обновляется список запрашиваемых данных, о чём сообщается любым из способов информирования. Как только в платёжную платформу поступают все запрашиваемые данные, проведение платежа продолжается дальше. ![](images/ru_clarification_uml.svg) В рамках взаимодействия с платёжной платформой для дополнения информации со стороны веб-сервиса необходимо: 1. Получить список параметров в объекте `clarification_fields` в оповещении или ответе. 2. Отправить POST-запрос, содержащий требуемый набор данных с объектом `additional_data` и подпись, к конечной точке [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification). 3. Получить и обработать ответ о приёме запроса в обработку — `200 OK`. Ответ `200 OK` отправляется, когда все запрашиваемые параметры указаны корректно и в полном объёме. При невыполнении хотя бы одного условия цикл повторяется, начиная с шага 1. Информация о форматах сообщений о необходимости дополнить данные и о формате запроса на продолжение платежа приведена далее. ## Форматы сообщений с запрашиваемыми данными {#section_oyf_d4j_m3b .section} Информация о необходимости дополнить данные может передаваться как в оповещении, так и в ответе на запрос статуса платежа. *Для оповещения* о необходимости дополнить данные используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). К особенностям оповещения в этом случае можно отнести наличие объекта `clarification_fields` со списком запрашиваемых параметров.Так, в следующем примере запрашиваются индекс и адрес пользователя, необходимые для проверки AVS при проведении оплаты с использованием платёжной карты. ```language-json POST /notify/success HTTP/1.1 Content-Length: 1237 User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1 Content-Type: application/json Host: example.com { "sum_request": { "amount": 45000, "currency": "USD" }, "request_id": "80bdc0831c3f8e1", "payment": { "id": "", "method": "card", "date": "2019-07-29T11:19:33+0000", "result_code": "9999", "result_message": "Awaiting processing", "is_new_attempts_available": false, "attempts_timeout": 0, "provider_id": 3 }, "sum_real": { "amount": 45000, "currency": "USD" }, "status": "awaiting clarification", // Статус платежа "customer": { "id": "4314220000000056" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "JUDY DOE", "expiry_month": "03", "expiry_year": "2021" }, "clarification_fields": { // Запрашиваемая информация "avs_data": [ "avs_post_code", "avs_street_address" ] }, "general": { "project_id": 11, "payment_id": "EPr-bf14", "signature": "99q4lpCEuNpxp3ugvxF1qPbinWUIwNSLaxcVbF0A==" }, "description": "", "operations": [ { "id": 7282148104130, "type": "sale", "status": "awaiting clarification", "date": "2019-07-29T11:19:33+0000", "processing_time": null, "sum": { "amount": 45000, "currency": "USD" }, "code": "9999", "message": "Awaiting processing" } ] } ``` *Для ответа* о необходимости дополнить информацию используется формат, который совпадает как для оповещений, так и для ответов в рамках исходного запроса на проведение платежа.В следующем примере ответа на запрос к конечной точке [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status) сообщается о необходимости указать электронную почту, имя и фамилию, платёжный адрес и дату рождения пользователя. ```language-json HTTP/1.1 200 OK Server: api.com Date: Wed, 29 July 2019 09:27:45 GMT Content-Type: application/json; charset=UTF-8 Content-Length: 875 Connection: keep-alive Keep-Alive: timeout=60 Cache-Control: no-cache Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Origin: * X-Powered-By: PHP/7.0.32 Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,User-Agent, X-Requested-With,If-Modified-Since,Cache-Control,Content-Type { "sum_request": { "amount": 500, "currency": "CNY" }, "request_id": "563c42d4846d105e77", "payment": { "method": "cup-card", "date": "2019-07-29T09:27:45+0000", "result_code": "9999", "result_message": "Awaiting processing", "status": "awaiting clarification", // Статус платежа "is_new_attempts_available": false, "attempts_timeout": 0, "id": "E2E_01_0868", "cascading_with_redirect": false, "provider_id": 1145 }, "sum_real": { "amount": 500, "currency": "CNY" }, "customer": { "id": "7826" }, "clarification_fields": { // Запрашиваемая информация "customer": [ "email", "first_name", "last_name", "billing.address", "billing.city", "billing.country", "billing.postal", "day_of_birth" ] }, "general": { "project_id": 245, "payment_id": "E2E_01_0868", "signature": "MYiga7aoW0UBFBfeTdIiF0QFOokEfyuSA==" }, "description": "", "operations": [ { "id": 1315207090506, "type": "sale", "status": "awaiting clarification", "date": "2019-07-29T09:27:45+0000", "processing_time": null, "request_id": "563c42d4846d105e77", "sum": { "amount": 500, "currency": "CNY" }, "code": "9999", "message": "Awaiting processing" } ] } ``` ## Формат запроса для продолжения платежа {#section_vgx_ww5_zgb .section} Запрос для продолжения платежа с учётом дополнения данных отправляется методом POST к конечной точке [/v2/payment/clarification](https://api-developers.ecommpay.com/api-specification/additional-information-submission/post-v2-payment-clarification) и должен содержать следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - `additional_data` — объект с запрошенными данными. Параметры в объекте могут быть указаны полностью, частично или не указаны совсем. **Прим.:** Объект `interface_type` не обязателен для заполнения. Таким образом, корректный запрос должен содержать идентификаторы проекта и платежа, подпись и данные, которые требуются для продолжения платежа.В следующем примере в качестве дополнительных данных указаны почтовый индекс и адрес пользователя \(в соответствии с запрошенными данными в примере оповещения выше\). ```language-json { "general": { "project_id": 11, "payment_id": "EPr-bf14", "signature": "v7KNMpfogAthg1ZZ5D/aZAeb0VMdeR+CqghwSm...==" }, "additional_data": { "avs_data":{ "avs_post_code": "99546", "avs_street_address": "01 Main Street, CA" } } } ``` В следующем примере представлены данные двух запросов. Это может быть актуально для случая, когда 30 минут недостаточно, чтобы предоставить запрошенную информацию в полном объеме. В таком случае сначала от веб-сервиса отправляется запрос только для продолжения платежа, поэтому в объекте `additional_data` параметры совсем не указаны. А далее отправляется запрос для продолжения платежа с учётом запрошенных данных, поэтому в объекте `additional_data` указаны электронная почта, имя и фамилия, платёжный адрес и дата рождения пользователя \(в соответствии с запрошенными данными в примере ответа выше\). ```language-json // Тело запроса для продолжения платежа { "general": { "project_id": 245, "payment_id": "E2E_01_0868", "signature": "5uco0y4eeTdf59R/1SQXdfepidfw==" }, "additional_data": { } } // Тело запроса для продолжения платежа с учётом требуемых данных { "general": { "project_id": 1144, "payment_id": "128755012", "signature": "5uco0y4eeTdf59R/1SQXdfepidfw==" }, "additional_data": { "customer": { "email": "test@testmail.com", "first_name": "杨", "last_name": "思荣", "billing": { "address": "和飞机的事", "city": "市区-东城区", "country": "CN", "postal": "156114" }, "day_of_birth": "12-12-1990" } } } ``` **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) --- # Конвертация валют {#ru_Gate_Conversion .concept} статья о порядке проведения через Gate платежей с применением разных валют и встроенной в этот процесс конвертацией ## Общая информация {#section_g2z_3kl_bbb .section} При проведении платежа в общем случае могут задействоваться три валюты: валюта счёта пользователя, валюта платежа и валюта счёта мерчанта. Если все эти валюты одинаковы, то конвертация, то есть пересчёт суммы из одной валюты в другую, не требуется, тогда как в иных ситуациях она необходима. Допустим, пользователь выбирает рублёвую карту для перевода средств в евро на счёт мерчанта, открытый в фунтах стерлингов. В таком случае сумма платежа последовательно конвертируется из рублей в евро и из евро в фунты. Первый из этих пересчётов выполняется на стороне эмитентаили альтернативной платёжной системы\(и не контролируется со стороны Ecommpay\), а второй — на стороне платёжной платформы Ecommpay. Мерчант также может проводить конвертацию на своей стороне и в запросах на проведение операций отправлять сразу сконвертированную сумму в нужной валюте. Для платежей, проводимых через Gate, в платёжной платформе поддерживается *конвертация с выбором валюты мерчантом* — без предоставления пользователю возможности выбора валюты платежа.Такая конвертация поддерживается при проведении выплат, а также разовых оплат с использованием любых платёжных методов. Для конвертации используются валютные курсы, устанавливаемые Ecommpay. С вопросами о курсах и порядке их применения можно обращаться к курирующему менеджеру Ecommpay. Информацию о конвертации, выполненной на стороне платёжной платформы, можно получать в оповещениях о результатах платежей, в интерфейсе Dashboard и в регулярных отчётах, отправляемых на заданные адреса электронной почты. Эту информацию рекомендуется учитывать при сверках с Ecommpay, потому что учёт операций по счёту мерчанта со стороны эмитентаили альтернативной платёжной системы, как правило, ведётся в валюте этого счёта. Также следует учитывать, что сумма операции и сумма фактически списанная со счёта пользователя могут не совпадать, так как на дату инициирования платежа и дату фактического списания средств курсы конвертации как правило отличаются. По факту компенсации в таких случаях пользователю следует обращаться к эмитенту карты или организации, где открыт счёт. Чтобы узнать, какие платёжные методы в какой валюте поддерживают конвертацию, следует обращаться к описанию этого метода или к курирующему менеджеру Ecommpay. ## Подключение {#section_u2c_qrk_kjb .section} Для подключения конвертации на стороне веб-сервиса выполнять какие-либо действия не требуется. ## Использование {#section_zh4_qrk_kjb .section} Для использования этого варианта конвертации со стороны веб-сервиса не требуется действий, отличных от стандартных при проведении оплаты. Информация о выполненной конвертации передаётся в оповещениях о результатах платежей — в объекте `operation`, где в объекте `sum_initial` указываются исходные сумма и валюта, а в объекте `sum_converted` — конечные сумма и валюта с учётом конвертации. Эти объекты входят в стандартную структуру оповещения, описание которой представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере в оповещении содержится информация о том, что при проведении оплаты в размере `100 USD` выполнена конвертация в `519,41 PHP`. ```language-json { "project_id": 239, "payment": { "id": "EPfa87-bcfd", "type": "purchase", "status": "success", "date": "2020-03-06T14:11:00+0000", "method": "Philippines banks", "sum":{ "amount":10000, // Сумма, переданная в запросе "currency":"USD" // Код исходной валюты, переданный в запросе }, "description": "" }, "operation": { "id": 464, "type": "sale", "status": "success", "date": "2020-03-06T14:11:00+0000", "created_date": "2020-03-06T14:10:34+0000", "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001", "sum_initial": { "amount":10000, // Сумма, переданная в запросе "currency":"USD" // Код исходной валюты, переданный в запросе }, "sum_converted": { "amount":519410, // Сумма с учётом конвертации "currency":"PHP" // Код конечной валюты }, "code": "0", "message": "Success", "provider": { "id": 1369, "payment_id": "7QKID3P3", "auth_code": "", "endpoint_id": "BOG", "date": "2020-03-06T14:10:54+0000" } }, "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA==" } } ``` **На уровень выше:**[Вспомогательные процедуры](ru_gate_procedures.md) --- # Дополнительные возможности {#ru_Gate_Additional_capabilities .concept} статьи о дополнительных возможностях Gate, которые могут быть полезны для повышения проходимости платежей, удобства пользователей и качества предоставляемых услуг В этом разделе представлены материалы о различных возможностях, которые могут применяться по инициативе мерчанта для улучшения предоставляемого им сервиса. ## Контроль проведения платежей {#section_udd_5vb_stb .section} Материал о возможности получения актуальной информации о конкретных платежахчерез Gate API — [Получение информации о состоянии платежа](ru_Gate_payment_status_request.md). ## Повышение проходимости платежей {#section_vs2_xvs_qtb .section} Материалы о том, что можно использовать для обеспечения высокой проходимости платежей: - [Каскадное проведение платежей](ru_gate_cascading.md)— о возможности выполнения дополнительных попыток проведения оплат \(когда это актуально\). - [Проведение оплат с частичными списаниями](ru_gate_partial_approval.md)— о возможности проведения оплат с одобрением эмитентом части суммы платежа. - [Получение информации о доступных методах](ru_gate_available_methods.md)— о возможности получения информации о доступных для проведения платежа методах. ## Использование платёжных данных {#section_g41_rrx_qtb .section} Материалы о возможностях сохранения и использования платёжных данных пользователей с применением произвольных идентификаторов \([Сохранение платёжных данных](ru_gate_saved_data.md)\) и стандартизированных токенов \([Использование токенов](ru_Gate_Token.md)\), сетевых токенов \([Работа с „сетевыми токенами“ карт платёжных систем Mastercard и Visa](ru_gate_tokens.md)\), а также о возможности переноса информации в платформу \([Перенос информации о повторяемых оплатах и токенах платёжных карт](ru_gate_data_migration.md)\). ## Поддержка специфичных сценариев работы {#section_vgg_wrx_qtb .section} Материалы о том, как можно использовать интерфейс Gate в специфических случаях, актуальных для различных отраслей, видов бизнеса и иных ситуаций: - [Проведение оплат MO/TO](ru_Gate_moto.md)— о возможности проведения оплат с получением платёжных данных пользователей по электронной почте, телефону или иным каналам связи. - [Оценка достоверности имён держателей карт](ru_gate_cardholder_name_verification.md)— о возможности сверять написания имён держателей карт с зафиксированными у эмитентов. - [Использование сервисов Mastercard MoneySend и Visa Direct](ru_gate_money_transfer_services.md)— о возможности проведения денежных переводов между пользователями и мерчантами в рамках сервисов Mastercard MoneySend и Visa Direct. - [Погашение задолженностей](ru_Gate_debt_repayments.md)— о возможности проведения платежей с целью погашения кредитов и займов. - [Использование „длинных записей“](ru_gate_addendum.md)— о возможности использования расширенного набора параметров \(„длинной записи“\) при оплате авиаперелётов. - [Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса](ru_gate_additional_data.md)— о возможности фиксировать сопутствующую информацию о проводимых оплатах для её внутреннего использования. ## Информирование пользователей {#section_xbg_4sx_qtb .section} Материалы о том, что можно использовать для информирования пользователей: - [Использование сведений о мерчанте при проведении платежей](ru_gate_descriptor.md)— о возможностях опосредованного предоставления пользователям различных сведений о мерчантах через сервисы эмитентов. - [Отправка уведомлений пользователям](ru_gate_receipts.md)— о возможностях прямого информирования пользователей о проведении платежей и других событиях через электронную почту. - **[Получение информации о состоянии платежа](ru_Gate_payment_status_request.md)** статья о возможности получать через Gate актуальную информацию о конкретных платежах, независимо от того, через какие интерфейсы они были инициированы - **[Каскадное проведение платежей](ru_gate_cascading.md)** статья о возможности выполнять дополнительные попытки проведения платежей через Gate - **[Проведение оплат с частичными списаниями](ru_gate_partial_approval.md)** статья о возможности проводить через Gate оплаты, в рамках которых эмитенты одобряют частичные списания от исходных сумм платежей - **[Получение информации о доступных методах](ru_gate_available_methods.md)** статья о возможности получать через Gate информацию о платёжных методах, доступных для проведения конкретного платежа - **[Сохранение платёжных данных](ru_gate_saved_data.md)** статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением произвольных идентификаторов - **[Использование токенов](ru_Gate_Token.md)** статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением стандартизированных локальных токенов - **[Работа с „сетевыми токенами“ карт платёжных систем Mastercard и Visa](ru_gate_tokens.md)** статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением сетевых токенов карт платёжных систем Mastercard и Visa - **[Перенос информации о повторяемых оплатах и токенах платёжных карт](ru_gate_data_migration.md)** статья о возможности переносить в платформу Ecommpay информацию о повторяемых оплатах и токенах платёжных карт от других эквайеров - **[Проведение оплат MO/TO](ru_Gate_moto.md)** статья о возможности проводить через Gate оплаты с получением платёжных данных пользователей по электронной почте, телефону и иным каналам связи - **[Оценка достоверности имён держателей карт](ru_gate_cardholder_name_verification.md)** статья о возможности сверять написания имён держателей карт с зафиксированными у эмитентов при работе через Gate - **[Использование сервисов Mastercard MoneySend и Visa Direct](ru_gate_money_transfer_services.md)** статья о возможности проводить денежные переводы между пользователями и мерчантами в рамках сервисов Mastercard MoneySend и Visa Direct при работе через Gate - **[Погашение задолженностей](ru_Gate_debt_repayments.md)** статья о возможности проводить через Gate платежи по кредитам и займам - **[Использование „длинных записей“](ru_gate_addendum.md)** статья о возможности использовать при работе через Gate расширенные наборы параметров \(«длинные записи»\) для учёта специализированной информации об оплате авиаперелётов - **[Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса](ru_gate_additional_data.md)** статья о возможности фиксировать при работе через Gate сопутствующую информацию о проводимых оплатах для её внутреннего использования в работе мерчантов - **[Использование дополнительных параметров проведения платежей](ru_Gate_extra_params.md)** статья о возможности использовать при работе через Gate дополнительные параметры, актуальные для мерчантов и не предусмотренные в спецификации Gate API - **[Использование сведений о мерчанте при проведении платежей](ru_gate_descriptor.md)** статья о возможностях опосредованно предоставлять пользователям сведения о мерчантах через сервисы эмитентов при работе через Gate - **[Отправка уведомлений пользователям](ru_gate_receipts.md)** статья о возможностях прямо информировать пользователей о проведении платежей и других событиях через электронную почту при работе через Gate **На уровень выше:**[Gate](ru_Gate_Integration_About.md) --- # Получение информации о состоянии платежа {#ru_Gate_payment_status_request .concept} статья о возможности получать через Gate актуальную информацию о конкретных платежах, независимо от того, через какие интерфейсы они были инициированы **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Обзор {#ru_gate_payment_status_request_overview} При работе с платёжной платформой Ecommpay получать актуальную информацию о состоянии платежей можно разными способами \(подробнее — в отдельном [обзоре](ru_platform_payment_information_overview.md)\). Наряду с другими интерфейсами для этого могут использоваться специализированные программные запросы к конечным точкам группы `payment/status` Gate API. Они позволяют оперативно получать информацию о конкретных платежах в то время, которое актуально со стороны веб-сервиса мерчанта, и могут глубоко интегрироваться в функциональность сервиса. Для получения информации о состоянии отдельного платежа через Gate API могут использоваться два способа поиска: - *По идентификатору платежа*. Этот способ является основным и может использоваться в любое время. Содержание ответов при использовании этого способа в каждом случае зависит от того, был ли зарегистрирован искомый платёж в платформе. - Если платёж был зарегистрирован, в ответ на запрос о состоянии такого платежа включается актуальная информация о платеже. - Если платёж не был зарегистрирован \(например, при вызове платёжной формы Payment Page и её закрытии пользователем до подтверждения платежа\), в ответ на запрос о состоянии такого платежа включается информация о том, что такой платёж не был зарегистрирован. - *Поиск по идентификатору запроса на проведение платежа*. Этот способ является дополнительным и для корректного поиска информации должен использоваться не ранее чем через 2 секунды после отправки запроса на проведение искомого платежа. Использование этого способа может быть актуальным, например, когда запрос на проведение платежа не был принят из-за выявленных ошибок в формате или содержании запроса. В таких случаях в ответ на запрос о состоянии платежа включается информация о выявленных ошибках, не позволивших перейти к проведению платежа. **Прим.:** В общем случае поиск по идентификатору запроса не рекомендуется использовать вместо основного поиска по идентификатору платежа. Получать информацию о любом платеже после принятия запроса на его проведение предпочтительнее по идентификатору платежа. Независимо от способа поиска, все запросы о состоянии платежа выполняются в рамках синхронной схемы взаимодействия между веб-сервисом и платёжной платформой. Это означает, что каждый такой запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа \(`200`\) и запрошенная информация без указания статуса запроса. В случаях, если запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса `error` и описание причины обнаруженной ошибки. Информация об HTTP-кодах ответов представлена в статье [Организация взаимодействия](ru_gate_interaction_organisation.md), а о кодах ошибок, используемых в платёжной платформе — в статье [Работа с информацией об операциях](ru_platform_payment_info_codes.md). ## Получение информации по идентификатору платежа {#ru_gate_payment_status_request_by_payment_id} ### Формат запроса {#section_xxz_2nm_rkb .section} Формат запроса на получение информации о состоянии платежа по его идентификатору соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md), конечной точкой API для этого запроса выступает [/v2/payment/status](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status), а в теле запроса должен содержаться объект `general` с основными идентификационными сведениями: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, информацию о состоянии которого необходимо получить; - `signature` — подпись запроса, составленная на основе вышеуказанных параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). ```language-json { "general":{ "project_id":50, "payment_id":"ORDER_ID_302bis", "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" } } ``` ### Формат ответа {#section_ayz_2nm_rkb .section} Формат ответа на запрос о состоянии платежа соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). В заголовке целевого ответа содержится стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к этому коду \(`200 OK`\). В теле такого ответа содержатся: - идентификатор проекта и подпись; - информация о статусе платежа и обо всех инициированных в рамках этого платежа операциях; - дополнительная информация, состав которой может варьироваться в зависимости от используемого платёжного метода и может настраиваться для разных методов по согласованию со специалистами технической поддержки. Базовый набор сведений, передаваемых в ответ на запрос о состоянии платежа, указан [в спецификации Gate API](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status). ### Примеры ответов {#section_htw_t1q_jlb .section} Далее представлен пример данных о проведённой двухстадийной оплате. В этом примере указаны: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`success`\); - код используемого платёжного метода \(`card`\); - сведения об операциях `auth` и `capture` в массиве `operations`. ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":50, "payment":{ "id":"ORDER_ID_302bis", "type":"purchase", //тип платежа "status":"success", //статус платежа "date":"2019-12-12T15:46:51+0000", "method":"card", //код платёжного метода "sum_real":{ "amount":33, "currency":"USD" }, "description":"Booking" }, "customer":{ "id":"6361696170" }, "account":{ "number":"4314220000000056", "type":"visa", "card_holder":"Michael Nurenberg", "expiry_month":"03", "expiry_year":"2024" }, "operations":[ { "id":9435219675496, "type":"auth", //тип операции "status":"success", //статус операции "date":"2019-12-11T15:46:37+0000", "created_date":"2019-12-11T15:46:35+0000", "request_id":"bcRFZRJkmfcf-178c3d843c99-00009436", "sum":{ "amount":33, "currency":"USD" }, "code":"0", //код, уточняющий статус операции auth "message":"Success", //пояснение к коду "eci":"07", "provider":{ "id":615, "payment_id":"2015611", "auth_code":"7213535217", "endpoint_id":615, "date":"2019-12-11T15:46:36+0000" }, "operation_fee":{ //объект с информацией о комиссии "amount":31, "currency":"USD" } }, { "id":9435219671141, "type":"capture", //тип операции "status":"success", //статус операции "date":"2019-12-12T15:46:51+0000", "created_date":"2019-12-12T15:46:48+0000", "request_id":"2f114083cfb0f6d12c2-2ac890ebadb793-05015382", "code":"0", //код, уточняющий статус операции capture "message":"Success" //пояснение к коду } ], "signature":"yb9JpzzbyEbkxitA9c3+c+0nX7PQwO8TPoYLGcPnZprQNnHgPlanEYqj1SAg==" } ``` В представленном далее примере данных о незавершённой одностадийной оплате содержится следующая информация: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`awaiting redirect result`\); - код используемого платёжного метода \(Malaysian Banks\); - сведения об операции `sale` в массиве `operations`. ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":72, "payment":{ "id":"ORDER_ID_tetan_M_2007_2012", "type":"purchase", //тип платежа "status":"awaiting redirect result", //статус платежа "date":"2019-12-11T15:59:10+0000", "method":"`Malaysian Banks`", //код платёжного метода "sum":{ "amount":25000, "currency":"MYR" }, "description":"Book premium" }, "customer":{ "id":"Scott", "phone":"44177118324" }, "operations":[ { "id":65747461, "type":"sale", //тип операции "status":"awaiting redirect result", //статус операции "date":"2019-12-11T15:59:10+0000", "created_date":"2019-12-11T15:59:06+0000", "request_id":"97c7dd03080b4293603f28e64-0c415bc3e876c911f2d87-00006979", "sum_initial":{ "amount":25000, "currency":"MYR" }, "sum_converted":{ "amount":25000, "currency":"MYR" }, "code":"9999", //код, уточняющий статус операции sale "message":"Awaiting processing", //пояснение к коду "provider":{ "id":2012, "payment_id":"", "auth_code":"" }, "operation_fee":{ //объект с информацией о комиссии "amount":25, "currency":"MYR" } } ], "signature":"i12QRhdMbrh6iFF2zKQ7X78u+M7KdwhRLpc2gHiF+lL74Wfp7Ylr85NA==" } ``` Далее представлен пример ответа на некорректно составленный запрос. Если в запросе обнаружена ошибка, то в ответе указывается следующее: - код ответа с описанием причины ошибки в стартовой строке \(`400 Bad Request`\); - статус обработки запроса \(`error`\); - уточняющая информация об ошибке: код ошибки \(`2004`\) и поясняющее описание к нему \(`Required field not provided`\). ```language-json HTTP/1.1 400 Bad Request //стартовая строка ответа ... //поля заголовка { "status":"error", //статус обработки запроса "code":"2004", //код, уточняющий статус "message":"Required field not provided" //пояснение к коду } ``` Для сравнения далее представлен пример ответа с информацией об отклонении платежа. В этом примере указаны: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`decline`\); - сведения об операции `sale`, которые включают код ошибки при выполнении операции \(`20502`\) и поясняющее описание к нему \(`Error during operation validation`\). ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "project_id":912103, "payment":{ "id":"ORDER_ID_2018nbl", "type":"purchase", //тип платежа "status":"decline", //статус платежа "date":"2018-05-04T12:55:51+0000", "method":"mobile", //код платёжного метода "sum":{ "amount":849, "currency":"EUR" }, "description":"Flights" }, "account":{ "number":"20072017", "type":"mTELE2" }, "customer":{ "id":"otokarczuk@gmail.com" }, "operations":[ { "id":2018416116, "type":"sale", //тип операции "status":"decline", //статус операции "date":"2020-05-04T12:55:51+0000", "created_date":"2020-05-04T12:55:10+0000", "request_id":"f522bie5cgu114cny46-fli56cdb35ght516sc4-2008", "sum_initial":{ "amount":849, "currency":"EUR" }, "sum_converted":{ "amount":849, "currency":"EUR" }, "code":"20502", //код, уточняюший статус операции sale "message":"Error during operation validation", //пояснение к нему "provider":{ "id":5232, "payment_id":"1024514", "auth_code":"" }, "operation_fee":{ //объект с информацией о комиссии "amount":0, "currency":"" } } ], "signature":"fsal89p0Eilew6-Ur45uKgaP8tiofC-cDns8Z1ow==" } ``` Далее представлен пример ответа на запрос о состоянии такого платежа, запрос на инициирование которого не был принят в платёжной платформе \(например, когда пользователь закрыл платёжную форму до подтверждения оплаты\). В этом случае в ответе содержатся: - код ответа о том, что запрос был успешно принят \(`200`\); - статус платежа \(`error`\); - уточняющая информация об ошибке: код ошибки \(`3061`\) и описание к нему \(`Transaction not found`\). ```language-json HTTP/1.1 200 OK //стартовая строка ответа ... //поля заголовка { "payment":{ "status":"error" //статус платежа }, "errors":[ { "code":"3061", //код, уточняющий статус "message":"Transaction not found" //пояснение к коду } ], "signature":"O08H+DLViSdn9ZoorYsbearslZsQ==" } ``` ## Получение информации по идентификатору запроса {#ru_gate_payment_status_request_by_request_id} ### Формат запроса {#section_jjf_htc_vtb .section} Формат запроса на получение информации о состоянии платежа по идентификатору запроса на его проведение соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md), конечной точкой API для этого запроса выступает [/v2/payment/status/request](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-payment-status-request), а в теле запроса должны содержаться следующие сведения: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `request_id` — идентификатор запроса на проведение платежа, информацию о состоянии которого необходимо получить, полученный в ответе от платёжной платформы; - `signature` — подпись запроса, составленная на основе вышеуказанных параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). ```language-json { "project_id":50, "request_id":"2336565", "signature":"qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" } ``` ### Формат ответа {#section_j2w_htc_vtb .section} Формат ответа на запрос о состоянии платежа соответствует описанному в разделе [Организация взаимодействия](ru_gate_interaction_organisation.md). В заголовке ответа на успешно принятый запрос содержится стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к коду \(`200 OK`\), а в теле такого ответа содержится информация о целевом платеже: набор сведений о платеже и инициированных при его проведении операциях либо информация об ошибках в запросе на проведение этого платежа. ## Дополнительные материалы {#ru_gate_payment_status_request_related_links} При работе с запросами на получение статуса платежа могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md) — раздел с общей информацией о взаимодействии с платёжной платформой через Gate. - [Модель проведения платежей](ru_platform_payment_model.md) — раздел с информацией о типах, схемах проведения и возможных статусах поддерживаемых платежей. - [Работа с подписью к данным](ru_platform_signature.md) — раздел с информацией о создании и проверке подписи в запросах и оповещениях при взаимодействии с платёжной платформой. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md) — раздел со списком кодов ошибок и ответов, используемых в платёжной платформе для уточнения информации об операциях. --- # Каскадное проведение платежей {#ru_gate_cascading} статья о возможности выполнять дополнительные попытки проведения платежей через Gate **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Оплаты с прямым использованием карт {#ru_gate_cascading_cards} ### Общая информация {#section_rlm_rfp_qjb .section} По различным причинам проведение платежей может прерываться. Например, на стороне провайдеров или банков причинами могут служить технические сбои, задержки в обработке платежа или же достижение лимитов, заданных для пользователя на стороне какого-либо провайдера. Для таких случаев в платформе Ecommpay поддерживается возможность каскадного проведения платежей. Каскадное проведение включает в себя последовательные дополнительные попытки проведения платежа через резервных провайдеров без изменения платёжного метода. При работе с прямым использованием карт эта возможность доступна только для разовых оплат в одну или две стадии как с поддержкой, так и без поддержки протокола 3‑D Secure. При работе с прямым использованием карт допускается только однократное списание средств, поэтому инициирование дополнительных попыток осуществляется на стороне платёжной платформы. Для поддержки такой возможности на стороне веб-сервиса требуются доработки относительно реализации стандартного проведении разовых оплат. Подробная информация о настройке веб-сервиса и схеме взаимодействия с платёжной платформой представлена далее. ### Подключение и настройка {#section_fpy_5hcgh_qjb .section} Чтобы подключить каскадное проведение платежей и настроить взаимодействие с платёжной платформой, со стороны мерчанта необходимо: 1. Решить организационные вопросы, согласовав с курирующим менеджером Ecommpay подключение этой возможности и необходимые доработки веб-сервиса. 2. Доработать веб-сервис для использования каскадного проведения платежей. - Дополнить платёжный интерфейс новыми элементами взаимодействия с пользователем. При проведении повторной аутентификации 3‑D Secure рекомендуется уведомлять пользователя об отказе в проведении текущей попытки оплаты и получать согласие пользователя на повторную аутентификацию с использованием данных карты, введённых при проведении исходной попытки. Для этого можно использовать уведомление и кнопку. Также при исчерпанном лимите на дополнительные попытки рекомендуется предложить пользователю вернуться в веб-сервис и начать оплату заново с новым идентификатором платежа \(`payment_id`\). - Поддержать неоднократную аутентификацию 3‑D Secure без внесения изменений в данные карты, введённые при выполнении первой попытки. Для этого требуется принимать от платёжной платформы промежуточные оповещения с данными для перенаправления пользователя при каждом проведении повторной аутентификации. А также следует учесть, что в этом случае в набор параметров таких оповещений входит дополнительный параметр `cascading_with_redirect`. Затем с согласия пользователя необходимо повторно выполнить перенаправление на страницу аутентификации без внесения изменений в данные, введённые ранее. 3. Отладить и протестировать возможность каскадного проведения оплат совместно с сотрудниками технической поддержки Ecommpay. ### Схема проведения {#section_sb4_nvd_kkb .section} Каскадное проведение платежа начинается стандартно: от веб-сервиса к платёжной платформе отправляется запрос на оплату. Далее при необходимости выполняется аутентификация пользователя по протоколу 3‑D Secure. Если эта попытка завершается списанием средств, то от платёжной платформы к веб-сервису отправляется оповещение с итоговым статусом платежа — `success`, а иначе продолжается каскадное проведение платежа. Далее, пока ни одна из выполненных попыток не привела к успешному списанию и дополнительные попытки ещё не исчерпаны, на стороне платёжной платформы инициируется выполнение новой попытки списать средства. Если в рамках дополнительной попытки не требуется аутентификация 3‑D Secure, то она выполняется без взаимодействия с пользователем и веб-сервисом. Если требуется аутентификация, то от платёжной платформы к веб-сервису отправляется оповещение с данными для перенаправления пользователя, и затем с согласия пользователя продолжается выполнение этой оплаты с повторной аутентификацией. Статусу платежа присваивается одно из промежуточных значений `awaiting_3ds_result`, `awaiting_redirect_result` или `processing`\). Каскадное проведение платежа заканчивается стандартно: от платёжной платформы к веб-сервису отправляется оповещение с одним из итоговых статусов платежа: `success`, если одна из выполненных попыток привела к списанию средств, или `decline`, если ни одна из выполненных попыток не привела к списанию и лимит на дополнительные попытки исчерпан. Далее представлена схема каскадного проведения оплаты в контексте оплаты в одну стадию с возможной аутентификацией 3‑D Secure. ![](images/universal/cascade/ru_gate_sale_cascading.svg) \* В качестве провайдера может выступать Ecommpay. 1. От платёжной платформы к провайдеру передаётся запрос на проведение платежа. 2. На стороне провайдера выявляется необходимость в аутентификации пользователя. Если требуется аутентификация, то к платформе отправляются данные для перенаправления пользователя, а иначе отправляется запрос к эмитенту на проведение платежа. 3. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя. 4. Осуществляется взаимодействие с пользователем: - Если аутентификация первичная, то выполняется перенаправление пользователя на страницу аутентификации \(ACS URL\) эмитента. - Если аутентификация повторная, то рекомендуется сначала отобразить пользователю ранее введённые данные карты, сообщение об ошибке и предложение повторить попытку оплаты, и далее с согласия пользователя выполнить перенаправление на страницу аутентификации \(ACS URL\) эмитента. 5. Пользователю отображается страница аутентификации, и он осуществляет требуемые действия. 6. На стороне эмитента выполняется аутентификация пользователя. 7. Выполняется перенаправление пользователя к веб-сервису с передачей данных о результате аутентификации. 8. Пользователю отображается страница ожидания в платёжном интерфейсе веб-сервиса. 9. От веб-сервиса на заданный URL Ecommpay передаётся запрос на продолжение проведения платежа с учётом результата аутентификации. 10. Запрос на продолжение проведения платежа поступает в платёжную платформу. 11. В платёжной платформе выполняется приём запроса с проверкой его корректности. 12. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 13. От платёжной платформы к провайдеру отправляется запрос на проведение платежа. 14. На стороне провайдера осуществляется обработка запроса на проведение платежа. В результате от сервиса провайдера либо к платформе отправляется уведомление об отказе, и на стороне платформы инициируется дополнительная попытка, либо к эмитенту отправляется запрос на проведение оплаты, и продолжается стандартное проведение платежа. ### Формат оповещений {#section_bnh_qw4_rjb .section} При каскадном проведении оплат с применением платёжных карт используются итоговые оповещения стандартного формата, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md), и промежуточные оповещения стандартного формата для перенаправления пользователя на страницу аутентификации, описание этих форматов представлено в разделе [Аутентификация 3‑D Secure](ru_gate_payment_3ds.md). К особенностям промежуточных оповещений в этом случае можно отнести наличие параметра `cascading_with_redirect`, который может принимать одно из следующих значений: - `true` — если требуется получить подтверждение пользователя на дополнительную попытку проведения оплаты, так как в одной из предыдущих попыток выполнялась аутентификация 3‑D Secure; - `false` — если не требуется получить подтверждение пользователя на дополнительную попытку, так как ни в одной из предыдущих попыток не выполнялась аутентификация 3‑D Secure. Причина отказа в выполнении попытки проведения оплаты может быть указана в параметре `message` объекта `operations`. Далее представлен пример набора данных в оповещении для случая, когда на стороне веб-сервиса не требуется получать согласие пользователя на дополнительную попытку проведения оплаты. ``` { "cascading_with_redirect": false, "payment": { "date": "2020-03-28T09:28:54+0000", "OperationFee": { "amount": 0, "currency": "USD" }, "type": "purchase", "sum": { "amount": 2000, "currency": "USD" }, "status": "awaiting 3ds result", "method": "card", "id": "1115888716", "description": "" }, "customer": { "id": "11158745" }, "account": { "number": "431422******0056", "type": "visa", "card_holder": "Jane Doe", "expiry_month": "11", "expiry_year": "2025" }, "project_id": 18616, "operation": { "id": 50454000052091, "type": "sale", "status": "awaiting 3ds result", "date": "2020-03-28T09:28:54+0000", "created_date": "2020-03-28T09:28:53+0000", "request_id": "af5e3a32bf6f8742c9are9", "sum_initial": { "amount": 2000, "currency": "USD" }, "sum_converted": { "amount": 2000, "currency": "USD" }, "code": "9999", "message": "Awaiting processing", "eci": "07", "provider": { "id": 4164, "payment_id": "", "endpoint_id": 4184 } }, "card_type": "Visa Gold", "acs": { "pa_req": "eJxVUd85...W6ip/iPo2E=", "acs_url": "https://acs.bank.com/pareq", "md": "eyZjUtODg...IjoiIn0=" }, "signature": "T1e+AOko05D...KupPd7TA==" } ``` --- # Проведение оплат с частичными списаниями {#ru_gate_partial_approval} статья о возможности проводить через Gate оплаты, в рамках которых эмитенты одобряют частичные списания от исходных сумм платежей ## Общая информация {#section_aj4_ckf_b3c .section} При проведении оплат могут возникать ситуации, когда у пользователя недостаточно средств на счёте для оплаты всей требуемой суммы, но для мерчанта может быть приемлема и частичная сумма зачисления. Например, это может быть актуальным для пополнения пользовательского баланса в веб-сервисе не на полную абонентскую плату, но по крайней мере на её часть. Чтобы допускать такие оплаты и не отклонять их из-за недостатка средств на счетах пользователей, можно использовать функциональность частичного одобрения платежей со стороны эмитентов \(Partial Approval или Partial Authorization\), которая применима в рамках отдельных платёжных систем. В платёжной платформе Ecommpay возможность проведения оплат с частичным одобрением поддерживается для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa. Эта возможность подключается по согласованию с курирующим менеджером Ecommpay в отношении требуемых проектов, после чего со стороны веб-сервиса мерчанта можно регулировать допустимость частичных списаний в отношении каждого инициируемого платежа. Для этого в структуре запросов на проведение платежей предусмотрен специализированный параметр `allow_partial_approval`. Конкретная сумма, которая может использоваться в рамках оплаты с возможностью частичного списания, каждый раз определяется на стороне эмитента используемой платёжной карты\(с учётом актуального баланса средств на счёте\). Информация об этой сумме передаётся от эмитента к платёжной платформеEcommpay, где одобренная сумма учитывается как актуальная сумма платежа, а исходно указанная в запросе сумма игнорируется. При этом важно учитывать, что такое изменение может влиять на дальнейшие операции в рамках оплаты, как например действия со средствами, заблокированными в рамках двухстадийной оплаты, или возврат средств после оплаты.Так, после оплаты с *исходно указанной* суммой `100 EUR` и *фактически одобренной* и оплаченной суммой `90 EUR` в запросе на выполнение частичного возврата может указываться сумма лишь менее `90 EUR`. В свою очередь, разница между исходной и одобренной суммами может быть оплачена \(и при необходимости возвращена\) лишь отдельно, в рамках другой оплаты. Применение возможности частичных списаний не влияет на типовые схемы проведения платежей в отношении последовательности взаимодействий между веб-сервисом и платёжной платформой. Вместе с тем, при использовании этой возможности важно учитывать изменения в форматах запросов и оповещений\(подробнее далее\) и расширять пользовательские сценарии: - уведомлять о допустимости частичного списания суммы платежа или предоставлять возможность согласия с таким вариантом оплаты — перед каждой оплатой, для которой актуальна возможность частичного одобрения; - уведомлять о фактически одобренной и оплаченной сумме — по итогам проведения каждой оплаты, в которой было выполнено частичное списание; - предоставлять возможность доплаты до исходно требуемой суммы через дополнительный платёж\(с возможностью использования другого платёжного инструмента\) — когда это актуально; - предоставлять возможность возврата оплаченной суммы — когда это актуально; - вносить другие дополнения — когда это уместно в рамках оказываемых услуг и специфики веб-сервиса. С вопросами, касающимися порядка подключения возможности проведения оплат с частичным одобрением, можно обращаться к курирующему менеджеру Ecommpay, с техническими вопросами, касающимися аспектов применения этой возможности — к настоящей документации и специалистам технической поддержки Ecommpay. ## Особенности и ограничения {#section_tgq_hmr_yhc .section} При использовании возможности оплат с частичными списаниями стоит учитывать следующие особенности и ограничения: - Возможность допустима для оплат с использованием карт платёжных систем Mastercard и Visa в тех случаях, когда эмитент используемой карты поддерживает частичные списания. В случаях, когда возможность не поддерживается со стороны эмитента и на счёте пользователя недостаточно средств, оплаты отклоняются. - Возможность должна быть подключена для используемого проекта. В случае, если эта возможность не подключена и на счёте пользователя недостаточно средств, оплата отклоняется, даже если в запросе была указана допустимость частичного списания. - Возможность применима для разовых оплат в одну и две стадии, а также для экспресс-оплат при хранении сведений о них на стороне веб-сервиса\(со значением `2` у параметра `stored_card_type`; [подробнее](ru_Gate__payments_on_saved_data.md)\). При регистрации повторяемых оплат частичные списания могут быть применимы для исходных оплат, нов таких случаях изменение актуальной суммы исходной оплаты не распространяется на регистрируемые серии списаний. В случае, если в запросе на инициирование автооплаты или регулярной оплаты \(со значением `4` или `6` у параметра `stored_card_type` соответственно\) указывается допустимость частичного списания, это указание игнорируется и при недостатке средств на счёте пользователя списание отклоняется. - После частичного одобрения актуальной считается сумма платежа, одобренная эмитентом. Это учитывается при конвертации валют \(если она применяется\), а также в рамках последующих операций по платежу, включая различные действия при проведении двухстадийной оплаты \(с уменьшением или увеличением суммы заблокированных средств и списанием или отменой блокировки, даже при их автоматическом инициировании\) и при возврате средств пользователю. ## Подключение, тестирование и использование {#section_fyv_syz_b3c .section} Чтобы *подключить* возможность проведения оплат с частичными списаниями,со стороны мерчанта необходимо: 1. Согласовать с курирующим менеджером Ecommpayподключение этой возможности и необходимость её тестирования. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работы с использованием этой возможностии сообщить о готовности к запуску. 3. Получитьот специалистов Ecommpay уведомление о подключении возможности. Чтобы *протестировать* проведение оплат с частичными списаниями,со стороны мерчанта следует провести как минимум одну оплату в рамках тестового проекта, с формированием запроса требуемого [формата](ru_gate_partial_approval.md#section_gb5_hmr_yhc) и с указанием тестовых данных. - При попытке оплаты на сумму более `120 EUR`\(в дробных единицах `12000`\) с использованием тестовой карты `5126160000356675` или `4010571676223548` должно выполняться списание ровно на `120 EUR`. При этом остальные параметры, включая имя держателя карты или проверочный код, могут иметь различные значения, но должны указываться в корректном формате\(в частности, срок действия карты должен заканчиваться позднее даты платежа\). - В других случаях оплаты должны проводиться на полную сумму или отклоняться, в соответствии с настроенными для проекта сценариями. ``` {#codeblock_jn2_yqx_f3c .language-json} { "general": { "project_id": 41, "payment_id": "test_165", "signature": "MpdRv7dsOtVftZ1ZZ5D/aZAebeR+CqGrNw...==" }, "payment": { "amount": 15000, "currency": "EUR", "allow_partial_approval": true }, "card": { "pan": "4010571676223548", "year": 2035, "month": 8, "card_holder": "JANE DOE", "cvv": "123" } "customer": { "ip_address": "192.0.2.1, "id": "test_customer", "screen_res": "360x640", "phone": "999123456789", "email": "test@example.com" } } ``` ``` {#codeblock_gns_yqx_f3c .language-json} { "account": { "number": "401057******3548", "type": "visa", "card_holder": "JANE DOE", "id": 12, "expiry_month": "08", "expiry_year": "2035" }, "customer": { "id": "test_customer", "phone": "999123456789" }, "payment": { "date": "2026-01-10T13:02:42+0000", "id": "test_165", "method": "card", "status": "success", "sum": { "amount": 12000, // одобренная сумма "currency": "EUR" }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 325, "type": "sale", "status": "success", "date": "2026-01-10T13:02:42+0000", "created_date": "2026-01-10T13:01:45+0000", "request_id": "eedb14c629b4ef20b086d...d04132b0088cbc0be", "sum_initial": { "amount": 12000, "currency": "EUR" }, "sum_converted": { "amount": 12000, "currency": "EUR" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "MpfogAxwRIL9tVftD/aZAeb0VMdeR+CqGUwSm...==" } ``` Чтобы *допускать* применениеранее подключённой возможности частичных списаний для конкретных платежей,со стороны веб-сервиса необходимо указывать специализированный параметр `allow_partial_approval` со значением `true` в запросах на проведение таких платежей. ## Форматы запросов {#section_gb5_hmr_yhc .section} При формировании запросов на проведение оплат с частичным одобрением необходимо учитывать следующее: 1. Для инициирования таких оплат каждый раз должен использоваться POST-запрос к одной из следующих конечных точек: - для разовых одностадийных оплат при передаче реквизитов карты в явном виде и для повторяемых экспресс-оплат —[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale); - для разовых одностадийных оплат при передаче идентификатора вместо реквизитов карты —[/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved); - для разовых одностадийных оплат при передаче токена вместо реквизитов карты —[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token); - для разовых двухстадийных оплат при передаче реквизитов карты в явном виде —[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth), - для разовых двухстадийных оплат при передаче идентификатора вместо реквизитов карты —[/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved). 2. В каждом запросе должны использоваться обязательные для проведения конкретной оплаты объекты и параметры\(подробнее — в описаниях форматов запросов на инициирование разовых [одностадийных](ru_gate_payment_sale.md) и [двухстадийных](ru_gate_payment_auth.md) оплат, а также повторяемых [экспресс-оплат](ru_Gate__cof_merchant_side.md#section_jbj_flf_dlb)\). 3. В каждом запросе в составе объекта `payment` должен передаваться параметр `allow_partial_approval` со значением `true`.При передаче в этом параметре значения `false`, как и при отсутствии этого параметра, частичные списания недопустимы. 4. Дополнительно могут использоваться любые другие параметры из указанных в спецификации используемой конечной точки API. ``` {#codeblock_izf_fkt_yhc .language-json} { "general": { "project_id": 42, "payment_id": "135113521359", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "payment": { "amount": 10000, "currency": "EUR", "allow_partial_approval": true }, "card": { "pan": "4314220000000056", "year": 2035, "month": 8, "card_holder": "Prostetnik Jeltz", "cvv": "521" } "customer": { "ip_address": "93.47.230.225", "id": "customer_12", "screen_res": "360x640", "phone": "44991234567", "email": "p.jeltz@mail.com" }, "return_url": { "success": "https://cosmoshop.jupiter.example/pages/success", "decline": "https://cosmoshop.jupiter.example/pages/decline" } } ``` ``` {#codeblock_i33_d1j_c3c .language-json} { "general": { "project_id": 42, "payment_id": "135113521359", "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" }, "payment": { "amount": 10000, "currency": "EUR", "allow_partial_approval": true }, "card": { "pan": "4314220000000056", "year": 2035, "month": 8, "card_holder": "Prostetnik Jeltz", "cvv": "521" } "customer": { "ip_address": "93.47.230.225", "id": "customer_12", "screen_res": "360x640", "phone": "44991234567", "email": "p.jeltz@mail.com" }, "return_url": { "success": "https://cosmoshop.jupiter.example/pages/success", "decline": "https://cosmoshop.jupiter.example/pages/decline" } } ``` ## Формат оповещений {#section_dn3_jmr_yhc .section} Для итоговых оповещений об оплатах с частичным одобрением используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом в объектах `payment` и `operation` в параметрах `sum`, `sum_initial` и `sum_converted` указываются значения с учётом суммы, одобренной эмитентом, и эту сумму следует использовать для финансового учёта и сверок. ``` {#codeblock_avz_wkt_yhc .language-json} { "account": { "number": "431422******0056", "type": "visa", "card_holder": "PROSTETNIK JELTZ", "id": 45678, "expiry_month": "08", "expiry_year": "2035" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2026-01-11T13:02:42+0000", "id": "135113521359", "method": "card", "status": "success", "sum": { "amount": 9000, // одобренная сумма в исходной валюте "currency": "EUR" // код исходной валюты }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2026-01-11T13:02:42+0000", "created_date": "2026-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 9000, // одобренная сумма в запрошенной операционной валюте "currency": "EUR" // код запрошенной операционной валюты }, "sum_converted": { "amount": 7805, // одобренная сумма в фактической операционной валюте "currency": "GBP" // код фактической операционной валюты }, "provider": { "id": 408, "payment_id": "330157196", "date": "2026-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` ``` {#codeblock_mfm_rz3_c3c .language-json} { "account": { "number": "431422******0056", "type": "visa", "card_holder": "PROSTETNIK JELTZ", "id": 45678, "expiry_month": "08", "expiry_year": "2035" }, "customer": { "id": "customer_12", "phone": "44991234567" }, "payment": { "date": "2026-01-11T13:02:42+0000", "id": "135113521359", "method": "card", "status": "success", "sum": { "amount": 9000, // одобренная сумма в исходной валюте "currency": "EUR" // код исходной валюты }, "type": "purchase", "description": "" }, "project_id": 42, "operation": { "id": 969000002636, "type": "sale", "status": "success", "date": "2026-01-11T13:02:42+0000", "created_date": "2026-01-11T13:01:45+0000", "request_id": "c6eed1eb14c629b4ef20b3b8086d...d04132c34b0088cbc0be4667c", "sum_initial": { "amount": 9000, // одобренная сумма в запрошенной операционной валюте "currency": "EUR" // код запрошенной операционной валюты }, "sum_converted": { "amount": 7805, // одобренная сумма в фактической операционной валюте "currency": "GBP" // код фактической операционной валюты }, "provider": { "id": 408, "payment_id": "330157196", "date": "2026-01-11T13:02:32+0000", "auth_code": "", "endpoint_id": "612266625" }, "code": "0", "message": "Success", "eci": "07" }, "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...==" } ``` ## Дополнительные материалы {#section_amt_jmr_yhc .section} При работе с оплатами с частичным одобрением могут быть полезны следующие материалы: - [Разовые оплаты](ru_Gate_purchase.md)— раздел со статьями о порядке проведения разовых одностадийных и двухстадийных оплат через Gate, включая описания схем взаимодействия и форматов данных при работе с классическими карточными платежами. - [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md)— раздел со статьями о порядке регистрации и проведения повторяемых оплат через Gate, включая описания схем взаимодействия и форматов данных при работе с классическими карточными платежами. - [Возвраты средств после оплат](ru_Gate_Refund.md)— статья о порядке выполнения возвратов средств по проведённым оплатам через Gate, включая общую информацию о таких возвратах и описания форматов данных при работе с классическими карточными платежами. - [Работа с информацией о платежах](ru_platform_payment_information.md)— раздел со статьями о способах получения информации, которая может быть актуальна для контроля проведения платежей и анализа результатов при работе с платёжной платформой. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Получение информации о доступных методах {#ru_gate_available_methods} статья о возможности получать через Gate информацию о платёжных методах, доступных для проведения конкретного платежа При использовании различных платёжных методов в некоторых случаях может быть полезным уточнять информацию об их доступности, в том числе для того, чтобы корректировать набор методов, доступных для выбора пользователями. В платёжной платформе Ecommpay для таких целей предусмотрены возможности программного уточнения информации как по отдельным, так и по всем подключённым методам. При этом следует учитывать, что доступность метода не гарантирует отсутствие каких-либо сбоев и неполадок непосредственно при проведении платежей с его использованием. Для получения информации о доступности методов можно использовать запросы к конечным точкам группы [/v2/info/available-methods/\{payment\_direction\}/list](https://api-developers.ecommpay.com/api.html/v2-info-available-methods-payment-direction-list), где в качестве указателя `payment_direction` следует использовать `payin` для оплат \(любого типа\) или `payout` для выплат. При работе с такими запросами необходимо учитывать следующее: - В каждом запросе должен указываться объект `general`, включающий два параметра: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в статье [Работа с подписью к данным](ru_platform_signature.md)\). - Если необходимо получить информацию для одного или нескольких конкретных платёжных методов, должен указываться массив `payment_method_list`, включающий параметры `payment_method` с [кодами](ru_pm_codes.md) этих методов. ```language-json { "general":{ "project_id": 50, "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" }, "payment_method_list": [ { "payment_method":"etoken" }, { "payment_method":"google-pay" } ] } ``` ```language-json { "general":{ "project_id": 50, "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==" } } ``` Для выполнения запросов на получение информации о доступности методов используется синхронная схема взаимодействия между веб-сервисом и платёжной платформой. Это означает, что каждый такой запрос полностью выполняется на стороне платёжной платформы в течение одного HTTP-сеанса, а в ответе на корректно составленный запрос содержится HTTP-код ответа \(`200`\) и запрошенная информация без указания статуса запроса. В случаях, когда запрос некорректен или с его приёмом и обработкой возникли проблемы, в ответе на запрос содержатся HTTP-код ответа, статус обработки запроса `error` и описание причины обнаруженной ошибки. Информация об HTTP-кодах ответов представлена в статье [Организация взаимодействия](ru_gate_interaction_organisation.md), а о кодах ошибок, используемых в платёжной платформе — в статье [Работа с информацией об операциях](ru_platform_payment_info_codes.md). В теле ответа на корректно составленный запрос содержатся идентификатор проекта, подпись и массив с информацией о доступности методов. ```language-json { "project_id": 50, "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==", "available_methods":[ { "payment_method":"etoken", "is_available": false }, { "payment_method":"google-pay", "is_available": true }] } ``` ```language-json { "project_id": 50, "signature": "qflDO7yiPKCFTyqCAaT+2/f9Gi20aV5woHKyf6J/CGJyuSjq1GH7BYgmil8APKojXw==", "available_methods":[ { "payment_method":"card", "is_available": true }, { "payment_method":"etoken", "is_available": false }, { "payment_method":"google-pay", "is_available": true }] } ``` **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Сохранение платёжных данных {#ru_gate_saved_data .concept} статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением произвольных идентификаторов Для быстрого и удобного проведения платежей пользователь может сохранить реквизиты одной или нескольких карт, кошельков, аккаунтов, телефонных номеровили любого другого платежного инструмента при совершении оплаты. Если вы обладаете сертификатом [PCI DSS](https://www.pcisecuritystandards.org/pci_security/) вы можете хранить данные карт на своей стороне, если нет — на стороне Gate. В этом случае Gate сохраняет данные, а также присваивает им уникальный идентификатор. Gate поддерживает ограничение максимального количества сохраненных платежных инструментов, которые может сохранить пользователь. **Прим.:** Для включения и настройки данной функциональности свяжитесь со службой технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). **Внимание:** Для сохранения и проведения оплаты по сохраненным данным обязательно передайте в запросе на оплату идентификатор пользователя id в объекте customer. ## Получение списка сохраненных платежных данных {#section_qf2_qsy_wbb .section} Дополнительно по запросу вы можете получить список сохраненных карт и других платежных инструментов пользователя и их данные; при этом номер карты передается в маскированном виде, CVV не передается. ## Создание запроса на получение списка сохраненных платежных средств {#section_h5b_zdn_jbb .section} **Прим.:** Отправьте запрос [/v2/customer/saved\_account/list](https://api-developers.ecommpay.com/api-specification/requests-for-customer-details/post-v2-customer-saved-account-list); метод отправки запроса — POST. В запросе укажите идентификатор пользователя, проект и платежный метод. После окончания обработки запроса вам придет ответ со списком сохраненных платежных инструментов пользователяв выбранной платежной системе или без него, если нет ни одного сохраненного в системе платежного инструмента. Для каждого сохраненного платежного средства в параметре account\_id илиcard\_id указывается его идентификатор в Gate. ## Удаление сохраненных платежных данных {#section_kdw_ysy_wbb .section} Если пользователь удаляет сохраненный платежный инструмент, отправьте запрос на удаление. Gate убирает такое платежное средство из списка сохраненных, но не удаляет его данные. **Прим.:** Если сохраненная платежная карта также имела токен, то токен также будет удален. Но сохраненная карта будет удалена, если вы деактивируете токен этой карты. Дополнительные сведения о токенах см. в [Использование токенов](ru_Gate_Token.md). ## Создание запроса на удаление платежных данных из списка сохраненных {#section_nh4_zdn_jbb .section} **Прим.:** Отправьте запрос [/v2/customer/saved\_account/delete](https://api-developers.ecommpay.com/api-specification/requests-for-customer-details/post-v2-customer-saved-account-delete); метод отправки запроса — POST. В запросе укажите идентификатор сохраненного инструмента. После окончания обработки запроса вам придет ответ с результатом удаления инструмента из списка сохраненных. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Использование токенов {#ru_Gate_Token .concept} статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением стандартизированных локальных токенов **Токен** \(**token**\) — уникальная, случайная последовательность из 64 символов, ассоциированная в Gate с определенной банковской картой и пользователем в подключенном проекте. Токен не содержит в себе конфиденциальной информации и может храниться в вашей системе, не вызывая угрозы нарушения стандартов безопасности по хранению данных по банковским картам. Через Gate вы можете создавать токены автоматически или по запросу и производить оплаты и выплаты по имеющимся токенам. ## Статусы токенов {#section_txw_jp2_zbb .section} Статус токена определяет возможность его использования для проведения оплат и выплат. |Статус|Описание| |------|--------| |active|Действительный токен, по которому могут проводиться оплаты и выплаты| |revoke|Токен был отозван, проведение операций по токену невозможно| |expiry|Срок действия токена истек, проведение операций по токену невозможно| ## Автоматическая генерация токена {#section_jrt_kzd_lbb .section} *Автоматическая генерация* токена происходит при проведении первой успешной оплаты или выплаты по банковской карте, а также при успешном холдировании средств. Сгенерированный токен \(token\) и время его создания \(token\_created\_at\) возвращаются в оповещении о проведении платежа. Дополнительные сведения об оповещении см. в разделе [Работа с оповещениями](ru_platform_callbacks.md). **Прим.:** Для включения автоматической генерации токенов свяжитесь со службой технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). ## Генерация токена по запросу {#section_emy_sg2_lbb .section} Другим способом генерации токена является отправка запроса на генерацию токена. В запросе передаются данные, необходимые для генерации токена. Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена. ## Создание запроса на генерацию токена {#section_vft_rzd_lbb .section} **Прим.:** Отправьте запрос [/v2/customer/card/tokenize](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-tokenize); метод отправки запроса — POST. В запросе укажите идентификатор проекта, данные пользователя и данные банковской карты пользователя. В оповещении вы получите токен банковской карты и время его создания. Подробнее см. в разделе [Работа с оповещениями](ru_platform_callbacks.md). ```language-javascript { "customer": { "id": "1707", "ip_address": "1.87.128.111", "project_id": 11, "signature": "LLmhbDKdNhNLT+Qkr2SzbLbFYNxC9sZLnQKkrTFYNN06NMPmZS/BfWGucWQVZ2WM3v5N709w==" }, "card": { "pan": "4314220000000056", "year": 2020, "month": 5, "card_holder": "PAUL SMITH" } } ``` ## Оплата по токену {#section_tz1_wrs_5bb .section} Gate позволяет пользователям осуществлять быстрые платежи с банковской карты, используя предварительно сгенерированный токен. При проведении оплаты по банковской карте, для которой уже существует токен, новый токен не генерируется. Если в этом случае была указана дата окончания срока действия карты, отличная от указанной при генерации токена, то токен не генерируется заново, срок действия токена обновляется в соответствии с указанной датой. Дополнительные сведения об оплатах с использованием токена см. в [Разовые оплаты](ru_Gate_purchase.md). ## Выплата по токену {#section_zyv_mc2_lbb .section} Gate позволяет осуществлять выплату средств на банковскую карту пользователя, используя предварительно сгенерированный токен. Дополнительные сведения о выплатах с использованием токена см. в [Выплаты](ru_Gate_payout.md). ## Получение данных карты по токену {#section_wzh_lqb_yfb .section} В случае необходимости получения данных банковской карты и информации о платежном инструменте, к которому привязана данная карта, вы можете отправить запрос в Gate. **Прим.:** Отправьте запрос [/v2/customer/card/bytoken](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-bytoken); метод отправки запроса — POST. В запросе укажите идентификатор проекта, пользователя и токен. В оповещении вы получите данные банковской карты в маскированном виде и другую информацию о данном платежном инструменте пользователя. ```language-javascript { "customer": { "project_id": 12, "id":"test_customer", "signature":"2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+BQjXWH6naCA9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q==" }, "token":"959c664ad64b8caa54bb7836ddc737fd1a3e6c7045679d71d89caff6c242a039" } ``` ``` { "account": { "id": 2932, "number": "431422******0056", "type": "card", "additional": { "country": "GB", "phone": "4314220000000056", "email": "john@gmail.com", "card": { "expiry": "01/20", "holder": "JOHN JOHNSON", "type": "visa" } }, "recurring_enable": false }, "token": "959c664ad64b8caa54bb7836ddc777fd1a3e6c704b59bd71d89caff6c242a039" }, "signature": "62kPxuCGqN4KDrxqqsuWnv0LOjdvUydWCxDmNPeq+AVW7/5UtLlmVL+SIyfbxot/Nf+47DEsAuW76DIgBg==" } ``` ## Проверка карты по токену {#section_qy3_fpt_wmb .section} Gate позволяет осуществлять проверку действительности карты пользователя, используя предварительно сгенерированный токен. Подробная информация о проверке с использованием токена представлена в разделе [Проверка платёжных инструментов](ru_gate_account_verification.md). ## Деактивация токена {#section_ozm_m1z_wbb .section} Токен может быть деактивирован в Gate в одном из следующих случаев: вы деактивируете токен или у банковской карты заканчивается срок действия. Вы можете, при необходимости, деактивировать токен из Gate, отправив запрос на деактивацию токена. Gate деактивирует токен. ## Создание запроса на деактивацию токена {#section_t5g_4ym_jbb .section} **Прим.:** Отправьте запрос [/v2/customer/card/token/revoke](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-token-revoke); метод отправки запроса — POST. В запросе укажите данные пользователя в вашей системе и токен, который необходимо деактивировать. После окончания обработки запроса вам придет оповещение с результатом деактивирования токена, включающий в том числе следующие параметры: project\_id, token, status, и token\_created\_at. ## Оповещение о создании или отключении токена {#section_rby_tt3_1cb .section} После выполнения запроса о создании или удалении токена, отправленного в конечную точку [/v2/customer/card/tokenize](https://api-developers.ecommpay.com/api-specification/token-operations/post-v2-customer-card-tokenize), платежная платформа возвращает оповещение с информацией о результате выполнения запроса. В следующей таблице приведен набор параметров, который содержится в таком оповещении. |Параметр|Описание| | |--------|--------|--| |general object, required |Объект с общими данными исходного запроса|1| |project\_id string, required |Уникальный идентификатор проекта|1-11| |customer\_id string, optional |Уникальный идентификатор пользователя в проекте|1-21| |signature string, required |Подпись оповещения|1-31| |request object, required |Объект с данными исходного запроса|2| |id integer, required |Уникальный идентификатор запроса|2-12| |action string, optional |Тип запроса. Возможны следующие варианты:- `tokenize` — запрос на создание токена; - `token_revoke` — запрос на отключение токена - **параметр отсутствует**— это означает, что токен деактивирован по истечению срока своего действия. Оповещение с отсутствующим параметром action инициируется в платежной платформе не по запросу, а автоматически, по истечении срока действия токена. |2-22| |status string, required |Статус запроса. Возможны следующие варианты:- `success` — запрос успешно выполнен; - `error` — во время выполнения запроса возникли ошибки. В этом случае в оповещение добавляется массив errors с подробной информацией об ошибках. |2-32| |errors array, optional |Массив объектов с информацией об ошибках. Присутствует в оповещении, только если в процессе обработки запроса возникли ошибки|2-42| |ErrorItem object, required |Объект с информацией об одной отдельно взятой ошибке|2-4-12-4| |code string, optional |Код ошибки|2-4-1-12-4-1| |message string, optional |Сообщение, уточняющее причину ошибки|2-4-1-22-4-1| |field string, optional |Параметр исходного запроса, в котором допущена ошибка, если этот параметр удалось локализовать |2-4-1-32-4-1| |token string, optional |Токен банковской карты пользователя. Токен генерируется автоматически при успешной оплате, если подключена соответствующая функциональность|3| |token\_created\_at string, optional |Дата и время генерации токена. Токен генерируется автоматически при успешной оплате, если подключена соответствующая функциональность. Пример: `2017-07-21T03:31:24+0000` |4| |token\_status string, optional |Статус токена. Пример: `active` |5| ```language-xml { "general":{ "project_id":12, "customer_id":cust_123, "signature":"\/gmTHcy5wvrFD4ISuWEiV8+nOa3aqnLnyJ\/AupOYkl9S5eLJZ", "request": { "id": "3c7f53fdbb5b8c96f9707457d75f", "action": "tokenize", "status": "success" }, "token":"2f0e75befacca30623354f9ffb0f44a80bee52982c39727b85039ef6f64309a1", "token_created_at":"2017-11-28 13:30:57", "token_status":"active" } ``` **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Работа с „сетевыми токенами“ карт платёжных систем Mastercard и Visa {#ru_gate_tokens} статья о возможности сохранять и использовать при работе через Gate платёжные данные пользователей с применением сетевых токенов карт платёжных систем Mastercard и Visa ## Общая информация {#section_u2p_3rk_mhc .section} Чтобы повысить удобство работы с данными платёжных карт и безопасность проведения платежей, отдельные платёжные системы обеспечивают возможности применения так называемых „сетевых токенов“. Каждый из таких токенов может быть получен только для карты соответствующей \(„родительской“\) платёжной системы и только через специализированный сервис этой платёжной системы, но в дальнейшем может применяться при работе с любыми эквайерами и провайдерами, поддерживающими работу с токенами этой платёжной системы. В платёжной платформе Ecommpay поддерживается проведение отдельных типов платежей с использованием токенов, сформированных в рамках сервисов сетевой токенизации Mastercard Secure Card on File \(SCOF\) и Visa Token Service \(VTS\)от платёжных систем Mastercard и Visa. Технически каждый из сетевых токенов этих платёжных системпредставляет собой последовательность из 16 символов, которая может использоваться в запросах вместо номера карты.При этом в случаях с изменениями сведений о карте, ассоциированной с сетевым токеном \(например, при перевыпуске карты\), такой токен не теряет действительности, поскольку его атрибуты автоматически обновляются в соответствующем сервисе. В рамках платёжной платформы Ecommpay использование сетевых токенов может быть актуальным в тех случаях, когда эти токены уже получены в сторонних сервисах и используются на стороне мерчанта. В остальных случаях можно использовать возможности по работе с токенами через Payment Page \([подробнее](ru_pp_token.md)\) и Gate \([подробнее](ru_Gate_Token.md)\), а также возможности переноса информации о локальных токенах от других эквайеров \([подробнее](ru_gate_data_migration.md)\). С вопросами, касающимися условий использования сетевых токенов и порядка подключения возможности работы с ними, можно обращаться к курирующему менеджеру Ecommpay, с техническими вопросами, касающимися аспектов применения сетевых токенов — к настоящей документации и специалистам технической поддержки Ecommpay. ## Особенности и ограничения {#section_h3w_krk_mhc .section} При проведении платежей с использованием сетевых токенов необходимо учитывать следующие особенности и ограничения. - Возможность применения сетевых токенов\(для всех поддерживаемых платёжных систем\) должна быть подключена для используемого проекта. В случае, если эта возможность не подключена для проекта, платежи с указанием сетевых токенов отклоняются с кодом ошибки 318. - Сетевые токены могут использоваться в ограниченном числе случаев, включая проведение разовых оплат в одну и две стадии, регистрацию и проведение повторяемых оплат с хранением платёжных данных на стороне веб-сервиса \([подробнее](ru_gate_payment_recurring_registration.md#section_smg_vqb_cjb)\) и проверку действительности карт. В других ситуациях, в частности при проведении оплат по платёжным ссылкам, при проведении повторяемых оплат с хранением данных в платформе или при проведении выплат, допустимо применять только те токены, которые сформированы непосредственно в платёжной платформе Ecommpay \([подробнее](ru_Gate_Token.md)\). - Управление сетевыми токенами \(в том числе их формирование, обновление и получение необходимых для их использования данных\) осуществляется через соответствующие специализированные сервисы. Для получения информации о порядке работы с такими сервисами можно обращаться к документации и специалистам этих сервисов. - Ответственность за корректное применение сетевых токенов и их атрибутов возлагается на мерчанта. При возникновении вопросов, связанных с ошибочным применением сетевых токенов, можно обращаться к курирующему менеджеру Ecommpay. ## Формат запросов {#section_dxw_lrk_mhc .section} При формировании запросов на проведение платежей с использованием сетевых токенов необходимо учитывать следующее: 1. Для инициирования каждого такого платежа должен использоваться отдельный POST-запрос к одной из следующих конечных точек: - для разовых одностадийных и для повторяемых оплат — [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale); - для разовых двухстадийных оплат — [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth); - для проверки действительности карты — [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification). 2. В составе объекта `card` вместо сведений о платёжной карте должны передаваться следующие сведения о токене: - `pan` — токен, сформированный в специализированном сервисесетевой токенизации; - `year` — порядковый номер года, в котором заканчивается срок действия токена\(в четырёхзначном формате `YYYY` по григорианскому календарю\); - `month` — порядковый номер месяца, в котором заканчивается срок действия токена\(в виде числа, без ведущего нуля\); - `card_holder` — имя держателя карты, если этот параметр обязателен для используемого проекта\(это имя должно указываться в соответствии с написанием на карте; исключить его из числа обязательных можно только по согласованию с курирующим менеджером Ecommpay после анализа и оценки рисков\); - `cvv` — код проверки подлинности карты \(обязательно во всех случаях, кроме проведения автооплат и регулярных оплат\). 3. В составе объекта `token_data` должны передаваться следующие параметры: - `token_type` — указатель типа токена со значением `network_token` \(обязательно для каждого платежа\); - `cryptogram` — код проверки подлинности токена, такой как Token Authentication Verification Value \(TAVV\), полученный в сервисе сетевой токенизации \(обязательно для платежей с регистрацией повторяемых оплат и необязательно для других платежей\); - `eci` — [индикатор ECI](ru_ECI_codes.md), соответствующий используемому токенуи полученный в сервисе сетевой токенизации \(обязательно для платежей с регистрацией повторяемых оплат и необязательно для других платежей\); - `trid` — идентификатор мерчанта, присвоенный при его регистрации в сервисе сетевой токенизации \(необязательно\). 4. Должен передаваться параметр `stored_card_type` с одним из следующих значений: - `1` для сохранения платёжных данных или для регистрации экспресс-оплаты, - `2` для проведения платежа с использованием сохранённых платёжных данных или для проведения экспресс-оплаты, - `3` для регистрации автооплаты, - `4` для проведения автооплаты, - `5` для регистрации регулярной оплаты, - `6` для проведения регулярной оплаты. Информация о работе с повторяемыми оплатами представлена в статье [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md). 5. В случае проведения повторяемой оплаты \(`stored_card_type` со значениями `2`, `4` или `6`\) с использованием карты, выпущенной в Европейской экономической зоне, должен передаваться параметр `scheme_id` — идентификатор операции, в рамках которой была зарегистрирована эта повторяемая оплата, на стороне международной платёжной системы \(Mastercard или Visa\). 6. Дополнительно могут использоваться любые другие параметры из указанных в спецификации используемой конечной точки API. ## Дополнительные материалы {#section_r4m_5vx_mhc .section} При работе с сетевыми токенами могут быть полезны следующие материалы: - [Разовые оплаты](ru_Gate_purchase.md)— статья о порядке проведения разовых одностадийных и двухстадийных оплат через Gate. - [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md)— статья о порядке проведения повторяемых оплат через Gate. - [Использование токенов](ru_Gate_Token.md)— статья о работе с внутренними токенами, формируемыми непосредственно в платёжной платформе. - [Перенос информации о повторяемых оплатах и токенах платёжных карт](ru_gate_data_migration.md)— статья о порядке переноса информации о повторяемых оплатах и локальных токенах от других эквайеров. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Перенос информации о повторяемых оплатах и токенах платёжных карт {#ru_gate_data_migration} статья о возможности переносить в платформу Ecommpay информацию о повторяемых оплатах и токенах платёжных карт от других эквайеров **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Общая информация {#ru_gate_data_migration_overview} В некоторых случаях для мерчанта может быть актуальным проводить через Ecommpay платежи с использованием платёжных данных, сохранённых ранее в сервисах других эквайеров. Для таких ситуаций в платёжной платформе Ecommpay поддерживаются различные возможности: - Переносить и использовать информацию о повторяемых оплатах \(как регулярных, так и нерегулярных\) и о токенах платёжных карт. Эта возможность описана в данной статье. - Проводить повторяемые оплаты, зарегистрированные в сервисах других провайдеров, без переноса информации о них в платформу. Для подключения и использования этой возможности необходимо обращаться к курирующему менеджеру Ecommpay. Перенос информации о повторяемых оплатах и токенах карт может быть предпочтителен в случаях, когда планируется использовать токены платёжных карт, совмещать использование платёжной платформы Ecommpay и сервисов других эквайеров, а также в случаях, когда требуется обеспечить автоматические списания в рамках повторяемых оплат. Такой перенос сведений не облагается комиссиями со стороны Ecommpay, но может облагаться комиссиями со стороны эквайера, передающего целевую информацию, и возможен только при поддержке с его стороны и при соблюдении ряда условий \(подробнее — далее\).С вопросами об организации такого переноса, как и с вопросами о возможности переноса информации в обратном направлении, от Ecommpay к другим эквайерам, можно обращаться к курирующему менеджеру Ecommpay. В целях обеспечения конфиденциальности информации её следует переносить в зашифрованном виде. Как правило, при переносе данных в платформу Ecommpay используется алгоритм шифрования PGP \(Pretty Good Privacy\), но в некоторых случаях по согласованию со специалистами Ecommpay могут применяться и другие способы \(например, если на стороне эквайера, передающего информацию, не поддерживается PGP-шифрование\). Для переноса информации файл с ней должен быть зашифрован на стороне текущего эквайера, от которого выполняется перенос, с использованием открытого ключа от Ecommpay \(в случае PGP-шифрования\), а затем передан специалистам Ecommpay. Контактную информацию ответственных специалистов можно получить у курирующего менеджера Ecommpay. После того, как вся необходимая информация перенесена в платёжную платформу Ecommpay и её корректность подтверждена со стороны мерчанта, с целевыми повторяемыми оплатами и токенами можно выполнять любые действия, доступные в платформе: списания в рамках повторяемых оплат \([подробнее](ru_Gate__cof_merchant_side.md)\) и управление этими списаниями \([подробнее](ru_gate_payment_recurring_manage.md)\), оплаты и выплаты по токенам \([подробнее](ru_Gate_Token.md)\), проверку действительности карт \([подробнее](ru_gate_account_verification.md)\) и так далее. При этом всю информацию об операциях, выполненных через платёжную платформу Ecommpay с использованием перенесённых сведений, можно получать через интерфейс Dashboard\(в разделе **Платежи**, с информацией обо всех платежах, и в разделе **Подписки**, с информацией о регулярных оплатах\), а также [Data API](ru_dbl_api_protocol.md) и Gate API. **Прим.:** Стоит учитывать, что для выполнения каких-либо действий с перенесённой информацией должны использоваться новые идентификаторы, зафиксированные в платформе Ecommpay: - токены карт, указываемые в параметре `token`, - идентификаторы платежей, указываемые в параметре `payment_id`, - идентификаторы серий списаний, указываемые в параметре `id` объекта `recurring`. Эти идентификаторы включаются в сверочный файл, отправляемый специалистам мерчанта для проверки и согласования корректности перенесённой информации, и все они применимы только в паре с идентификатором проекта \(`project_id`\), к которому изначально отнесены. ## Условия и ограничения {#ru_gate_data_migration_restrictions} При переносе информации необходимо учитывать условия и ограничения, которые выдвигаются с двух сторон: эквайером, предоставляющим информацию, и Ecommpay, принимающим её в платформу. Со стороны Ecommpay это следующие условия и ограничения: - Переносимая информация может относиться только к картам платёжных систем American Express,Mastercard и Visa. Для работы по картам других платёжных систем следует формировать токены и регистрировать повторяемые оплаты непосредственно в платформе, используя поддерживаемые для этого способы. - Перенос допускается только напрямую от других эквайеров. При работе через посредников следует оговаривать с ними возможности взаимодействия непосредственно с эквайерами. - Перенос возможен только в рамках рабочих проектов взаимодействия с платёжной платформой Ecommpay. Если мерчант ещё не является клиентом Ecommpay, то с его стороны следует отправить [заявку](https://ecommpay.com/sign-up/) на подключение к платформе и решить последующие вопросы. - Ответственность за актуальность и корректность перенесённой информации возлагается на мерчанта. После переноса специалистам мерчанта направляется сверочный файл, и если специалисты мерчанта подтверждают корректность информации в этом файле, то эта информация признаётся рабочей и ответственность за любые негативные последствия \(например, оформление опротестования из-за списания средств не с того пользователя\) возлагается на мерчанта. - Ответственность за отсутствие двойных списаний возлагается на мерчанта. Перед началом переноса специалисты Ecommpay согласовывают со специалистами мерчанта дату начала проведения платежей с использованием полученной информации. Чтобы избежать двойных списаний \(через двух эквайеров\), со стороны мерчанта следует обеспечить к указанной дате завершение всех операций с использованием переносимой информации через прежнего эквайера. ## Порядок переноса {#ru_gate_data_migration_workflow} Перенос информации о повторяемых оплатах и токенах осуществляется по зашифрованному каналу связи, который настраивается в рамках взаимодействия специалистов Ecommpay и текущего эквайера, передающего информацию. Сроки такого переноса, как правило, составляют не более недели для токенов и не более двух недель для повторяемых оплат. Эти сроки зависят от различных факторов, в том числе от того, требуется ли вместе с основными параметрами переносить дополнительные, и согласовываются непосредственно в процессе взаимодействия всех сторон. В случаях, когда информация о токенах переносится раньше и необходима для проведения платежей уже до переноса информации о повторяемых оплатах, можно согласовывать её более раннее применение со специалистами Ecommpay. В общем случае со стороны мерчанта следует: 1. Согласовать возможность и условия переноса с эквайером, от которого актуально перенести целевую информацию. 2. Сообщить курирующему менеджеру Ecommpay о желании перенести информацию и согласовать с ним сроки переноса и дату начала проведения платежей с использованием перенесённой информации. В случае, если мерчант ещё не входит в число клиентов Ecommpay, предварительно следует отправить [заявку](https://ecommpay.com/sign-up/) на подключение и решить последующие вопросы. 3. Согласовать со специалистами Ecommpay следующее: - Проекты, для которых актуален перенос информации. Если необходимо перенести информацию для нескольких проектов в платформе Ecommpay, то перенос осуществляется для каждого проекта отдельно. - Состав параметров, которые следует перенести в платёжную платформу Ecommpay. Это могут быть только основные параметры, описанные [далее](ru_gate_data_migration.md) и переносимые в обязательном порядке, или, если актуально, основные вместе с выбранными дополнительными \(из числа поддерживаемых в платформе\). - Если необходимо перенести информацию о повторяемых оплатах — идентификаторы, которые следует присвоить этим оплатам\(в качестве значений параметра `scheduled_payment_id`\), а также записям о сериях списаний в рамках этих оплат\(в качестве значений параметра `register_payment_id`\). Это могут быть значения в формате, используемом по умолчанию \(`Ecommpay–yyyymmddnnn`\), или в форматах, заданных мерчантом \(с ограничением в 255 символов\). - Состав параметров, которые следует использовать для проверки специалистами мерчанта того, что целевая информация перенесена в платформу корректно и может использоваться при проведении платежей. В число этих параметров обязательно включаются новые идентификаторы \(`token` и `recurring_id`\), параметры из числа основных, отмеченные далее как required for verification, и, если актуально, дополнительные параметры из числа перенесённых. - Контактную информацию ответственных специалистов мерчанта, эквайера, от которого необходимо получить информацию, и Ecommpay— для организации взаимодействия и решения актуальных вопросов, в том числе по согласованию корректности перенесённой информации. 4. В случае, если не обеспечивается прямое взаимодействие между специалистами текущего эквайера и Ecommpay, получить от эквайера зашифрованный файл и направить его ответственным специалистам, чью контактную информацию можно получить у курирующего менеджера Ecommpay. Как правило, перенос данных в платформу Ecommpay выполняется с помощью алгоритма шифрования PGP \(Pretty Good Privacy\) и открытого ключа от Ecommpay, но в некоторых случаях по согласованию со специалистами Ecommpay могут применяться и другие способы. ``` -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBF6dl0kBEADFrBtqZ7gXwTxPZXKFFJNPtickNW2lj7TigR+ymGR8ym+AOb9k /IJp7Ua7Rgw6vFD/puLdGv7RFIbMYtqGnQgBzN4b+TFVqUtLST4cL8vR3S5tvYof /YYY9PuqGaLWYdtg9PYtTQREe19gKhZPVi9PVjpnYLwnqGZnKYD9f76b8seQGUNS RMJ9RA2VjwLq0GcOP2k4s3pnNN+GJFdS/z/RAfBwyT++681irmXgVWOq//3yIkya WGRkVb+weY0Z3aoK++piMR55xr76l8aukOxb3ULJd1N5zhYMWACzZglla47rtCkC rWw2Y8aC/DVbU7+NLtyr58LlXs7CbOpbfMIt59VfM2vrt4JtPF/F+u+ahBqJ5g0j 8aM0fhZASeS6m/1FRXAR6ArUIEuILlW91xk6C2nRNcnnrbm7uSTiWAaCrV719lSm h/DlNVubFjgsTZ+KbkCjsPza2q6QQc8PCzhWhu7cmxmQKVL1l17+tujQvxa5x74N 9T4aizoOGXhZEKm33cReCGEga30WdZFstB1sfjDcNhxbBsHYPu15iVMDpo8BQSeb 5Gt/rQD7Q0uk6IgwMfuuICCCsF695hUFRK7dvQUNEHB5biWrCec7Yl40XaY0EDMy 0s3J/Niha049jT7Z+/RSqrv53BftdyI+UVJKn9rAGdKeiMPC31tAjCRW9QARAQAB tBppdHNlYyA8aXRzZWNAZWNvbW1wYXkuY29tPokCTgQTAQgAOBYhBFe/BlX1+HSg v2i/PfBgfCmIRnw0BQJenZdJAhsDBQsJCAcCBhUKCQgLAgQWAgMBAh4BAheAAAoJ EPBgfCmIRnw0v2wP/RGy9jAseKPNOk1NyEbuMTP7F3O/sYfgLKzMpl6TPp6q11Xn TPnepkukszZtn4ZwBV16fl5dcXXfM8gvfXgKgtBKr6XzNU9lTfGqTLcQJ5OzSSGY e7zxhE2NtQQmMVyARC4y+BzIYjyzn6ekVNh0lI61ZhluimSm+BWnm1TcE/ASS7a9 ddI+FA93iupb/0l9EIZHn0tyf/+uj3SnMspCV8fFVDxSuTggbdOsZsfMa9MCXrHD 2HYY2EfMhgVkDh+LvInrhAzgWLJmGiyS5VT6+v6hs3xpyILQUsi1SbVkPdF7jBiy LknMHj5AGmL5uIWANVLT/BMgyhUksuadqpo91O0KZf8K4c3PvToHw7UOQ7me15G0 4mpInCNqPzaAz655Jc3eeUmJHGybTEUFX7MBlx/Fqvj7aTNIFStH7FPQq+a5HDGl 5Y9jIfTFBwVCb4ngETERE6j/b8K+TCHGXo87t+OmMdxNc2vSSOWmM9c/PSlsKKCH Y2y78m3T2WpWwrhw7QYNpAhdPw4dVqGLcjXqFAhxcv4BAeaRYZwiqNdNNIq17Gch N6e7e8emPwFip0+ok5PLMDvfAfE3/LeoAfU+QCbaMticklgojxmWZAGU2nzoe9tq 95jiDf1Rif4qJaixoTEoGaezBVcA73BW5zDRLbkppeCCT4pVUgpfTvJBAJknuQIN BF6dl0kBEADLNI2mOwmFWlvgKRUAtpbdaqmaTTmsVyoVl0VpLnOKnAxQDTReSfcV 7G4NS0bSwnNIlxQsbtq5hUKsz/HYOS5fMvgFRIORUosOR80+Zz1QjGRC/UvWHoKs qsAs5vKRqhMOtQ+1KxYEhsyy8PZKBUgqo31q9FWkmgjR7urzlidRocutTI5vHNTR MODrjrhlPJ8nTp30935oFCML4eJXDV3eQWmCM9LahVj9bbSqGungdPafHPP1DLVR AUg+EONUW2/jM0jZwoJxafUBT3Is6XcLNNtB6DlX2N4ITOxE23CLl6B1M54gwTiv iF1bGV13h4K0XxrsQqw6OEX8K4B3MPd468NJn5GCoinGtMBQFT3uv6mzxTxtyVaG EI9H6i5ElAAIL7BqlbQI/ad40PVwe7mWWP0k8GawAf6y1298hPbkIhOvEjnMyKiv HpOWrnDEQPxKUvvjrh8n83r4yQWRI77vT3OYKbmQbEESsJgZnmMwJpjBswKjuwwm Td+7V45e0dL9YC6XQfIwV8VZugdYueuAVX5m4IdebzJQst8uvPXM2SH4jW44cDhs pw0Zs+++frCjoYw4PnNtVeZ2BBRGIyylCQxirNtyeEzd5lO2p04KmYJcCO79wmAM ZdkEeohh52SMe3xz/HrfrOZXdFeu83Cx/TMEzAbeGgf9SNTOfdViIQARAQABiQI2 BBgBCAAgFiEEV78GVfX4dKC/aL898GB8KYhGfDQFAl6dl0kCGwwACgkQ8GB8KYhG fDSANg/8CFHIoWGGro7Wh//k8pNsfzdpUZPj4kNuKB2Hl/17Lj5Tz0ziQWis7uSI 11pf+u0GttJ8MxzBn4XAnvvMA+LozoAu9i9OKMLrGAplr2EsMRBFA8+tMeZFdUmt pDA3bVCIp12/ERsxhzhd7eN6M0g/JxXkDKhvHTsDlsAJF+T+xeDPgQu+ejrKB8bb 2fCIv1Ru6UNSCJ32ZbtEF9MlkODSumD+gVPQddM5E2OUmbuE02wFOcN7vGx2mAa6 6HWUv2gK/FX8id82RSWkEvlV12xLu/BDWaSKddemBX357iwC3ho6EsWovbZfhFsw Yrw8WTz4eYOVw9rm4jbX82vCiztN8snrdx5vZ2H/F/0jAHB1YHLReFdsLAdRGfj6 6MolppVGjCal/Q/JkqPQQpWGy3oSo3TbpbqKrWqaGTDWnb8+enocfBM5pjIo+Y3w diofU0meiCGgQs32LhuJV6kraUakYa0CEyhNeyVVqPPqUg8mqC/CEs12bExABEDI +3q6nA8OivWShBLVvmuKMYbQnO874VHJ0IF60sX6a5FIGi31QS2efcxYCcVD6sCU WD2s88/xYedyDNHWaUfl+fi9+7FRPhKixB2TlzARWN5m5D1Jc3rsZ/NlXfEk0m6j Xfgysvyy0abRlDIfFHv87ICIc8kNWtn4mIw9a6jbSDpAT/+16eQ= =jMHf -----END PGP PUBLIC KEY BLOCK----- ``` 5. При получении от специалистов Ecommpay по указанному адресу электронной почты сверочного файла проверить полноту и корректность информации в нём. **Прим.:** В сверочный файл включается информация по всем согласованным параметрам, при этом сам файл передаётся в формате CSV, а пароль для доступа к нему отправляется отдельно. Кроме того, если это было согласовано на шаге 2, могут составляться и отправляться отдельные сверочные файлы для токенов и повторяемых оплат. 6. Сообщить \(ответным письмом\) специалистам Ecommpay о корректности информации или о выявленных несоответствиях. В первом случае \(если сведения в файле актуальны и корректны\) после этого можно приступать к использованию перенесённой информации. Во втором случае \(если обнаружены несоответствия или ошибки\) специалисты Ecommpay сверяют информацию из файла с информацией, полученной от прежнего эквайера, и \(если информация не совпадает\) исправляют её по согласованию с мерчантом или \(если информация совпадает\) рекомендуют обратиться к прежнему эквайеру для её актуализации, а затем сообщить специалистам Ecommpay актуальные сведения. **Прим.:** Проведение платежей через платформу Ecommpay с использованием перенесённой информации возможно только после получения от мерчанта подтверждения корректности всех сведений. 7. Настроить на стороне веб-сервиса использование актуальной информации. Так, для работы с токенами целесообразно обновить их значения \(на сформированные в платёжной платформе\), а для работы с повторяемыми оплатами — настроить использование новых идентификаторов платежей и списаний. После этого можно полноценно работать с перенесённой информацией. В следующих разделах представлена информация об основных параметрах, которые используются при переносе информации.Для настройки дополнительных параметров следует обращаться к курирующему менеджеру Ecommpay. ## Состав параметров для повторяемых оплат {#ru_gate_data_migration_cof_parameters} При переносе информации о повторяемых оплатах используются следующие основные параметры. ### Идентификаторы проекта и пользователя {#section_n5v_cdl_2xb .section} |Параметр|Описание| |--------|--------| |`project_id`|Идентификатор проектав платёжной платформе Ecommpay, к которому относится переносимая информация. Пример: `42` | |`customer_id` [required for verification](ru_default_for_verification.md) |Идентификатор пользователя в веб-сервисе.Должен представлять собой строку длиной не более 255 символов. Пример: `customer_17008` | ### Сведения о платёжной карте {#section_nbw_hdl_2xb .section} |Параметр|Описание| |--------|--------| |`pan` [required for verification](ru_default_for_verification.md) |Номер платёжной карты.Переносится между эквайерами в явном виде, но в сверочном файле указывается в маскированном виде в параметре `card_number`. Пример: `4314220000000056` | |`card_holder`|Имя держателя карты, в соответствии с указанным на карте и с учётом используемых [ограничений](ru_faq_payment_processing.md). Пример: `SONYA KOVALEVSKY` | |`card_expiration_month`|Порядковый номер месяца, в котором истекает срок действия карты, в виде числа от 1 до 12. Пример: `5` | |`card_expiration_year`|Порядковый номер года, в котором истекает срок действия карты, в формате `ГГГГ`. Пример: `2025` | |`card_type`|Указатель бренда платёжной карты со следующими вариантами значений: - `amex` — American Express - `maestro` — Maestro - `mastercard` — Mastercard - `visa` — Visa | ### Основные сведения о повторяемой оплате {#section_ydp_ldl_2xb .section} |Параметр|Описание| |--------|--------| |`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`|Статус записи о серии списаний\([подробнее](ru_gate_payment_recurring_registration.md)\): - `active` — ожидаются дальнейшие списания - `canceled` — дальнейшие списания отменены Если этот параметр не указан, серии присваивается статус `active` | |`recurring_type`|Указатель типа повторяемой оплаты\([подробнее](ru_Gate__saved_cards_payments_type.md)\): - `U` — автооплата - `R` — регулярная оплата | ### Параметры регулярных списаний {#section_kym_ydl_2xb .section} |Параметр| | |--------|--| |`amount` [required for verification](ru_default_for_verification.md) |Сумма однократного списания. В дробных единицах валюты, если они применимы.В сверочном файле указывается в параметре `recurring_amount`. Пример: `999` | |`currency` [required for verification](ru_default_for_verification.md) |Код валюты списаний в формате ISO 4217 alpha-3.В сверочном файле указывается в параметре `recurring_currency`. Пример: `USD` | |`start_date` [required for verification](ru_default_for_verification.md) |Дата, с которой необходимо начать списания после переноса информации в платформу, в формате `dd-mm-yyyy`. Пример: `01-06-2023` | |`start_time` [required for verification](ru_default_for_verification.md) |Время, в которое следует выполнять списания, в формате `hh–mm–ss`. Пример: `15-00-00` | |`period` [required for verification](ru_default_for_verification.md) |Период, используемый как единица расчёта при определении интервала списаний\(чтобы задавать списания по регулярной оплате каждые *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` | ## Состав параметров для токенов {#ru_gate_data_migration_token_parameters} При переносе информации о токенах используются следующие основные параметры. |Параметр|Описание| |--------|--------| |`project_id`|Идентификатор проектав платёжной платформе Ecommpay, к которому относится переносимая информация. Пример: `42` | |`customer_id` [required for verification](ru_default_for_verification.md) |Идентификатор пользователя в веб-сервисе.Должен представлять собой строку длиной не более 255 символов. Пример: `customer_17008` | |`pan`|Номер платёжной карты.Переносится между эквайерами в явном виде. Пример: `4314220000000056` | |`card_holder`|Имя держателя карты, в соответствии с указанным на карте и с учётом используемых [ограничений](ru_faq_payment_processing.md). Пример: `SONYA KOVALEVSKY` | |`card_expiration_month`|Порядковый номер месяца, в котором истекает срок действия карты, в виде числа от 1 до 12. Пример: `5` | |`card_expiration_year`|Порядковый номер года, в котором истекает срок действия карты, в формате `ГГГГ`. Пример: `2025` | |`card_type`|Указатель бренда платёжной карты со следующими вариантами значений: - `amex` — American Express - `maestro` — Maestro - `mastercard` — Mastercard - `visa` — Visa | ## Дополнительные материалы {#ru_gate_data_migration_links} При использовании возможности переноса информации о повторяемых оплатах и токенах платёжных карт могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— статья с общей информацией о взаимодействии с платёжной платформой через Gate. - [Повторяемые оплаты](ru_Gate__payments_on_saved_data.md)— группа статей о работе с повторяемыми оплатами. - [Использование токенов](ru_Gate_Token.md)— статья с информацией о работе с токенами платёжных карт. - [Контроль и проведение платежей](ru_dbl_payments.md)— статья с информацией о проведении и контроле проведения платежей и операций через Dashboard. - [Спецификация Gate API](https://api-developers.ecommpay.com/)— спецификация интерфейса Gate API. --- # Проведение оплат MO/TO {#ru_Gate_moto .concept} статья о возможности проводить через Gate оплаты с получением платёжных данных пользователей по электронной почте, телефону и иным каналам связи Mail Order/Telephone Order \(MO/TO\) платеж — это CNP \(card-not-present\) платёж, при котором для осуществления операции держатель платёжной карты передает мерчанту её реквизиты в письменном виде или по телефону. ## Типы платежей, поддерживающие проведение MO/TO {#section_c22_lkx_y2b .section} Типы операций, поддерживающие проведение MO/TO оплаты: - оплата с прямым списанием средств — [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale); - оплата с прямым списанием средств по сохранённым данным — [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved); - оплата с прямым списанием средств по токену — [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token); - оплата с блокировкой средств — [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth); - оплата с блокировкой средств по сохранённым данным — [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved); - оплата с блокировкой средств по токену — [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token); - проверка действительности платёжной карты по её номеру — [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification); - проверка действительности платёжной карты по токену, ассоциированному с картой — [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token). ## Проведение MO/TO оплат через Gate {#section_ncq_xfx_y2b .section} Платежи MO/TO отличаются от обычных тем, что необходимые для составления расчётного документа реквизиты платёжной карты сообщаются её держателем по почте, телефону, факсимильной или иной связи. MO/TO платежи являются подвидом CNP-платежей, при совершении которых физически не присутствуют платёжная карта и её держатель. Для проведения MO/TO оплаты необходимо в запросе в Gate в объекте payment передать одно из значений в параметре moto\_type: - значение `1` для проведения оплаты Mail Order \(MO\); - значение `2` для проведения оплаты Telephone Order \(TO\). ## Передача параметра `cvv` {#section_ct3_jkx_y2b .section} Если moto\_type=`1`, то для банковских карт Mastercard, Visaи American Express параметр cvv в объекте card становится необязательным. Для всех остальных карт параметр остаётся обязательным. Если moto\_type=`2`, то для карт Mastercardи American Express параметр cvv в объекте card становится необязательным. Для всех остальных карт параметр остаётся обязательным. ## Ограничения проведения MO/TO оплаты {#section_bjj_dlh_jfb .section} Для проведения MO/TO оплаты по картам Maestro действует ограничение: страна, на территории которой проводится операция, должна совпадать со страной, выпустившей карту, а также входить в список доступных стран. В случае если данные условия не выполнены, выполнение операции отклоняется. Список стран, доступных для проведения MO/TO оплат по картам Maestro, представлен в следующей таблице: |IRL|Ирландия| |FRA|Франция| |GBR|Великобритания| |TUR|Турция| **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Оценка достоверности имён держателей карт {#ru_gate_cardholder_name_verification} статья о возможности сверять написания имён держателей карт с зафиксированными у эмитентов при работе через Gate ## Общая информация {#section_zq3_2q2_zhb .section} В случаях, когда необходимо проверять действительность платёжных карт, можно дополнительно сверять написание имени держателя определённой карты с тем, которое зафиксировано у эмитента. В рамках платёжной платформы Ecommpay такая возможность поддерживается для карт платёжных систем Mastercard и Visa и включает в себя проверку в специализированных сервисах этих систем — Name Validation Service\(NVS\) для карт Mastercard и Account Name Inquiry\(ANI\) для карт Visa. Проверка имёнможет быть актуальна в разных ситуациях \(например, перед проведением выплат или при работе с нетипичными заказами\) и позволяет дополнительно оценивать риски мошенничества и опротестования платежей. Она применима для классических карточных платежей и методов Apple Pay и Google Pay, а также при работе с сервисами Mastercard MoneySend и Visa Direct. Использование этой возможности вписывается в схемы проверки действительности платёжного инструмента \([подробнее](ru_gate_account_verification.md)\) и не требует со стороны веб-сервиса каких-либо дополнительных действий помимо работы с расширенным составом параметров в запросах и оповещениях \(подробнее [далее](ru_gate_cardholder_name_verification.md#section_rpp_v14_3fc)\). Для подключения этой возможности следует обращаться к курирующему менеджеру Ecommpay. ## Особенности и ограничения {#section_td5_kdj_5yb .section} При использовании оценки достоверности имён держателей карт стоит учитывать следующие особенности и ограничения: - Оценка может выполняться только в тех случаях, когда эмитент карты поддерживает интеграцию с соответствующим сервисом платёжной системы. - Со стороны эмитентов могут действовать различные правила оценки, которые могут допускать проверку только на полное соответствие имени или на полное и частичное соответствие. - Информация о степени соответствия имени может интерпретироваться только как справочная.Решение о проведении или отклонении платежей с учётом этой информации в каждом случае остаётся за мерчантом. - За каждое выполненное сопоставление имени со стороны платёжной системы взимается комиссия.В случаях, когда оценка была инициирована, но выполнить её не удалось, комиссия не взимается. Информацию об актуальных тарифах на сопоставление имён можно уточнять у курирующего менеджера Ecommpay. - Технически со сведениями от эмитента сопоставляются сведения, указанные в запросе на проверку действительности карты, в параметрах `first_name`, `middle_name` и `last_name` объекта `customer`. При этом для каждого из этих параметров сопоставляются только первые 35 значимых символов, исключая специальные символы и пробелы. - Информация о результате сопоставления передаётся к веб-сервису в итоговом оповещении о результате проверки действительности карты— в виде индикатора в параметре `name_validation_result` объекта `operation`. ## Формат запросов {#section_rpp_v14_3fc .section} При формировании запросов на проверку действительности карты с дополнительной проверкой имени её держателя необходимо учитывать следующее: 1. Для инициирования каждой проверки должен использоваться отдельный POST-запрос к одной из следующих конечных точек: - для проверки по реквизитам карты, указанным в явном виде — `/v2/payment/card/account_verification` \([подробнее](ru_gate_account_verification.md)\); - для проверки по токену, ассоциированному с картой — `/v2/payment/card/account_verification/token` \([подробнее](ru_gate_account_verification.md)\); - для проверки с использованием сервиса Apple Pay — `/v2/payment/applepay/account_verification` \([подробнее](pm_applepay.md)\); - для проверки с использованием сервиса Google Pay — `/v2/payment/googlepay/account_verification` \([подробнее](pm_googlepay.md)\). 2. В каждом запросе в составе объекта `customer` должны передаваться следующие параметры: - `first_name` — имя пользователя \(обязательно\); - `middle_name` — отчество, второе или среднее имя пользователя \(при указании со стороны пользователя\); - `last_name` — фамилия пользователя \(обязательно\); - `name_validation` — указатель необходимости проверки имени держателя \(обязательно, со значением `true`\). 3. Дополнительно могут использоваться любые другие параметры из указанных в спецификации используемой конечной точки API. ``` {#codeblock_dxp_wqx_jfc .language-json} { "general":{ "project_id":874, "payment_id":"15538406111", "signature":"1wR1YgD5PxxTIJfQ==" }, "customer":{ "ip_address":"192.0.2.0", "id":"customer_10", "first_name":"John", "middle_name": "Jr", "last_name": "Doe", "name_validation": true //указатель необходимости проверки имени }, "payment":{ "amount":0, "currency":"USD" }, //с указанием реквизитов платёжного инструмента (по спецификации) } ``` ## Формат оповещений {#section_gq3_n12_pfb .section} Для итоговых оповещений о проверке платёжного инструмента вместе с оценкой достоверности имени держателя карты используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом в объекте `operation` в таких оповещениях дополнительно передаётся параметр `name_validation_result` с индикатором результата сопоставления. Этот параметр может принимать следующие значения: - `A` — при полном соответствии сведений, представленных в запросе, со сведениями на стороне эмитента. - `B` — при частичном соответствии сведений, представленных в запросе, со сведениями на стороне эмитента. - `C` — при полном несоответствии сведений, представленных в запросе, со сведениями на стороне эмитента. - `U` — при невозможности сопоставления\(из-за того, что оно не поддерживается со стороны эмитента, или из-за возникших ошибок\). В следующем примере в параметре `name_validation_result` содержится индикатор полного совпадения \(`A`\). ``` {#codeblock_dd2_1tx_jfc .language-json} { "project_id":874, "payment":{ "id":"15538406111", "type":"account_verification", "status":"success", "date":"2024-09-10T13:45:59+0000", "method":"card", "sum":{ "amount":0, "currency":"USD" }, "description":"Добавить карту" }, "account":{ "number":"431422******0056", "token":"844f84f3bdfaf2ddf006c96ffaddc09394c5d0e158f", "type":"visa", "card_holder":"JOHN DOE", "id":8861226, "expiry_month":"09", "expiry_year":"2028" }, "customer":{ "id":"customer_10", "first_name":"John", "middle_name":"Jr", "last_name":"Doe" }, "recurring":{ "id":10505, "currency":"USD", "valid_thru":"2025-09-30T00:00:00+0000" }, "operation":{ "id":4314220000000056, "type":"account verification", "status":"success", "date":"2024-09-10T13:45:59+0000", "name_validation_result": "A", //индикатор результата сопоставления "created_date":"2024-09-10T13:45:57+0000", "request_id":"5cb898347e62b2c1-52dac6c8c", "provider":{ "id":120, "payment_id":"306449667", "date":"2024-09-10T13:45:59+0000", "auth_code":"188591", "endpoint_id":120 }, "code":"0", "message":"Success" }, "signature":"P9g0U+eF2QWs2A==" } ``` ## Дополнительные материалы {#section_d55_sxv_chd .section} При работе с оценкой достоверности имён держателей карт могут быть полезны следующие материалы: - [Проверка платёжных инструментов](ru_gate_account_verification.md)— статья о порядке условных списаний или блокировок средств с целью проверки действительности платёжных инструментов через Gate, включая информацию о том, какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. - [Классические карточные платежи](ru_pm_card_payments.md)— краткая сводка с основными сведениями о платежах с прямым использованием платёжных карт в контексте платёжных методов. - [Apple Pay](pm_applepay.md)— статья о работе с платёжным методом Apple Pay, включая информацию о том, какие запросы и оповещения актуальны при проверке действительности платёжных инструментов этим методом через Gate. - [Google Pay](pm_googlepay.md)— статья о работе с платёжным методом Google Pay, включая информацию о том, какие запросы и оповещения актуальны при проверке действительности платёжных инструментов этим методом через Gate. - [Использование сервисов Mastercard MoneySend и Visa Direct](ru_gate_money_transfer_services.md)— статья о возможностях проведения денежных переводов в рамках специализированных сервисов от платёжных систем Mastercard и Visa. - [Работа с оповещениями](ru_platform_callbacks.md)— статья о работе с программными оповещениями, позволяющими максимально оперативно получать значимую информацию о проведении каждого платежа. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Использование сервисов Mastercard MoneySend и Visa Direct {#ru_gate_money_transfer_services} статья о возможности проводить денежные переводы между пользователями и мерчантами в рамках сервисов Mastercard MoneySend и Visa Direct при работе через Gate **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Общая информация {#ru_gate_money_transfer_services_overview} В платёжной платформе Ecommpay поддерживается возможность использования сервисов Mastercard MoneySend и Visa Direct, которые упрощают проведение денежных переводов между пользователями и мерчантами. В рамках этих сервисов доступны операции, позволяющие *списывать* средства с пользователей-„отправителей“ и *зачислять* средства пользователям-„получателям“.Такие списания и зачисления могут выполняться по отдельности и в различных комбинациях, при этом поступление средств на целевые счета согласно требованиям платёжных систем должно занимать не более 30 минут, что обеспечивает довольно высокую скорость переводов и удобство пользователей. Основные свойства этих операций можно представить следующим образом. | |Списание|Зачисление| |:-|:-------|:---------| |Операция в сервисе Mastercard MoneySend|Funding transaction \(FT\)|Payment transaction \(PT\)| |Операция в сервисе Visa Direct|Account Funding Transaction \(AFT\)|Original Credit Transaction \(OCT\)| |Техническая операция в платформе Ecommpay|`sale`|`payout`| |Допустимые платёжные методы|- Карточные платежи - Apple Pay - Google Pay |Карточные платежи | |Допустимые платёжные инструменты пользователей|Платёжные карты Mastercard или Visa|Платёжные карты Mastercard или Visa| |Возможность отмены операции после её выполнения|+\(с ограничениями по времени\) |–| |Примеры использования|- Пополнение пользовательского счёта в сервисе мерчанта - Первая часть перевода с карты на карту \(со списанием средств со счёта отправителя\) |- Выплата средств пользователю - Вторая часть перевода с карты на карту \(с зачислением средств на счёт получателя\) | Поскольку в платформе Ecommpay эти операции выполняются как `sale` и `payout` \(с определённым набором параметров\), для их инициирования могут использоваться любые подходящие интерфейсы: для оплат не только Gate, но и Payment Pageи SDK для мобильных приложений, а для выплат Gate и Dashboard. По вопросам, касающимся ограничений в применении сервисов Mastercard MoneySend и Visa Direct и подключения к ним, можно обращаться к курирующему менеджеру Ecommpay. ## Схемы выполнения операций {#ru_gate_money_transfer_services_workflow} ### Общий порядок работы {#section_odv_vwj_5wb .section} Схемы работы с отдельными операциями списаний и зачислений при работе через Gate в целом соответствуют схемам проведения [одностадийных оплат](ru_gate_payment_sale.md) и [выплат](ru_Gate_payout.md): со стороны веб-сервиса по каждой операции необходимо отправить соответствующий запрос, выполнить, если потребуется, промежуточные действия согласно предписывающим оповещениям от платформы и принять итоговое уведомительное оповещение. При этом для перевода средств с карты на карту необходимо последовательно инициировать две операции — сначала операцию списания и после её выполнения операцию зачисления. ### Способы указания платёжных реквизитов {#section_t3p_2xj_5wb .section} Как и с другими видами оплат и выплат в платёжной платформе Ecommpay, приработе со списаниями и зачислениями в рамках сервисов Mastercard MoneySend и Visa Direct можно использовать разные способы указания реквизитов платёжных карт. Это: - *Реквизиты* \(в явном виде\)— с указанием номера карты, срока её действия, держателя и кода проверки подлинности; - *Произвольный идентификатор реквизитов*— с указанием идентификатора, ранее ассоциированного в платёжной платформе с реквизитами используемой карты \([подробнее](ru_gate_saved_data.md)\); - *Стандартизированный токен реквизитов*— с указанием токена, ранее ассоциированного в платёжной платформе с реквизитами используемой карты \([подробнее](ru_Gate_Token.md)\). ### Списания {#section_ywd_pxj_5wb .section} Чтобы выполнить списание средств через Gate, со стороны веб-сервиса необходимо: 1. Отправить запрос к конечной точке `/v2/payment/\{название метода\}/sale[/форма указания реквизитов платёжного инструмента]`. 2. При необходимости выполнить аутентификацию пользователя с использованием протокола 3-D Secure \([подробнее](ru_gate_payment_3ds.md)\). 3. Принять от платёжной платформы оповещение о результате списания. Формат запроса на списание описан [далее](ru_gate_money_transfer_services.md#section_s1y_31k_5wb), в разделе [Форматы запросов](ru_gate_money_transfer_services.md) этой статьи. ### Отмены списаний {#section_apg_czj_5wb .section} В некоторых случаях может быть актуальной отмена списания. Технически в платформе такая отмена выполняется как [возврат](ru_Gate_Refund.md) и инициируется через запрос к конечной точке `/v2/payment/\{указатель метода\}/refund`. При этом следует учитывать, что согласно требованиям платёжных систем отменить списание можно только на полную сумму и только в установленные сроки. Для карт платёжной системы Visa запрос на такую отмену допустимо отправлять в течение первых суток с момента списания, для карт платёжной системы Mastercard настоятельно рекомендуется делать это в течение трёх рабочих дней. По истечении этих сроков с вопросами об отмене списаний следует обращаться к сотрудникам технической поддержки Ecommpay. ### Зачисления {#section_xgb_szj_5wb .section} Чтобы выполнить зачисление средств через Gate, со стороны веб-сервиса необходимо: 1. Отправить запрос к конечной точке `/v2/payment/card/payout[/token]`. 2. Принять от платёжной платформы оповещение о результате зачисления. Формат запроса на зачисление описан [далее](ru_gate_money_transfer_services.md#section_fcv_3vk_5wb), в разделе [Форматы запросов](ru_gate_money_transfer_services.md) этой статьи. ## Форматы запросов {#ru_gate_money_transfer_services_format_request} ### Запрос на списание {#section_s1y_31k_5wb .section} При формировании запросов на списание необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - при передаче реквизитов карты в явном виде — к [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale); - при передаче идентификаторов сохранённых данных — к [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved); - при передаче токенов сохранённых данных — к [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token); - при использовании методов Apple Pay и Google Pay — к [/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale) и [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale) cоответственно. 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о списании: - `amount` — сумма списания с платёжной карты отправителя \(пользователя\), в дробных единицах валюты; - `currency` — код валюты списания в формате ISO-4217 alpha-3; - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. - `customer` — объект, содержащий сведения об отправителе \(пользователе\): - `id` — идентификатор пользователя в рамках проекта; - `ip_address` — IP-адрес пользователя; - `country` — код страны пользователя в формате ISO 3166-1 alpha-2; - `address` — адрес проживания пользователя, обязательный при использовании карт Visa; - `city` — название города проживания \(или иного населённого пункта\) пользователя, обязательное при использовании карт Visa; - `state` — код штата или провинции пользователя, обязательный для случаев с последующим зачислением списываемых средств на карту Visa, выпущенную в США или Канаде; - `phone` — номер телефона пользователя, обязательный для случаев с последующим зачислением списываемых средств на карту Visa, выпущенную в Бразилии или Катаре; - `account_id` — номер кошелька получателя, обязательный при использовании карт Mastercard; - `first_name` — имя пользователя, обязательное при использовании методов Apple Pay и Google Pay; - `last_name` — фамилия пользователя, обязательное при использовании методов Apple Pay и Google Pay. 3. В запросе должны содержаться сведения о платёжной карте отправителя \(пользователя\): - При передаче реквизитов в явном виде — следующие данные в объекте `card`: - `pan` — номер карты; - `year` — год окончания срока действия карты; - `month` — порядковый номер месяца срока действия карты; - `card_holder` — имя и фамилия держателя карты \(в соответствии с указанными на карте\); - `cvv` — код проверки подлинности карты. - При передаче идентификатора реквизитов — следующие данные в объекте `card`: - `saved_account_id` — идентификатор, ассоциированный в платёжной платформе с реквизитами используемой карты; - `cvv` — код проверки подлинности карты. - При передаче токена реквизитов — следующие данные: - `token` — токен, ассоциированный в платёжной платформе с реквизитами используемой карты; - `cvv` — код проверки подлинности карты. 4. В запросе должны содержаться сведения о получателе и его платёжном инструменте: - При передаче сведений о кошельке получателя — следующие данные в объекте `recipient`: - `wallet_id` — номер кошелька; - `wallet_owner` — имя и фамилия владельца кошелька; - `country` — код страны владельца кошелька в формате ISO 3166-1 alpha-2, обязательный для случаев, когда кошелёк связан с картой Mastercard. - При передаче реквизитов карты — следующие данные в объекте `recipient`: - `pan` — номер платёжной карты получателя; - `card_holder` — имя и фамилия держателя карты \(в соответствии с указанными на карте\); - `day_of_birth` — дата рождения получателя в формате `ДД-ММ-ГГГГ`, обязательная при использовании карт Visa. 5. В отдельных случаях должны указываться дополнительные сведения о получателе в объекте `recipient` \(в дополнение к реквизитам\): - При передаче реквизитов карты Visa, выпущенной в Канаде: - `country` — код страны получателя в формате ISO 3166-1 alpha-2; - `city` — название города проживания \(или иного населённого пункта\) получателя; - `state_code` — код штата или провинции получателя. - При передаче реквизитов карты Visa, выпущенной в Австралии, Канаде или Новой Зеландии — адрес проживания получателя в параметре `address`. 6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на списание должен содержать идентификаторы проекта и платежа, подпись, код валюты и сумму списания, сведения об отправителе, а также реквизиты платёжных карт отправителя и получателя в одной из применимых форм. В следующем примере представлены данные тела запроса на списание с карты Visa c последующим зачислением списываемых средств на карту Mastercard. ```language-json { "general":{ "project_id":91348, "payment_id":"135113521354", "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA==" }, "payment":{ "amount":1000, "currency":"EUR" }, "customer":{ "id":"16061313", "ip_address":"93.47.230.225, "country":"IT", "city":"Florence", "address":"Via Certaldo 18" }, //при передаче реквизитов карты отправителя в явном виде: "card":{ "pan":"4314220000000056", "year":2024, "month":10, "card_holder":"Gio Boccaccio", "cvv":"334" }, //при передаче идентификатора реквизитов: "card":{ "saved_account_id": 21121375, "cvv": "334" }, //при передаче токена реквизитов: "token":"f365bb1729f9b72fd9c09703a751c979f3becc67", "cvv":"334", //при передаче реквизитов карты получателя: "recipient":{ "pan":"5413330000000019", "card_holder":"Fran Petrarca" } //при передаче сведений о кошельке получателя: "recipient":\{ "wallet\_id":"WID20071304", "wallet\_owner":"Fran Petrarca", "country":"IT" \} } ``` ### Запрос на зачисление {#section_fcv_3vk_5wb .section} При формировании запросов на зачисление необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - при передаче реквизитов карты в явном виде — к [/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout); - при передаче токенов сохранённых данных — к [/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о зачислении: - `amount` — сумма зачисления на платёжную карту получателя в дробных единицах валюты; - `currency` — код валюты зачисления в формате ISO-4217 alpha-3; - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. - `customer` — объект, содержащий сведения об отправителе: - `id` — идентификатор пользователя \(отправителя\) в рамках проекта; - `ip_address` — адрес пользователя. 3. В запросе должны содержаться сведения о платёжной карте получателя: - При передаче реквизитов в явном виде — следующие данные в объекте `card`: - `pan` — номер платёжной карты получателя; - `card_holder` — имя и фамилия получателя \(в соответствии с указанными на карте\); - При передаче токена реквизитов: - `token` — токен, ассоциированный в платёжной платформе с реквизитами используемой карты. 4. В запросе должны содержаться сведения об отправителе и его платёжном инструменте, включаемые в состав объекта `sender`: - Данные о платёжном инструменте отправителя, указываемые в одном из следующих параметров: - `pan` — номер платёжной карты отправителя; - `wallet_id` — номер кошелька отправителя. - Данные об отправителе, в числе которых рекомендуется передавать следующие параметры: - `country` — код страны отправителя в формате ISO 3166-1 alpha-2; - `city` — название города проживания \(или иного населённого пункта\) отправителя; - `address` — адрес проживания отправителя; - `first_name` — имя отправителя; - `last_name` — фамилия отправителя; - `state` — код штата или провинции отправителя, обязательный для случаев, если страна отправителя — США или Канада; - `zip` — почтовый индекс отправителя, обязательный при использования карты Mastercard; - `day_of_birth` — дата рождения отправителя в формате `ДД-ММ-ГГГГ`, обязательная при использовании карт Visa; - `phone` — номер телефона отправителя, обязательный для случаев зачисления средств на карту Visa, выпущенную в Бразилии или Катаре. 5. В запросе должны содержаться следующие сведения о получателе в объекте `recipient`: - `first_name` — имя получателя; - `last_name` — фамилия получателя. 6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос на зачисление должен содержать идентификаторы проекта и платежа, подпись, код валюты и сумму зачисления, сведения об отправителе и получателе, а также реквизиты платёжного инструмента отправителя и платёжной карты получателя в одной из применимых форм. В следующем примере представлены данные тела запроса на зачисление средств на карту Mastercard, при этом списание было осуществлено с карты Visa. ```language-json { "general":{ "project_id":91348, "payment_id":"135113521354", "signature":"iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA==" }, "customer":{ "id":"16061313", "ip_address":"93.47.230.225" }, "payment":{ "amount":1000, "currency":"EUR" }, "recipient":{ "first_name":"Fran", "last_name":"Petrarca", "day_of_birth":"20-08-1304" }, "sender":{ "country":"IT", "city":"Florence", "address":"Via Certaldo 18", "first_name":"Gio", "last_name":"Boccaccio", "day_of_birth":"16-06-1313" }, //при передаче реквизитов карты получателя: "card":{ "pan":"5413330000000019", "card_holder":"Fran Petrarca" }, //при передаче токена: "token": 1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713, //при передаче реквизитов карты отправителя: "sender":{ "pan":"4314220000000056" } //при передаче сведений о кошельке отправителя: "sender":\{ "wallet\_id":"WID16061313" \} } ``` ## Формат оповещений {#ru_gate_money_transfer_services_format_callback} Для оповещений о результате выполнения операций списания и зачисления в рамках использования сервисов Mastercard MoneySend и Visa Direct используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). ```language-json { "project_id": 91348, "payment": { "id": "135113521354", "type": "purchase", "status": "success", "date": "2022-02-22T19:52:14+0000", "method": "card", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "account": { "number": "431422******0056", "type": "visa", "token": "f365bb1729f9b72fd9c09703a751c979f3becc67", "country": "IT", "bank": "Intesa Sanpaolo SpA", "product": "debit" }, "customer": { "id": "16061313" }, "operations": [ { "provider": { "result_message": "Success", "result_code": "00", "id": 2, "payment_id": "135113521354", "auth_code": "661786", "endpoint_id": 3651, "date": "2022-02-22T19:52:14+0000" }, "rrn": "305440290856", "region": "domestic", "code": "0", "message": "Success", "eci": "05", "id": 52901540107953, "type": "sale", "status": "success", "date": "2022-02-22T19:52:14+0000", "created_date": "2022-02-22T19:51:18+0000", "request_id": "a51091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-d7bc0c44525", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" } } ], "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA==" } ``` ```language-json { "project_id": 91348, "payment": { "id": "135113521355", "type": "payout", "status": "success", "date": "2022-02-22T20:01:36+0000", "method": "card", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "account": { "number": "541333******0019", "type": "mastercard", "token": "1f0dc354c1907a13ba5efc4b19a071b3f1c364abd071bac91b354190b713" }, "customer": { "id": "16061313" }, "issuer_name": "UniCredit SpA", "product_name": "World Mastercard", "country": "IT", "card_product_type": "debit", "card_holder": "Fran Petrarca", "operations": [ { "type": "payout", "provider": { "result_message": "Success", "result_code": "00", "id": 2, "payment_id": "135113521355", "auth_code": "309410", "endpoint_id": 3651, "date": "2022-02-22T20:01:35+0000" }, "status": "success", "date": "2022-02-22T20:01:36+0000", "rrn": "301360291143", "created_date": "2022-02-22T20:01:34+0000", "region": "domestic", "request_id": "fda091ae66b8387af268ef81-069b9fd5ab46392fc15e3c02-00001711", "code": "0", "sum_initial": { "amount": 1000, "currency": "EUR" }, "message": "Success", "sum_converted": { "amount": 1000, "currency": "EUR" }, "id": 5013600010130727 } ], "signature": "hQAYY7mMIBWPaskXE/TiUZ26dm8ptxuEq/g==" } ``` --- # Погашение задолженностей {#ru_Gate_debt_repayments .concept} статья о возможности проводить через Gate платежи по кредитам и займам ## Общая информация {#section_rzc_z4b_12b .section} *Погашение задолженности* — вид оплаты с карты пользователя, предназначенный для выплаты по кредиту или займу. Такой вид оплаты доступен для мерчантов, предоставляющих услуги микрокредитования с кодом категории `6012` или `6051`. Платеж на погашение задолженности может быть осуществлен как разовая оплата, регистрация повторяемой оплаты или проверка действительности карты. В случаях если мерчант, зарегистрирован в Великобритании \(для платежей по картам Mastercard\) или Европейском регионе, согласно регламенту распределения Visa \(для платежей по картам Visa\), то в дополнение к обязательным объектам и параметрам в запросе указываются номер счёта мерчанта и дополнительные данные пользователя: - payment — объект, содержащий сведения о платеже: - debt\_account — номер счёта для получения средств с карты пользователя. Допустимы буквы латинского алфавита и цифры, длина не более 10 символов; - customer — объект, содержащий сведения о пользователе: - first\_name — имя, - last\_name — фамилия, - day\_of\_birth — дата рождения, в формате ДД-ММ-ГГГГ, - zip — почтовый индекс адреса пользователя \(обязательно для Великобритании\). Для платежей по картам American Express данная возможность не поддерживается. Если параметр не указан в запросе, то он дополнительно запрашивается в оповещении о необходимости дополнить данные \(подробнее — в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md)\). ```language-json { "general": { "project_id": 200, "payment_id": "payment_id", "signature": "PJkV8ej\/UG0Di8NN5...==" }, "payment": { "amount": 1000, "currency": "EUR", "debt_account": "897896541" }, "customer": { "id": "123", "ip_address": "1.1.1.1" "first_name": "John", "last_name": "Johnson", "day_of_birth": "12-05-1990", "zip": "SW1W 0NY" } } ``` Если платеж на погашение задолженности осуществлен через регистрацию повторяемой оплаты — передавать дополнительные параметры в запросах на проведение не требуется, они будут взяты из первоначального запроса. Дополнительные сведения об этой функциональности и ее подключении уточняйте у вашего курирующего менеджера Ecommpay. ## Ограничения Mastercard {#section_tc2_zmj_4mb .section} Согласно требованиям Mastercard эта функциональность доступна мерчантам из Великобритании только с кодом категории `6012`, для всех остальных стран допускаются оба кода — `6012` или `6051`. Запрещено погашение задолженности с кредитных и предоплаченных карт, если страной выпуска карты и регистрации мерчанта является Великобритания. ## Ограничения Visa {#section_wdr_qgk_4mb .section} Согласно требованиям Visa мерчанты из Великобритании, которые принимают погашение просроченной задолженности, должны иметь код категории `6051`. В других случаях и для всех остальных стран допускаются оба кода — `6012` или `6051`. Запрещено погашение задолженности с кредитных карт. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Использование „длинных записей“ {#ru_gate_addendum} статья о возможности использовать при работе через Gate расширенные наборы параметров \(«длинные записи»\) для учёта специализированной информации об оплате авиаперелётов **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Общая информация {#ru_gate_addendum_overview} Для поддержки и развития отдельных индустрий со стороны международных платёжных систем принято использовать специализированные программы, с различными льготами и преференциями для мерчантов. В частности, мерчантам, которые ведут деятельность в сфере туризма и соответствуют одной из заданных категорий \(согласно коду MCC; [Merchant Category Code, MCC](ru_glossary.md)\), могут предоставляться определённые льготы, если при проведении оплат эти мерчанты обеспечивают передачу так называемых „длинных записей“ с детальными сведениями об оказываемых услугах. В платёжной платформе Ecommpay поддерживается возможность работы с „длинными записями“ об услугах туристической отрасли, оплачиваемых с использованием карт платёжных систем Mastercard и Visa. Это относится к оплатам перелётов и дополнительных услуг в рамках забронированных путешествий. При этом каждая длинная запись должна передаваться в запросе на проведение соответствующего платежа в отдельном объекте `addendum` и может включать в себя сведения, соответствующие заданным структурам. Вместе с тем, в некоторых случаях со стороны мерчантов может быть актуальным передавать расширенные сведения об оказываемых туристических услугах не через регламентированные длинные записи, а иным способом\(например, когда код категории мерчанта не подходит для получения льгот и преференций от платёжных систем, но развёрнутая информация о заказах в связке с информацией платежах по ним необходима в рабочих процессах\). Для таких ситуаций в платформе предусмотрены возможности гибко настраиваемой работы с объектом `booking_info` \([подробнее](ru_gate_additional_data.md)\). Применение длинных записей доступно по умолчанию в рамках любого проекта для мерчантов с допустимыми кодами категорий.Для этого предусмотрены соответствующие параметры API, описанные далее в рамках этой статьи. При использовании длинных записей вне допустимых категорий платежи отклоняются. С вопросами об актуальных программах платёжных систем и о характере и размерах льгот, доступных в конкретных случаях с учётом региональных и иных особенностей, как и с вопросами о поддержке специфических сценариев работы и отдельных видов длинных записей, можно обращаться к курирующему менеджеру Ecommpay. ## Передача сведений о бронировании авиабилетов {#ru_gate_addendum_airline} ### Ограничения {#section_g21_vhq_k1c .section} Передавать сведения о бронировании авиабилетови рассчитывать при этом на соответствующие льготы и преференции со стороны платёжных систем могут мерчанты с кодами категорий `3000`–`3350` и `4511`. При использовании длинных записей со стороны мерчантов с другими кодами категорий платежи отклоняются с кодом состояния `310`. Для учёта подобной информации в собственных целях \(со стороны мерчантов с любыми кодами категорий\) можно использовать объект `booking_info` \([подробнее](ru_gate_additional_data.md)\). ### Формат данных {#section_gwf_f3q_k1c .section} Сведения о бронировании авиабилетов в составе длинных записей должны передаваться в исходных запросах на проведение соответствующих платежей — в JSON-объекте `airlines`, вложенном в объект `addendum`. При этом для оформления каждого билета должен использоваться отдельный платёж. Для указания общих сведений о пассажире и авиабилете в объекте `airlines` предусмотрены соответствующие параметры, а для указания сведений о полётных сегментах билета — вложенный объект `trip_legs`, в котором можно указывать от одного до четырёх полётных сегментов, используя объекты `trip_leg`, где `` — порядковый номер сегмента в рамках маршрута. ```language-json { "addendum": { "airlines": { "ticket_number": "1055526005625", "passenger_name": "William Herschel", "customer_ref": "K7XT2A", "ticket_issuer_code": "KL" "ticket_issue_date": "2025-12-24", "travel_agency_code": "12345678", "travel_agency_name": "Deep Sky Tours", "restricted_ticket_indicator": true, "computerized_reservation_system": "SABR", "total_fare_amount": 15000, "total_tax_amount": 2000, "total_fees_amount": 1000, "trip_legs": { \\ Объект с информацией о полётных сегментах "trip_leg1": { \\ Объект с информацией о первом сегменте маршрута "flight_number": "3142", "carrier_code": "KL", "departure_airport": "AMS", "departure_at": "2026-12-25T15:30:25+01:00", "destination_airport": "JFK", "arrival_at": "2026-12-25T17:45:25-05:00", "stop_over_code": true, "service_class": "Y", "fare_bassis": "Y0SVR7", "exchange_ticket": "3141592653589", "conjunct_ticket": "6626070151034", "coupon_number": "1", "endorsements_restr": "No changes allowed" }, "trip_leg2": { \\ Объект с информацией о втором сегменте маршрута "flight_number": "1054", "carrier_code": "DL", "departure_airport": "JFK", "departure_at": "2026-12-25T22:45:25-05:00", "destination_airport": "LHR", "arrival_at": "2026-12-26T10:55:25+00:00", "stop_over_code": false, "service_class": "K", "fare_bassis": "KHCLS7", "coupon_number": "2", "endorsements_restr": "Changes allowed" } } } } } ``` Объект `airlines` может включаться в запросы к различным конечным точкам, при этом его структура определяется моделью, а его расположение в структуре запросов — спецификацией этих конечных точек: - для разовых одностадийных оплат: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)— с указанием платёжных данных в прямом виде или через „сетевые токены“; - [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)— с указанием платёжных данных через идентификаторы; - [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)— с указанием платёжных данных через внутренние токены платёжной платформы; - для разовых двухстадийных оплат: - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)— с указанием платёжных данных в прямом виде или через „сетевые токены“; - [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)— с указанием платёжных данных через идентификаторы; - [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)— указанием платёжных данных через внутренние токены платёжной платформы. ### Используемые параметры {#section_gh5_1qf_j1c .section} В объекте `airlines` могут передаваться следующие объекты и параметры. |Параметр|Описание|tree| |--------|--------|----| |`ticket_number` string, required |Номер забронированного билета. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов. Пример: `1055526005625` |1| |`passenger_name` string, required |Имя и фамилия пассажира, на которого забронирован билет. Представляет собой строку длиной не более 20 символов. Пример: `William Herschel` |2| |`customer_ref` string, required |Идентификатор записи о пассажире в используемой системе бронирования Как правило, представляет собой идентификатор именной записи о пассажире \(Passenger Name Record, PNR\). Может содержать буквы базовой латиницы и цифры. Пример: `K7XT2A` |3| |`ticket_issuer_code` string, required |Двухсимвольный код авиакомпании, оформившей билет \(согласно классификации IATA\). Пример: `KL` |4| |`ticket_issue_date` string, required |Дата бронирования авиабилета в формате `ГГГГ-ММ-ДД` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\). Пример: `2025-12-24` |5| |`travel_agency_code` string, optional |Код туристического агентства, оформившего билет. Этот код присваивается в результате аккредитации в одной из профильных ассоциаций \(IATA, ARC или другой\). Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 8 символов. Пример: `12345678` |6| |`travel_agency_name` string, optional |Название туристического агентства, оформившего билет. Может содержать буквы базовой латиницы и цифры, при этом не должно превышать 25 символов. Пример: `Deep Sky Tours` |7| |`restricted_ticket_indicator` boolean, optional |Индикатор ограничений по тарифу на возврат авиабилета. Может принимать следующие значения: - `true` — невозвратный тариф - `false` — возвратный тариф Пример: `true` |8| |`computerized_reservation_system` string, optional |Код компьютерной системы бронирования, который может быть актуален при оплате перелёта в Германии. Может принимать следующие значения: - `BLAN` — Dr. Blank - `DALA` — Covia-Apollo - `DATS` — Delta - `DERD` — DER - `PARS` — TWA - `SABR` — Sabre - `STRT` — Start - `TUID` — TUI Пример: `SABR` |9| |`total_fare_amount` integer, optional |Сумма, взимаемая авиакомпанией за перевозку пассажира и допустимой бесплатной нормы багажа, в дробных единицах валюты. Пример: `15000` |10| |`total_tax_amount` integer, optional |Налог, включённый в сумму платежа, в дробных единицах валюты. Может представлять собой налог с продаж, налог на добавленную стоимость или другой вид соответствующего налога. Пример: `2000` |11| |`total_fees_amount` integer, optional |Сумма взимаемых комиссий и сборов, в дробных единицах валюты. Пример: `1000` |12| |`trip_legs` object, required |Объект, содержащий сведения о полётных сегментах. Должен содержать информацию как минимум об одном перелёте во вложенном объекте `trip_leg` и при этом может содержать информацию не более чем о четырёх перелётах |13| |`trip_leg` object, required |Объект, содержащий информацию о полётном сегменте \(или так называемом *операционном плече* — отрезке пути между двумя последовательно запланированными остановками\)|13-1 13| |`flight_number` string, required |Номер рейса, присвоенный авиакомпанией, выполняющей перелёт, без указания кода авиакомпании. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 5 символов. Пример: `3142` |13-1-1 13-1| |`carrier_code` string, required |Двухсимвольный код авиакомпании, выполняющей перелёт \(согласно классификации IATA\). Пример: `KL` |13-1-2 13-1| |`departure_airport` string, required |Трёхбуквенный код пункта отправления \(согласно классификации IATA\). Пример: `AMS` |13-1-3 13-1| |`departure_at` string, required |Дата и время планового отправления в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\). Пример: `2026-12-25T15:30:25+01:00` |13-1-4 13-1| |`destination_airport` string, required |Трёхбуквенный код пункта назначения \(согласно классификации IATA\). Пример: `JFK` |13-1-5 13-1| |`arrival_at` string, required |Дата и время планового прибытия в пункт назначения в формате `ГГГГ-ММ-ДДTчч:мм:сс±чч:мм` \(в соответствии с требованиями стандарта [ISO 8601](https://www.iso.org/ru/iso-8601-date-and-time-format.html)\). Пример: `2026-12-25T17:45:25-05:00` |13-1-6 13-1| |`stop_over_code` boolean, required |Индикатор стыковки. Может принимать следующие значения: - `true` — стыковочный рейс - `false` — прямой рейс Пример: `true` |13-1-7 13-1| |`service_class` string, required |Однобуквенный код класса обслуживания \(согласно классификации IATA\). - R — Supersonic - P — First Class Premium - F — First Class - A — First Class Discounted - J — Business Class Premium - C — Business Class - D — Business Class Discounted - I — Business Class Discounted - Z — Business Class Discounted - W — Economy/Coach Premium - S — Economy/Coach - Y — Economy/Coach - B — Economy/Coach Discounted - H — Economy/Coach Discounted - K — Economy/Coach Discounted - L — Economy/Coach Discounted - M — Economy/Coach Discounted - N — Economy/Coach Discounted - Q — Economy/Coach Discounted - T — Economy/Coach Discounted - V — Economy/Coach Discounted - X — Economy/Coach Discounted Пример: `D` |13-1-8 13-1| |`fare_bassis` string, required |Код тарифа авиакомпании, оформившей билет. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 6 символов. Пример: `Y0SVR7` |13-1-9 13-1| |`exchange_ticket` string, optional |Номер билета, взамен которого был забронирован описываемый билет. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов. Пример: `3141592653589` |13-1-10 13-1| |`conjunct_ticket` string, optional |Номер связанного билета. Оформляется, когда забронированный перелёт включает в себя более четырёх полётных сегментов и билеты для этого перелёта объединяются в связанный ряд. Может содержать буквы базовой латиницы и цифры, при этом не должен превышать 15 символов. Пример: `6626070151034` |13-1-11 13-1| |`coupon_number` string, optional |Номер полётного купона, соответствующий номеру полётного сегмента. Пример: `1` |13-1-12 13-1| |`endorsements_restr` string, optional |Служебная запись, в которой могут указываться различные ограничения, дополнительная информация, а также указание возможности «передачи» \(*endorsement*\) пассажира другому перевозчику. Представляет собой строку длиной не более 20 символов. Пример: `No changes allowed` |13-1-13 13-1S| --- # Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса {#ru_gate_additional_data} статья о возможности фиксировать при работе через Gate сопутствующую информацию о проводимых оплатах для её внутреннего использования в работе мерчантов **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Введение {#ru_gate_additional_data_overview} В некоторых случаях при проведении платежей может быть актуально передаватьне только обязательные и рекомендуемые со стороны провайдера параметры, но и те сведения, которые могут быть полезны в дальнейшем на стороне мерчанта\(с привязкой к конкретным платежам и их статусам\). Для таких ситуаций в структуре Gate API предусмотрены параметры, позволяющие передавать различные сведения в запросах и получать эти сведения вместе с другой информацией в составе итоговых оповещений. **Прим.:** При работе с Payment Page можно использовать аналогичные [возможности](ru_pp_additional_data.md). ## Передача сведений о бронировании товаров и услуг {#ru_gate_booking_data} ### Общая информация {#section_cyp_fwf_g1c .section} С помощью объекта `booking_info` можно фиксировать в запросах сведения о бронированиях, связанных с оплатами, и получать эти сведения в оповещениях от платёжной платформы. В отличие от используемых в отдельных индустриях «длинных записей» \([подробнее](ru_gate_addendum.md)\) эта возможность может применяться более широко \(например, для указания сведений о бронировании билетов на концерты\) и гибко — без ограничений на категорию мерчанта \(согласно коду [Merchant Category Code, MCC](ru_glossary.md)\). Вместе с тем, использование объекта `booking_info` не обеспечивает тех преимуществ, которые могут быть доступны при работе с «длинными записями», и при наличии вопросов о работе с этими возможностями можно обращаться к курирующему менеджеру Ecommpay. Объект `booking_info` может использоваться практически для всех типов платежей с прямым использованием платёжных карти с использованием методов Apple Pay, Click to Pay и Google Pay: в частности, для разовых оплат \(одностадийных и двухстадийных\), нерегулярных повторяемых оплат \(экспресс-оплат и автооплат\) и для проверки платёжных инструментов. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача объекта `booking_info` с информацией о датах начала и окончания бронируемой услуги \(в параметрах `start_date` и `end_date`\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. ### Пример использования {#section_iyy_gwf_g1c .section} В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере музыкальных фестивалей, актуально обеспечить: - сбор и обработку информации о бронировании билетов на фестивали; - оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю. Для этого настраивается следующая схема работы: 1. В каждом запросе к Gate API со стороны веб-сервиса мерчанта в объекте `booking_info` передаются следующие сведения о бронировании. - Массив `bookers` с информацией о лицах, для которых бронируется услуга. Каждый элемент такого массива содержит: - `first_name` — имя получателя услуги, указанное при бронировании; - `last_name` — фамилия получателя услуги, указанная при бронировании; - `email` — адрес электронной почты, указанный при бронировании. - Массив `items` с информацией об отдельных услугах, которые входят в состав бронирования. Каждый элемент такого массива содержит: - `description` — описание отдельной услуги в рамках бронирования; - `start_date` — дата начала действия отдельной услуги; - `end_date` — дата окончания действия отдельной услуги. - А также следующие параметры: - `start_date` — дата начала действия забронированной услуги; - `end_date` — дата окончания действия забронированной услуги; - `description` — произвольное описание бронирования; - `total` — итоговая стоимость бронирования; - `pax` — количество лиц, для которых бронируется услуга; - `reference` — указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта; - `id` — идентификатор бронирования, уникальный в рамках сервиса мерчанта. **Прим.:** Стоит учитывать, что в параметрах `start_date` и `end_date` объекта `booking_info` должны передаваться даты начала и окончания забронированной услуги в целом, а в параметрах `start_date` и `end_date` массива `items` — даты начала и окончания отдельных её составляющих. **Внимание:** В параметрах `total` и `pax` следует передавать численное значение выше `0`. 2. По результатам выполнения соответствующей операции информация из объекта `booking_info` передаётся к веб-сервису в итоговом оповещениии становится доступной для просмотра в карточке платежа интерфейса Dashboard. 3. На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о выполняемых операциях. ### Подключение {#section_mft_hwf_g1c .section} Указывать объект `booking_info` в запросах и получать передаваемые в нём сведения в оповещениях \(при использовании типовой структуры оповещений\) можно без согласований и каких-либо дополнительных действий. Эти возможности доступны по умолчанию. ### Формат данных {#section_bm5_3wf_g1c .section} Объект `booking_info` может включаться в запросы к различным конечным точкам и в оповещения о результатах операций, при этом его структура определяется [моделью](https://api-developers.ecommpay.com/api.html#/7f6ce1c65f45f-booking-info), а его расположение в структуре запросов — спецификацией этих конечных точек. - Для разовых одностадийных оплат: - [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)— с прямым указанием платёжных данных; - [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)— с указанием платёжных данных через идентификаторы; - [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)— с указанием платёжных данных через токены. - Для разовых двухстадийных оплат: - [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)— с прямым указанием платёжных данных; - [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)— с указанием платёжных данных через идентификаторы; - [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)— с указанием платёжных данных через токены; - [/v2/payment/card/incremental](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-incremental)— для увеличения суммы заблокированных в рамках разовых двухстадийных оплат средств пользователя. - Для оплат по платёжным ссылкам: - [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)— без указания платёжных данных в запросе; - [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create)— с указанием платёжных данных через токены. - Для повторяемых оплат: - [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring). - Для проверки платёжных инструментов: - [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)— с прямым указанием платёжных данных; - [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)— с указанием данных через токены. - Для возвратов средств после оплат: - [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund). - [/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale)— для разовых одностадийных оплат; - [/v2/payment/applepay/auth](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-auth)— для разовых двухстадийных оплат; - [/v2/payment/applepay/recurring](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-recurring)— для повторяемых оплат; - [/v2/payment/applepay/account\_verification](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-account-verification)— для проверки платёжных инструментов; - [/v2/payment/applepay/refund](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-refund)— для возвратов средств после оплат. - [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale)— для разовых одностадийных оплат; - [/v2/payment/googlepay/auth](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-auth)— для разовых двухстадийных оплат; - [/v2/payment/googlepay/recurring](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-recurring)— для повторяемых оплат; - [/v2/payment/googlepay/account\_verification](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-account-verification)— для проверки платёжных инструментов; - [/v2/payment/googlepay/refund](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-refund)— для возвратов средств после оплат. В итоговых оповещениях о результатах операций сведения из объекта `booking_info` передаются в таком же виде \(как и в запросах\) в объекте с названием `booking info`. ```language-json "booking_info": { "start_date": "12-08-2026", "end_date": "14-08-2026", "description": "Sideris music festival full pass", "total": 200000, "pax": 2, "bookers": [ { "first_name": "William", "last_name": "Herschel", "email": "rsfellow@mail.com" }, { "first_name": "Caroline", "last_name": "Herschel", "email": "salariedastronomer@mail.com" } ], "items":[ { "description": "VIP Arrival", "start_date": "12-08-2026", "end_date": "12-08-2026" }, { "description": "Hotel", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "Concerts", "start_date": "12-08-2026", "end_date": "14-08-2026" }, { "description": "VIP Departure", "start_date": "14-08-2026", "end_date": "14-08-2026" } ], "reference": "musicfestlink", "id": "83" } ``` ```language-json { "payment": { "date": "2024-01-24T06:24:45+0000", "method": "card", "id": "FESTIVAL_PASS_1781", "sum": { "amount": 0, "currency": "EUR" }, "type": "purchase", "status": "refunded", "description": "FESTIVAL_PASS_1781" }, "project_id": 111738, "customer": { "id": "musicaficionado_83" }, "account": { "number": "551115******1822", "token": "7123ba1f24f16a115f3390a9", "type": "mastercard", "card_holder": "WILLIAM HERSCHEL", "expiry_month": "08", "expiry_year": "2030" }, "booking info": \{ // Объект с информацией о бронировании "start\_date": "12-08-2026", "end\_date": "14-08-2026", "description": "Sideris music festival full pass", "total": 200000, "pax": 2, "bookers": \[ \{ "first\_name": "William", "last\_name": "Herschel", "email": "rsfellow@mail.com" \}, \{ "first\_name": "Caroline", "last\_name": "Herschel", "email": "salariedastronomer@mail.com" \} \], "items": \[ \{ "description": "VIP Arrival", "start\_date": "12-08-2026", "end\_date": "12-08-2026" \}, \{ "description": "Hotel", "start\_date": "12-08-2026", "end\_date": "14-08-2026" \}, \{ "description": "Concerts", "start\_date": "12-08-2026", "end\_date": "14-08-2026" \}, \{ "description": "VIP Departure", "start\_date": "14-08-2026", "end\_date": "14-08-2026" \} \], "reference": "musicfestlink", "id": "83" \}, "operation": { "provider": { "payment_id": "0010000124258736", "auth_code": "", "endpoint_id": 414, "id": 414 }, "sum_converted": { "amount": 200000, "currency": "EUR" }, "code": "0", "message": "Success", "id": 55386010114429, "type": "refund", "status": "success", "date": "2024-01-24T06:24:45+0000", "sum_initial": { "amount": 200000 "currency": "EUR" }, "created_date": "2024-01-24T06:24:43+0000", "request_id": "abcaf52323381a-d988c158cc4b43046-00055387" } } ``` ## Передача произвольных сведений {#ru_gate_merchant_data} ### Общая информация {#section_n5y_5lc_nzb .section} С помощью параметра `merchant.data` можно фиксировать расширенные сведения о составе заказа, информацию об использовании промокодов и бонусных баллов и другие актуальные данные.При этом можно комбинировать состав таких сведений со сведениями, передаваемыми в описании платежа \(в параметре `payment.description`\) и в информации для товарного чека \(в объекте `receipt_data`\). Это позволяет получать в оповещениях всю необходимую информацию без её дублирования в различных параметрах. ### Пример использования {#section_mpx_jmv_fzb .section} В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере видеоигр, актуально обеспечить: - сбор и обработку информации о дополнительных услугах, приобретаемых пользователями в процессе игр; - оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю. Специалисты мерчанта обращаются с такой задачей к курирующему менеджеру Ecommpay, после чего настраивается следующая схема работы: 1. В каждом запросе к Gate со стороны веб-сервиса мерчанта передаётся информация о приобретаемых услугах — в виде JSON-объекта в параметре `data` объекта `merchant` . В состав строки `data` включаются: - массив `items`, в котором каждый элемент содержит артикул \(`sku`\), описание \(`description`\) и количество приобретаемых услуг \(`count`\); - параметр `total_count` с общим количеством приобретаемых услуг или товарных позиций; - параметр `user_id` с внутренним идентификатором пользователя. 2. По результатам проведения каждого платежа информация из строки `data` передаётся к веб-сервису мерчанта в итоговом оповещении и становится доступной для просмотра в карточке платежа интерфейса Dashboard. 3. На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о проводимых платежах. ![](images/ecommpay/ru_merchant_data_db.svg "Отображение информации в интерфейсе Dashboard") ### Подключение {#section_xf5_tkv_fzb .section} Возможности применения параметра `merchant.data` для передачи и получения различных сведений следует согласовывать с курирующим менеджером Ecommpay. После согласований специалисты Ecommpay выполняют необходимые действия в платёжной платформе и уведомляют о готовностик включению расширенных сведений в оповещения и к отображению этих сведений в интерфейсе Dashboard. ### Формат данных {#section_tp5_rfc_nzb .section} В запросах к Gate для проведения платежей сведения в параметре `merchant.data` должны передаваться в виде JSON-объекта. При этом, поскольку параметр имеет строковый тип данных\(string\), для передачи JSON-объекта методом POST требуется экранировать символ `"` \(двойной штрих,U+0022\) путём постановки перед ним символа `\` \(косой обратной черты,U+005C\).Это необходимо, чтобы чётко разграничивать на уровне программного взаимодействия, какие кавычки закрывают строку, а какие относятся к содержанию JSON-объекта внутри строки. В итоговых оповещениях о результатах платежей сведения из параметра `merchant.data` передаются в аналогичном параметре `data` объекта `merchant`, с применением экранирования. В следующих примерах содержимое параметра разбито на несколько строк для удобства чтения. ```language-json "merchant": { "data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" } ``` ```language-json "merchant": { "data": "{\"items\":[{\"sku\":\"GM12-CC\", \"description\":\"10 Copper Coins\",\"count\":1}, {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\", \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" } ``` --- # Использование дополнительных параметров проведения платежей {#ru_Gate_extra_params .concept} статья о возможности использовать при работе через Gate дополнительные параметры, актуальные для мерчантов и не предусмотренные в спецификации Gate API Gate позволяет задавать особые условия обработки платежей. Для этого необходимо передать данные в параметре payment.extra\_param. Дополнительные сведения об этой возможности уточняйте у вашего курирующего менеджера. **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Использование сведений о мерчанте при проведении платежей {#ru_gate_descriptor} статья о возможностях опосредованно предоставлять пользователям сведения о мерчантах через сервисы эмитентов при работе через Gate ## Общая информация {#section_u2p_3rk_mhc .section} Выступая как эквайер, Ecommpayсогласно правилам платёжных систем передаёт другим сторонам, участвующим в проведении платежей, сведения о мерчантах. Эти сведениямогут использоваться каждой из сторон по своему усмотрению и, как правило, доводятся эмитентами до пользователей в уведомлениях и банковских выписках. По умолчанию сведения о каждом мерчантестатичны и включают в себялишь согласованное написание названия организации, однако по инициативе мерчанта к названию могут динамически добавляться и другие сведения,касающиеся конкретных операций или иных аспектов деятельности. Эти динамические части описаний могут указываться в запросах на проведение платежейи ограничиваются только общей длиной строки и составом допустимых символов \(подробнее [далее](ru_gate_descriptor.md#section_b3f_hvp_13c)\). Так, в качестве сведений о мерчанте может указываться запись с названием организации и периодом бронирования услуги \(`Cosmotour* 17-19 feb`\) или с названием организации и забронированного отеля \(`Cosmotour* MarsSuite`\). ![](images/ecommpay/ru_gate_descriptor_2.svg "Указание периода бронирования") ![](images/ecommpay/ru_gate_descriptor_1.svg "Указание названия отеля") Гибкое применение корректных и информативных сведений такого рода позволяет пользователям чётче идентифицировать мерчантов и платежи, а мерчантам — улучшать пользовательский опыт и снижать вероятность опротестования платежей со стороны пользователей.Работа с такими сведениями в рамках платёжной платформы Ecommpay актуальна для *карточных платежей* \(включая классические карточные платежи и методы Apple Pay, Click to Pay, Google Pay и Visa Instalments\) в отношении разовых и повторяемых оплат, проверок действительности платёжных карт и выплат. ## Особенности {#section_fhg_s3m_djc .section} При работе со сведениями о мерчанте следует учитывать ряд особенностей: - Основное назначение сведений о мерчантах — помогать пользователям идентифицировать их операции и предотвращать неуместные опротестования. В связи с этим важно избегать в используемых сведениях двусмысленностей и иных сложностей интерпретирования и фокусировать внимание пользователей на тех сведениях, которые помогают однозначно идентифицировать мерчанта и, по возможности, каждую операцию с ним. В частности, можно руководствоваться рекомендацией использовать знакомое для пользователей название бренда и ёмкое описание товаров и услуг в рамках каждой операции. - Правила работы со сведениями о мерчантах могут отличаться для разных платёжных систем. Такие отличия стоит иметь в виду, как минимум, в части допустимых форматов \(подробнее [далее](ru_gate_descriptor.md#section_b3f_hvp_13c)\). - Порядок предоставления сведений о мерчантах пользователям определяется эмитентами. Состав и способ отображения итоговых сведений о мерчантах в уведомлениях, банковских выписках и иных материалах определяются правилами работы конкретных эмитентов. Это ведёт к тому, что сведения могут выглядеть по-разному как среди разных эмитентов, так и среди разных интерфейсов одного эмитента и среди разных типов операций в рамках одного интерфейса \(в частности, такие отличия могут касаться разных типов оплат и выплат, а также операций с использованием сервисов Mastercard MoneySend и Visa Direct\). ## Подключение {#section_p14_v5p_13c .section} Название организации, используемое в качестве базового варианта сведений о мерчанте, фиксируется при регистрации мерчанта в платёжной платформе и может быть скорректировано в дальнейшем только через курирующего менеджера Ecommpay. Чтобы подключить возможность использования дополнительных сведений о мерчанте,со стороны мерчанта следует: 1. Согласовать с курирующим менеджером Ecommpay актуальность подключениядля конкретных проектов и необходимость тестирования функциональности. 2. Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работыс использованием этой возможности и сообщить о готовности к запуску. 3. Получить от специалистов Ecommpay уведомление о подключении функциональности. ## Использование {#section_dh5_v5p_13c .section} В тех случаях, когда для мерчанта актуально использование дополнительных сведений, следует передавать в запросах параметр `descriptor`. Этот параметр может включаться в объекты `merchant` и `sender`, при этом, если для определённой конечной точки могут использоваться оба этих объекта, `descriptor` допустимо указывать в любом из них, но при указании двух значений приоритетным считается более релевантный объект: - для оплат и проверок действительности платёжных карт — `merchant`; - для выплат — `sender`. Также стоит учитывать, что в случаях, когда значения параметра `descriptor` не соответствуют требуемому формату \([подробнее](ru_gate_descriptor.md#section_b3f_hvp_13c)\), в платформе может выполняться техническая корректировка таких значений\(в частности, с транслитерацией алфавитных символов и удалением недопустимых неалфавитных\) и это не приводит к отклонению инициируемых платежей. Вместе с тем, значения параметра `descriptor`не анализируются на стороне Ecommpay по содержанию, но могут анализироваться и использоваться в дальнейшем на стороне эмитентов. В связи с этим со стороны мерчанта важно обеспечивать техническую и содержательную корректность сведений, передаваемых в параметре `descriptor`, в каждом случае его применения. - для разовых оплат в одну стадию с указанием реквизитов карт или „сетевых токенов“ —[/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale) - для разовых оплат в одну стадию с указанием внутренних токенов платёжной платформы —[/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token) - для разовых оплат в две стадии с указанием реквизитов карт или „сетевых токенов“ —[/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth) - для разовых оплат в две стадии с указанием внутренних токенов платёжной платформы —[/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token) - для повторяемых оплат всех типов —[/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring) - для выплат с указанием реквизитов карт —[/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout) - для выплат с указанием внутренних токенов платёжной платформы —[/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token) - для проверок действительности платёжных карт с указанием их реквизитов или „сетевых токенов“ —[/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification) - для проверок действительности платёжных карт с указанием внутренних токенов платёжной платформы —[/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token) - для разовых оплат в одну стадию —[/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale) - для разовых оплат в две стадии —[/v2/payment/applepay/auth](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-auth) - для разовых оплат в одну стадию —[/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale) - для разовых оплат в две стадии —[/v2/payment/googlepay/auth](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-auth) ## Формат данных {#section_b3f_hvp_13c .section} Допустимая длина используемых сведений о мерчанте ограничивается со стороны каждой платёжной системы. Так, Mastercard устанавливает максимальной длину в 22 символа, а Visa — в 25 символов.Все избыточные символы при этом отсекаются. Это стоит учитывать при формировании описаний наряду с ограничениями по допустимым символам. Допустимыми для параметра `descriptor` являются буквы базовой латиницы, цифры, пробел \(U+0020\) и следующие символы: |`*`|U+002A|звёздочка \(астериск\)| |`,`|U+002C|запятая| |`-`|U+002D|дефис| |`.`|U+002E|точка| |`=`|U+003D|знак равенства| |`_`|U+005F|нижнее подчёркивание| Чтобы сформировать параметр `descriptor`, необходимо указатьсогласованный вариант названия организации и дополнительные сведения, разделив их звёздочкой \(`*`\) и пробеломи проверив соответствие ограничениям по длине строки.Например, если использовать название `Cosmotour` длиной в 9 символов \(и 2 символа в качестве разделителя\), допустимая длина для дополнительных сведений составит 11 символов для карт Mastercard и 14 символов для карт Visa — достаточно для записи вида `Cosmotour* to the Moon`. ``` {#codeblock_m2w_r5h_23c .language-json} { "payment": { "amount": 1000, "currency": "EUR", "description": "Payout" }, "general": { "project_id": 91348, "payment_id": "135113521354", "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA==" }, "customer": { "id": "16061313", "ip_address": "93.47.230.225", "first_name": "John", "last_name": "Doe" }, "sender": { "descriptor": "Cosmotour* to the Moon" // сведения о мерчанте }, "card": { "save": false, "pan": "4314220000000056" } } ``` **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) --- # Отправка уведомлений пользователям {#ru_gate_receipts} статья о возможностях прямо информировать пользователей о проведении платежей и других событиях через электронную почту при работе через Gate **На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md) ## Общая информация {#ru_gate_receipts_overview} В платёжной платформе Ecommpay поддерживается возможность уведомлять пользователей о различных событиях, связанных с проведением платежей. Как правило, это уведомления о результатах выполнения операций, однако в зависимости от индивидуальных потребностей мерчанта могут использоваться уведомления и о других событиях, например о регистрации электронного кошелька в рамках проведения платежа или обновлении условий повторяемой оплаты. Уведомления отправляются при соблюдении следующих условий: - для используемого проекта подключена отправка уведомлений; - в платёжную платформу был передан адрес электронной почты пользователя \(в исходном запросе на проведение платежа или при дополнении информации об этом платеже\); - произошло событие, для которого настроена отправка уведомлений. К событиям, для которых настраивается отправка уведомлений, могут относиться как результаты выполнения операций в рамках проведения платежей\(например, операций `sale`, `auth`, `capture`, `cancel`, `payout` и `refund`\), так и результаты отдельных действий, выполненных в рамках операций\(например, обновление условий повторяемой оплаты\). В уведомления о результатах проведения оплат можно добавлять информацию о товарных позициях с указанием списка приобретённых товаров и их сопутствующих характеристик \(стоимости, количества товарных единиц, описания и суммы включённого в стоимость налога на добавленную стоимость \(НДС\). При необходимости можно выполнять повторную отправку опредёленных уведомлений. Для этого следует обращаться к специалистам технической поддержки [support@ecommpay.com](mailto:support@ecommpay.com). Далее представлена информация о порядке подключения отправки уведомлений, об использовании двух вариантов оформления уведомлений — стандартного и индивидуального, а также о формате данных, передаваемых в запросах на проведение тех платежей, по которым необходимо уведомлять пользователей. Информация об отправке чеков в Payment Page представлена в разделе [Отправка чеков и оповещений пользователям](ru_PP_receipt_data.md). ## Подключение {#ru_gate_receipts_setting_up} Подключение и настройка возможности отправлять уведомления пользователям выполняются специалистами технической поддержки Ecommpay. При этом по согласованию с мерчантом настраиваются следующие характеристики режима отправки: - перечень операций и других событий, для которых настраивается отправка; - статусы операций, при которых выполняется отправка уведомлений \(возможно как для итогового статуса `success`, так и для итогового статуса `decline`\) ; - тема письма, в котором приходит уведомление \(например, Receipt или «Уведомление о проведённой оплате»\); - адрес электронной почты отправителя \(домен Ecommpay или домен, принадлежащий веб-сервису мерчанта\); - возможность отправлять скрытые копии уведомлений на адрес электронной почты, предоставленный мерчантом. ## Оформление уведомлений {#ru_gate_receipt_templates} ### Стандартное оформление {#section_brh_xc2_tlb .section} Стандартный шаблон может использоваться только при отправке уведомлений о результатах выполнения операций в рамках проведения разовых оплат \(`purchase`\)и выплат \(`payout`\), а также о результатах выполнения возвратов средств пользователям \(`refund`\). Шаблон содержит следующие поля: - дату и время, когда событие зафиксировано в платёжной платформе, с указанием часового пояса веб-сервиса мерчанта; - логотип Ecommpay или мерчанта; - название, фактический адрес, а также доменное имяEcommpay или мерчанта; - тип платежа или операции, информация о результате которых передаётся в уведомлении; - статус этого платежа или этой операции; - идентификатор платежа `payment_id`; - описание платежа или операции, если оно было передано в запросе на инициирование; - данные платёжного инструмента, с использованием которого был проведён платёж; - сумму платежа с указанием кода валюты; - ссылку на адрес электронной почтыEcommpay или мерчанта; - ссылку на правила пользования сервисом. ![](images/ecommpay/template_receipt_purchase.svg "Пример уведомления о результатах оплаты") ### Индивидуальное оформление {#section_e2g_2zc_vlb .section} Шаблон с индивидуальной вёрсткой может использоваться для отправки уведомлений как о результатах операций, так и о других событиях, связанных с проведением платежей. Индивидуальная вёрстка таких уведомлений реализуется на стороне Ecommpay на основе макетов, предоставленных мерчантом. В шаблонах с индивидуальной вёрсткой могут использоваться те же элементы, что и в стандартных шаблонах, с возможностью изменения их порядка или могут быть добавлены другие элементы, например блоки с информацией о товарных позициях,о регистрации электронного кошелька,о превышении лимита общей суммы операций за сутки или об обновлении условий повторяемой оплаты. Также мерчантам следует учитывать, что в случае нестандартного текста уведомлений и для уведомлений на всех языках, кроме английского \(применяемого по умолчанию\), необходимо предоставить текст уведомления специалистам технической поддержки. Далее представлены примеры уведомлений с индивидуальной вёрсткой: - Уведомление с информацией об окончании бесплатного пробного периода, которое не содержит поля, включаемые в стандартный шаблон \(за исключением логотипа мерчанта\). - Уведомление с информацией о товарных позициях, которое содержит все поля, включаемые в стандартный шаблон. ![](images/ru-receipt-trial-update.png "Пример уведомления об окончании бесплатного пробного периода") ![](images/ru-receipt-orderlist.png "Пример уведомления с информацией о товарных позициях") ## Формат данных {#ru_gate_receipt_request_format} Для отправки уведомления кроме обязательных параметров в запросе необходимо передать: - адрес электронной почты пользователя в параметре `email` объекта `customer`; - код языка пользователя в параметре `language` объекта `customer` в случае отправки уведомлений на любых языках, кроме английского. Для включения в уведомление информации о товарных позициях необходимо дополнительно передать данные для формирования такого уведомления в объекте `receipt_data`. Объект `receipt_data` содержит массив `positions`, в котором можно перечислить до 300 товарных позиций. Для каждой товарной позиции указывается следующее: - `amount` — обязательный параметр для указания стоимости товара; - `quantity` — дополнительный параметр для указания количества товарных единиц; - `tax` — дополнительный параметр для указания ставки налога на добавленную стоимость \(НДС\); - `tax_amount` — дополнительный параметр для указания суммы налога на добавленную стоимость \(НДС\); - `description` — дополнительный параметр с описанием товара. Как правило, в объекте `receipt_data` также указывается общая сумма НДС за всю покупку в параметре `total_tax_amount`. Если ставка НДС является одинаковой для всех позиций, то она указывается в параметре `common_tax` после общей суммы. Если ставка отличается для позиций в списке, то её значение указывается в параметре `tax` для каждой позиции отдельно. Структура JSON-объекта приведена в модели `[receiptdata](https://api-developers.ecommpay.com/api.html#/c2NoOjQwNTY3ODY2-receipt-data)` в спецификации Gate API. В представленном далее примере запроса на проведение оплаты в объекте `receipt_data` содержится список из трёх товарных позиций в массиве `positions`. Так как ставки НДС для отдельных товаров в списке различаются, они указываются с помощью параметра `tax` для каждой товарной позиции. Соответственно, параметр `common_tax` с общей ставкой НДС в данном случае указывать не нужно. ```language-json { "general":{ "project_id":92724, "payment_id":"7654321-777", "signature":"5fgsjhgfgFxO9UaFLYGsBaisdffddgYuezUf+6VWlrsdfsH+LysUfdQM+w==" }, "customer":{ "ip_address":"128.112.0.16", "email":"relativeal@princeton.com" }, "payment":{ "amount":131971, "currency":"USD", "description":"Cosmoshop order" }, "receipt_data":{ "positions":[ //массив с перечислением товарных позиций { "quantity":1, "amount":5990, "tax":20, //основная ставка НДС "tax_amount":1198, "description":"How to communicate with aliens, a book" }, { "quantity":3, "amount":2990, "tax":10, //льготная ставка НДС "tax_amount":299, "description":"Astronaut space food, 1-week supply" }, { "quantity":1, "amount":122990, "tax":20, //основная ставка НДС "tax_amount":24598, "description":"Radio-controlled flying saucer, full size" } ], "total_tax_amount":26095 //общая сумма НДС за всю покупку }, "card":\{ "pan":"4314220000000056", "year":2025, "month":11, "card\_holder":"Albert Astone" \} } ``` --- # Gate API {#gate_api} **На уровень выше:** [Gate](ru_Gate_Integration_About.md) { "openapi": "3.0.2", "info": { "title": "Gate API", "description": "Ecommpay Gate public API is an interface for merchants to perform operations and retrieve operation information", "version": "3.34.5" }, "servers": [ { "url": "https://api.ecommpay.com" } ], "paths": { "/v2/payment/card/sale": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/sale", "description": "Request for purchase from the customer's card", "operationId": "POST_v2-payment-card-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "card", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "card": { "$ref": "#/components/schemas/CardInfoForSaleAuth" }, "token_data": { "$ref": "#/components/schemas/TokenData" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "sender": { "$ref": "#/components/schemas/SenderInfoSale" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "installment": { "$ref": "#/components/schemas/Installment" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/sale/saved": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/sale/saved", "description": "Request for purchase from the customer's saved card", "operationId": "POST_v2-payment-card-sale-saved", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "saved_account_id" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "installment": { "$ref": "#/components/schemas/Installment" }, "saved_account_id": { "type": "integer", "description": "The identifier associated with the corresponding payment instrument in the payment platform" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "sender": { "$ref": "#/components/schemas/SenderInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/sale/token": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/sale/token", "operationId": "POST_v2-payment-card-sale-token", "description": "Request for purchase from the customer's card by using its token", "requestBody": { "description": "Payment by token", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "token" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "token": { "description": "Card token received from the payment platform", "type": "string", "minLength": 1, "maxLength": 255 }, "cvv": { "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession", "type": "string", "pattern": "^[0-9]{3,4}$" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "sender": { "$ref": "#/components/schemas/SenderInfoSale" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "installment": { "$ref": "#/components/schemas/Installment" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/card/auth": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/auth", "description": "Request for holding funds on the customer's card. The holding of funds can be captured or cancelled by merchant request or automatically if it is specified in merchant project", "operationId": "POST_v2-payment-card-auth", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "card", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "card": { "$ref": "#/components/schemas/CardInfoForSaleAuth" }, "token_data": { "$ref": "#/components/schemas/TokenData" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "installment": { "$ref": "#/components/schemas/Installment" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/auth/saved": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/auth/saved", "description": "Request for holding funds on the customer's saved card", "operationId": "POST_v2-payment-card-auth-saved", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "saved_account_id" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "saved_account_id": { "type": "integer", "description": "The identifier associated with the corresponding payment instrument in the payment platform" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "installment": { "$ref": "#/components/schemas/Installment" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/auth/token": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/auth/token", "operationId": "POST_v2-payment-card-auth-token", "description": "Request for holding funds on the customer's saved card by using its token", "requestBody": { "description": "DMS first step by token", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "token" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfoCard" }, { "type": "object", "properties": {}, "required": [ "email", "phone", "screen_res" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoForCard" }, "token": { "description": "Card token received from the payment platform", "type": "string", "minLength": 1, "maxLength": 255 }, "cvv": { "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession", "type": "string", "pattern": "^[0-9]{3,4}$" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumInitialCard" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "installment": { "$ref": "#/components/schemas/Installment" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/card/capture": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/capture", "description": "Request for debit of the previously held funds on the customer's card", "operationId": "POST_v2-payment-card-capture", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Payment amount, can be equal to, less or more than in the initial auth request. If the amount is less or more than in the auth request a decremental or incremental operation is created automatically" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in the initial auth request" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" } } }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/Addendum" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/incremental": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/incremental", "description": "Request for changing the amount of payment after holding, before confirm", "operationId": "POST_v2-payment-card-incremental", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoCard" }, "payment": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount to increment" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency in ISO 4217 alpha-3 format, must be same with currency in auth request" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" } }, "required": [ "currency", "amount" ] }, "addendum": { "$ref": "#/components/schemas/Addendum" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/cancel": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/cancel", "description": "Request to cancel the holding of funds on the customer's card", "operationId": "POST_v2-payment-card-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Payment amount, can be equal to or less than in the initial auth request. If the amount is less than in the auth request a decremental operation is created automatically" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in auth request" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" } } }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/Addendum" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/account_verification": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/account_verification", "description": "Request for card verification without performing actual withdrawal", "operationId": "POST_v2-payment-card-account-verification", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "card", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "card": { "$ref": "#/components/schemas/CardInfo" }, "token_data": { "$ref": "#/components/schemas/TokenData" }, "customer": { "type": "object", "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoNameValidation" }, { "type": "object", "required": [ "id" ] } ] }, "payment": { "$ref": "#/components/schemas/AccountVerificationPaymentInfoForCard" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" }, "merchant": { "allOf": [ { "$ref": "#/components/schemas/MerchantInfo" }, { "$ref": "#/components/schemas/Descriptor" } ] } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/account_verification/token": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/account_verification/token", "description": "Request for card verification by token without performing actual withdrawal", "operationId": "POST_v2-payment-card-account-verification-by-token", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "token" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "type": "object", "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoNameValidation" }, { "type": "object", "required": [ "id" ] } ] }, "payment": { "$ref": "#/components/schemas/AccountVerificationPaymentInfoForCard" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "acs_return_url": { "$ref": "#/components/schemas/ACSReturnUrl" }, "authentication_data": { "$ref": "#/components/schemas/AuthenticationData" }, "token": { "description": "Card token received from the payment platform", "type": "string", "minLength": 1, "maxLength": 255 }, "cvv": { "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession", "type": "string", "pattern": "^[0-9]{3,4}$" }, "card": { "type": "object", "properties": { "stored_card_type": { "$ref": "#/components/schemas/StoredCardType" } } }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" }, "merchant": { "allOf": [ { "$ref": "#/components/schemas/MerchantInfo" }, { "$ref": "#/components/schemas/Descriptor" } ] } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/recurring": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/recurring", "description": "Request to perform regular COF payment from the customer's card", "operationId": "POST_v2-payment-card-recurring", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "type": "object", "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "id" ] } ] }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfoRecurring" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "recurring_id": { "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier received from the payment platform", "type": "integer" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/recurring/update": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/recurring/update", "description": "Request to update or change recurring payment conditions", "operationId": "POST_v2-payment-card-recurring-update", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringUpdateInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/recurring/cancel": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/recurring/cancel", "description": "Request to cancel recurring payment", "operationId": "POST_v2-payment-card-recurring-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/merchant_auth": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/merchant_auth", "description": "Request for performing a customer authentication by the payment system on merchant's request", "operationId": "POST_v2-payment-card-merchant_auth", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/MerchantAuthGeneralInfo" }, "confirmation_code": { "type": "string", "minLength": 1, "description": "Authentication confirmation code entered by a customer" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/3ds_check_iframe": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/3ds_check_iframe", "operationId": "POST_v2-payment-card-3ds_check_iframe", "description": "Request to check enrolled card after show iframe", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo3DS" }, "threeds_completion_indicator": { "description": "Indicator that specifies whether the message acknowledging the receipt of the customer's device information was received within 10 seconds after the iframe element was closed. If the acknowledgement was received within 10 seconds, pass `true`; if not, pass `false`", "type": "boolean" }, "md": { "type": "string", "minLength": 1, "description": "Merchant state data. The content of this field must be passed unchanged and without assumptions about its content" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/3ds_result": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/3ds_result", "description": "Request to continue payment processing after 3-D Secure authentication", "operationId": "POST_v2-payment-card-3ds_result", "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "required": [ "general", "cres" ], "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo3DS" }, "cres": { "type": "string", "minLength": 1, "description": "Challenge response - the parameter containing the information about customer's 3‑D Secure 2 authentication result sent in the message from the Access Control Server" }, "md": { "type": "string", "minLength": 1, "description": "Merchant state data received from the payment platform in the callback. The content of this field must be passed unchanged and without assumptions about its content" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } }, { "required": [ "general", "pares" ], "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo3DS" }, "pares": { "type": "string", "minLength": 1, "description": "Payer Authentication Response - the parameter containing the information about customer's 3‑D Secure 1 authentication result sent in the message from the Access Control Server" }, "md": { "type": "string", "description": "Merchant state data received from the payment platform in the callback. The content of this field must be passed unchanged and without assumptions about its content" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } }, { "x-stoplight": { "id": "5ifn7agerbe31" } } ], "type": "object" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/refund": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/refund", "description": "* Request for full or partial refund to the customer's card.\n* Refund is requested in the same currency that the payment was performed.\n* The refund amount can be less than or equal to the amount of the initial payment. The partial refund amount is specified in the parameter `amount`.\n* If the refund amount is not specified in the request, the full amount of the initial payment is refunded", "operationId": "POST_v2-payment-card-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/Addendum" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/payout": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/payout", "description": "Request to credit funds to the customer's card", "operationId": "POST_v2-payment-card-payout", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "card", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "card": { "$ref": "#/components/schemas/CardInfoLight" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "sender": { "$ref": "#/components/schemas/SenderInfoPayout" }, "recipient": { "type": "object", "properties": { "country": { "maxLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Country code of recipient" }, "address": { "maxLength": 99, "type": "string", "description": "Recipient address" }, "city": { "maxLength": 25, "type": "string", "description": "Name of recipient's address city" }, "state": { "maxLength": 3, "pattern": "^[A-Z]+$", "type": "string", "description": "State code of recipient" }, "first_name": { "type": "string", "maxLength": 255, "description": "Customer first name" }, "last_name": { "type": "string", "maxLength": 255, "description": "Customer last name" } } }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" }, { "type": "object", "description": "Object that contains payment details", "properties": { "purpose": { "type": "string", "maxLength": 12, "description": "Payment purpose code—the parameter is populated if specification of payment purpose is mandatory in issuer country" } } } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "merchant": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/card/payout/token": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/card/payout/token", "description": "Request to credit funds to the customer's card by using its token", "operationId": "POST_v2-payment-card-payout-token", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "token" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "sender": { "$ref": "#/components/schemas/SenderInfoPayout" }, "recipient": { "type": "object", "properties": { "country": { "maxLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Country code of recipient" }, "address": { "maxLength": 99, "type": "string", "description": "Recipient address" }, "city": { "maxLength": 25, "type": "string", "description": "Name of recipient's address city" }, "state": { "maxLength": 3, "pattern": "^[A-Z]+$", "type": "string", "description": "State code of recipient" }, "first_name": { "type": "string", "maxLength": 255, "description": "Customer first name" }, "last_name": { "type": "string", "maxLength": 255, "description": "Customer last name" } } }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "type": "object", "description": "Object that contains payment details", "properties": { "purpose": { "type": "string", "maxLength": 12, "description": "Payment purpose code—the parameter is populated if specification of payment purpose is mandatory in issuer country" } } } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "token": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Card token received from the payment platform" }, "card": { "type": "object", "properties": { "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" } } }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "merchant": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/individual/payout": { "post": { "tags": [ "Card payments" ], "summary": "/v2/payment/individual/payout", "description": "Request to credit funds to a customer's card by using P2P scheme", "operationId": "POST_v2-payment-individual-payout", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "card", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "card": { "$ref": "#/components/schemas/CardInfoLight" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "sender": { "$ref": "#/components/schemas/SenderInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/card/bytoken": { "post": { "tags": [ "Token operations" ], "summary": "/v2/customer/card/bytoken", "description": "Request for retrieving the saved customer's payment account details by customer's card token in specific project", "operationId": "POST_v2-customer-card-bytoken", "requestBody": { "content": { "application/json": { "schema": { "required": [ "customer", "token" ], "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerGeneralInfo" }, "token": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Card token received from the payment platform" } }, "description": "Object that contains parameters for receiving of the customer's payment account in the project" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "account", "signature" ], "type": "object", "properties": { "signature": { "type": "string", "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)." }, "account": { "$ref": "#/components/schemas/SavedAccount" } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/card/tokenize": { "post": { "tags": [ "Token operations" ], "summary": "/v2/customer/card/tokenize", "description": "Request for the token generation of a customer's card", "operationId": "POST_v2-customer-card-tokenize", "requestBody": { "content": { "application/json": { "schema": { "required": [ "customer", "card" ], "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/TokenizeCustomerInfo" }, "card": { "$ref": "#/components/schemas/CardInfoForTokenize" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/card/token/revoke": { "post": { "tags": [ "Token operations" ], "summary": "/v2/customer/card/token/revoke", "description": "Request for revoking token.", "operationId": "POST_v2-customer-card-token-revoke", "requestBody": { "content": { "application/json": { "schema": { "required": [ "token", "customer" ], "type": "object", "properties": { "token": { "type": "string", "minLength": 1, "maxLength": 255 }, "customer": { "$ref": "#/components/schemas/CustomerGeneralInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/clarification": { "post": { "tags": [ "Additional information submission" ], "summary": "/v2/payment/clarification", "description": "Request to pass the parameters required to make a payment and missed in the previously sent payment request", "operationId": "POST_v2-clarification", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "additional_data" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfoClarification" }, "additional_data": { "$ref": "#/components/schemas/AdditionalData" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/payout/registration": { "post": { "tags": [ "Payment Page payouts" ], "summary": "/v2/payment/payout/registration", "description": "Register payout payment", "operationId": "POST_v2-payment-payout-registration", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "required": [ "payment_id", "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Identifier of the payment, must be unique within project. Any letters, digits, and symbols in UTF-8 encoding can be used" }, "merchant_callback_url": { "type": "string", "minLength": 1, "maxLength": 255, "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "customer": { "required": [ "id", "ip_address", "email" ], "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Customer identifier unique within the project" }, "email": { "type": "string", "maxLength": 255, "format": "email", "description": "Customer email address" }, "phone": { "pattern": "^[0-9]{4,24}$", "type": "string", "description": "Customer's phone number, can be 4 to 24 digits long" }, "ip_address": { "type": "string", "maxLength": 255, "format": "ip-address", "description": "Customer IP address" } } }, "payment": { "required": [ "amount", "currency" ], "type": "object", "description": "Object that contains payment details", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[:_A-Z0-9]{3,27}$", "description": "Payment currency in the ISO 4217 alpha-3 format" } } } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/verification-of-payee/create": { "post": { "tags": [ "Verification of Payee Service" ], "summary": "/v2/verification-of-payee/create", "description": "Request for verification of payee", "operationId": "POST_v2-verification-of-payee-create", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "account" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoBase" }, { "type": "object", "properties": {}, "required": [ "id" ] } ] }, "account": { "description": "Object that contains account details", "allOf": [ { "$ref": "#/components/schemas/AccountBankPayoutInfo" }, { "type": "object", "properties": {}, "required": [ "customer_name", "number" ] } ] } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/verification-of-payee/result": { "post": { "tags": [ "Verification of Payee Service" ], "summary": "/v2/verification-of-payee/result", "description": "Request for verification of payee result", "operationId": "POST_v2-verification-of-payee-result", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "vop" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "vop": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Id of vop" } }, "description": "Object that contains vop fields." } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/session/applepay": { "post": { "tags": [ "Apple Pay", "sync" ], "summary": "/v2/session/applepay", "description": "Request for receiving the Apple Pay payment session", "operationId": "POST_v2-session-applepay", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/SessionGeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/ApplePaySessionPaymentInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/sale": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/sale", "description": "Request to debit funds from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "etoken": { "$ref": "#/components/schemas/ETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/auth": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/auth", "description": "Request for performing authentication from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-auth", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "etoken": { "$ref": "#/components/schemas/ETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/capture": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/capture", "description": "Request for performing a customer capture from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-capture", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/recurring": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/recurring", "description": "Request to perform recurring payment from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-recurring", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/recurring/cancel": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/recurring/cancel", "description": "Request to cancel recurring payment from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-recurring-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/refund": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/refund", "description": "Request to perform refund payment from the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/applepay/account_verification": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/account_verification", "description": "Request for card verification without performing actual withdrawal via Apple Pay", "operationId": "POST_v2-payment-applepay-account-verification", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoNameValidation" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/AccountVerificationPaymentInfo" }, "etoken": { "$ref": "#/components/schemas/ETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/applepay/cancel": { "post": { "tags": [ "Apple Pay" ], "summary": "/v2/payment/applepay/cancel", "description": "Request to cancel the holding of funds on the customer's card via Apple Pay", "operationId": "POST_v2-payment-applepay-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/CancelPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/atm/{payment_method}/sale": { "post": { "tags": [ "ATM" ], "summary": "/v2/payment/atm/{payment_method}/sale", "operationId": "POST_v2-payment-atm-payment-method-sale", "description": "Request to debit funds from the customer's card by means of ATMs of the supported banks", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payment initiation request", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "return_url" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "account": { "$ref": "#/components/schemas/AccountBankPurchaseInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "card": { "$ref": "#/components/schemas/CardInfoLight" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/atm/{payment_method}/payout": { "post": { "tags": [ "ATM" ], "summary": "/v2/payment/atm/{payment_method}/payout", "operationId": "POST_v2-payment-atm-payment-method-payout", "description": "Request for payout to the customer's card by means of ATMs of the supported banks", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payout initiation request", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "account" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "account": { "$ref": "#/components/schemas/AccountAtmPayoutInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "card": { "$ref": "#/components/schemas/CardInfoLight" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/bancontact/sale": { "post": { "tags": [ "Bancontact" ], "summary": "/v2/payment/bancontact/sale", "description": "Request for payment by using Bancontact", "operationId": "POST_v2-payment-bancontact-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/bancontact/refund": { "post": { "tags": [ "Bancontact" ], "summary": "/v2/payment/bancontact/refund", "description": "Request for refund by using Bancontact", "operationId": "POST_v2-payment-bancontact-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" } } } } }, "required": true }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/banks/{payment_method}/sale": { "post": { "tags": [ "Banks" ], "summary": "/v2/payment/banks/{payment_method}/sale", "operationId": "POST_v2-payment-banks-payment-method-sale", "description": "Request to debit funds from the customer's card in one of the supported banks", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payment initiation request", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "account": { "$ref": "#/components/schemas/AccountBankPurchaseInfo" }, "payment": { "$ref": "#/components/schemas/PaymentBanksInfo" }, "return_url": { "oneOf": [ { "$ref": "#/components/schemas/ReturnUrl" }, { "type": "string", "description": "URL to which customer is redirected after payment performing", "minLength": 1 } ] }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/banks/{payment_method}/payout": { "post": { "tags": [ "Banks" ], "summary": "/v2/payment/banks/{payment_method}/payout", "operationId": "POST_v2-payment-banks-payment-method-payout", "description": "Request to credit funds to the customer's card in one of the supported banks", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Payout initiation request", "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "account" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "account": { "$ref": "#/components/schemas/AccountBankPayoutInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "card": { "$ref": "#/components/schemas/CardInfoLight" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/banks/{payment_method}/refund": { "post": { "tags": [ "Banks" ], "summary": "/v2/payment/banks/{payment_method}/refund", "operationId": "POST_v2-payment-banks-payment-method-refund", "description": "Request for refund to the customer's card in one of the supported banks", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Refund initiation request", "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/bank-transfer/{payment_method}/sale": { "post": { "tags": [ "Bank Transfer" ], "summary": "/v2/payment/bank-transfer/{payment_method}/sale", "description": "Request for transferring of funds from the customer's bank account in one of the supported banks", "operationId": "POST_v2-payment-bank-transfer-method-sale", "parameters": [ { "name": "payment_method", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/BankTransferCustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "account": { "$ref": "#/components/schemas/AnotherAccountBankInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/bank-transfer/{payment_method}/payout": { "post": { "tags": [ "Bank Transfer" ], "summary": "/v2/payment/bank-transfer/{payment_method}/payout", "description": "Request for transferring of funds to the customer's bank account in one of the supported banks", "operationId": "POST_v2-payment-bank-transfer-method-payout", "parameters": [ { "name": "payment_method", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "sender": { "$ref": "#/components/schemas/SenderInfo" }, "account": { "$ref": "#/components/schemas/AccountBankInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "additional_data": { "$ref": "#/components/schemas/AdditionalData" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/bank-transfer/{payment_method}/refund": { "post": { "tags": [ "Bank Transfer" ], "summary": "/v2/payment/bank-transfer/{payment_method}/refund", "description": "Request for refund transferring to the customer's bank account in one of the supported banks", "operationId": "POST_v2-payment-bank-transfer-varying-method-refund", "parameters": [ { "name": "payment_method", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "account": { "$ref": "#/components/schemas/AccountBankRefundInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/blik/sale": { "post": { "tags": [ "Blik" ], "summary": "/v2/payment/blik/sale", "description": "Request for payment through blik payment method", "operationId": "POST_v2-payment-blik-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/blik/refund": { "post": { "tags": [ "Blik" ], "summary": "/v2/payment/blik/refund", "description": "Request for refund through blik payment method", "operationId": "POST_v2-payment-blik-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/bnpl/humm/sale": { "post": { "tags": [ "BNPL" ], "summary": "/v2/payment/bnpl/humm/sale", "description": "BNPL sale", "operationId": "POST_v2-payment-bnpl-humm-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment", "customer" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoBnplSale" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/cup/union/sale": { "post": { "tags": [ "China UnionPay" ], "summary": "/v2/payment/cup/union/sale", "description": "Request to debit funds from the customer's account in China UnionPay system by using CUP payment method union", "operationId": "POST_v2-payment-cup-union-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "return_url" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "return_url": { "$ref": "#/components/schemas/CupReturnUrl" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/unionpay/refund": { "post": { "tags": [ "China UnionPay" ], "summary": "/v2/payment/unionpay/refund", "operationId": "POST_v2-payment-unionpay-refund", "description": "Request for refund through the UnionPay payment method", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/directdebit/{payment_method}/sale": { "post": { "tags": [ "Direct debit" ], "summary": "/v2/payment/directdebit/{payment_method}/sale", "description": "Request for purchase with mandate registrations", "operationId": "POST_v2-payment-directdebit-payment_method-sale", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringRequiredInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/directdebit/{payment_method}/contract/registration": { "post": { "tags": [ "Direct debit" ], "summary": "/v2/payment/directdebit/{payment_method}/contract/registration", "description": "Request to mandate registrations without making payment", "operationId": "POST_v2-payment-directdebit-payment_method-contract-registration", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfoDirectDebit" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringRequiredInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/directdebit/{payment_method}/recurring": { "post": { "tags": [ "Direct debit" ], "summary": "/v2/payment/directdebit/{payment_method}/recurring", "description": "Request to perform recurring payment from the customer's directdebit account", "operationId": "POST_v2-payment-directdebit-recurring", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "recurring_id": { "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases", "type": "integer" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/directdebit/{payment_method}/recurring/update": { "post": { "tags": [ "Direct debit" ], "summary": "/v2/payment/directdebit/{payment_method}/recurring/update", "description": "Request to perform recurring payment update info", "operationId": "POST_v2-payment-directdebit-recurring-update", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringUpdateInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/directdebit/{payment_method}/recurring/cancel": { "post": { "tags": [ "Direct debit" ], "summary": "/v2/payment/directdebit/{payment_method}/recurring/cancel", "description": "Request to perform recurring payment cancel", "operationId": "POST_v2-payment-directdebit-recurring-cancel", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/recurring/info": { "post": { "tags": [ "Requests for recurring" ], "summary": "/v2/payment/recurring/info", "description": "Request to get info about recurring payment conditions", "operationId": "POST_v2-payment-recurring-info", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "type": "object", "description": "Object that contains general request details", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "required": [ "project_id", "signature" ] }, "recurring": { "type": "object", "description": "Object that contains the identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique identifier of the recurring payment in the payment platform" } }, "required": [ "id" ] } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecurringInfoSuccess" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/refund": { "post": { "tags": [ "Requests for refunding specific payments" ], "summary": "/v2/payment/refund", "description": "* Request for full or partial refund to the customer's payment method.\n* Refund is requested in the same currency that the payment was performed.\n* The refund amount can be less than or equal to the amount of the initial payment. The partial refund amount is specified in the parameter `amount`.\n* If the refund amount is not specified in the request, the full amount of the initial payment is refunded", "operationId": "POST_v2-payment-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "addendum": { "$ref": "#/components/schemas/Addendum" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/sale": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/sale", "description": "Request to debit funds from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "etoken": { "$ref": "#/components/schemas/GooglePayETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/auth": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/auth", "description": "Request for performing authentication from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-auth", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "etoken": { "$ref": "#/components/schemas/GooglePayETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "sender": { "$ref": "#/components/schemas/Descriptor" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/capture": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/capture", "description": "Request for performing a customer capture from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-capture", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/recurring": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/recurring", "description": "Request to perform recurring payment from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-recurring", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/recurring/cancel": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/recurring/cancel", "description": "Request to cancel recurring payment from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-recurring-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/refund": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/refund", "description": "Request to perform refund payment from the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/payment/googlepay/account_verification": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/account_verification", "description": "Request for card verification without performing actual withdrawal via Google Pay", "operationId": "POST_v2-payment-googlepay-account-verification", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "etoken" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoNameValidation" }, "payment": { "$ref": "#/components/schemas/AccountVerificationPaymentInfo" }, "etoken": { "$ref": "#/components/schemas/GooglePayETokenInfoLight" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "avs_data": { "$ref": "#/components/schemas/AvsInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/googlepay/cancel": { "post": { "tags": [ "Google Pay" ], "summary": "/v2/payment/googlepay/cancel/etoken", "description": "Request to cancel the holding of funds on the customer's card via Google Pay", "operationId": "POST_v2-payment-googlepay-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/CancelPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/online-banking/{payment_method}/sale": { "post": { "tags": [ "Online banking" ], "summary": "/v2/payment/online-banking/{payment_method}/sale", "description": "Request for payment from customer's online bank account in one of the supported banks", "operationId": "POST_v2-payment-online-banking-payment_method-sale", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "receipt_data": { "$ref": "#/components/schemas/ReceiptData" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "recurring_register": { "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment", "type": "boolean" }, "additional_data": { "$ref": "#/components/schemas/AdditionalData" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/online-banking/{payment_method}/refund": { "post": { "tags": [ "Online banking" ], "summary": "/v2/payment/online-banking/{payment_method}/refund", "description": "Request for refund to the customer's online bank account in one of the supported banks", "operationId": "POST_v2-payment-online-banking-payment_method-refund", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/pix/sale": { "post": { "tags": [ "Pix" ], "summary": "/v2/payment/pix/sale", "description": "Request for payment through the Pix payment method", "operationId": "POST_v2-payment-pix-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/pix/payout": { "post": { "tags": [ "Pix" ], "summary": "/v2/payment/pix/payout", "description": "Request for payout through the Pix payment method", "operationId": "POST_v2-payment-pix-payout", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "account": { "$ref": "#/components/schemas/AccountBankInfo" } } } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/invoice/create": { "post": { "tags": [ "Payment links" ], "summary": "/v2/payment/invoice/create", "description": "Request to create an invoice payment", "operationId": "POST_v2-payment-invoice-create", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfoInvoice" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoInvoice" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfoInvoice" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "operation_type": { "type": "string", "enum": [ "sale", "auth", "contract registration" ], "description": "Operation type for customer to pay. Default is sale." }, "send_email": { "type": "boolean", "description": "Send automatic email to customer or not" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Payload parsing or data structure error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/invoice/card/token/create": { "post": { "tags": [ "Payment links" ], "summary": "/v2/payment/invoice/card/token/create", "operationId": "POST_v2-payment-invoice-card-token-create", "description": "Create invoice payment by token", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "token" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfoInvoice" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoInvoice" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfoInvoiceByToken" }, { "$ref": "#/components/schemas/CryptoPayment" } ] }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recipient": { "$ref": "#/components/schemas/RecipientForCard" }, "token": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Token of the customer's card in Gate" }, "operation_type": { "type": "string", "enum": [ "sale", "auth" ], "description": "Operation type for customer to pay. Default is sale." }, "send_email": { "type": "boolean", "description": "Send automatic email to customer or not" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "booking_info": { "$ref": "#/components/schemas/BookingInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Payload parsing or data structure error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/invoice/cancel": { "post": { "tags": [ "Payment links" ], "summary": "/v2/payment/invoice/cancel", "operationId": "POST_v2-payment-invoice-cancel", "description": "Request to cancel invoice payment", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfoInvoice" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Payload parsing or data structure error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/sale": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/sale", "description": "Request for payment through the Skrill payment method", "operationId": "POST_v2-payment-skrill-sale", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "return_url" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/1-tap": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/1-tap", "description": "Request for OneClick payment through the Skrill payment method", "operationId": "POST_v2-payment-skrill-1-tap", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "general", "customer", "payment", "recurring" ], "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/recurring/update": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/recurring/update", "description": "Request to update or change recurring conditions of the payment through the Skrill payment method", "operationId": "POST_v2-payment-skrill-recurring-update", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringUpdateInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/recurring/cancel": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/recurring/cancel", "description": "Request to cancel recurring payment through the Skrill payment method", "operationId": "POST_v2-payment-skrill-recurring-cancel", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/payout": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/payout", "description": "Request for payout through the Skrill payment method", "operationId": "POST_v2-payment-skrill-payout", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "account", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/SkrillCustomerInfo" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/skrill/refund": { "post": { "tags": [ "Skrill" ], "summary": "/v2/payment/skrill/refund", "description": "Request for refund through the Skrill payment method", "operationId": "POST_v2-payment-skrill-refund", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "account", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/SkrillCustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/sale": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/sale", "description": "Request for payment via methods that support e-wallets", "operationId": "POST_v2-payment-wallet-paymentmethod-sale", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "account": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AccountInfo" }, { "type": "object", "properties": { "customer_name": { "type": "string", "description": "Account owner full name" } } } ] }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "addendum": { "$ref": "#/components/schemas/AddendumData" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/auth": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/auth", "description": "First step DMS for APS", "operationId": "POST_v2-payment-wallet-paymentmethod-auth", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "return_url" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/capture": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/capture", "description": "First step DMS for APS", "operationId": "POST_v2-payment-wallet-paymentmethod-capture", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "properties": { "amount": { "type": "integer", "description": "Payment amount, can be equal to, less or more than in the initial auth request. If the amount is less or more than in the auth request a decremental or incremental operation is created automatically" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency in ISO 4217 alpha-3 format, must match the currency in the initial auth request" } } } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/cancel": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/cancel", "description": "Cancel step DMS for APS", "operationId": "POST_v2-payment-wallet-paymentmethod-cancel", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/CancelPaymentInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" }, "callback": { "$ref": "#/components/schemas/CallbackInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/sale/1click": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/sale/1click", "description": "Request for OneClick payment through the payment method that supports such payments by using e-wallets", "operationId": "POST_v2-payment-wallet-payment-method-sale-1click", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "saved_account_id" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoWithId" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringInfo" }, "saved_account_id": { "type": "integer" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/recurring": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/recurring", "description": "Request to perform regular payment from the customer's e-wallet", "operationId": "POST_v2-payment-wallet-payment-method-recurring", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment", "customer", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoWalletRecurring" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/1-tap": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/1-tap", "description": "Request for OneClick payment through the payment method that supports such payments by using e-wallets", "operationId": "POST_v2-payment-wallet-payment-method-1-tap", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/recurring/update": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/recurring/update", "description": "Request to update or change recurring conditions of the payment through the payment method that supports such payments by using e-wallets", "operationId": "POST_v2-payment-recurring-update", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringUpdateInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/recurring/cancel": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/recurring/cancel", "description": "Request to cancel recurring payments through the payment method that supports such payments by using e-wallets", "operationId": "POST_v2-payment-recurring-cancel", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "recurring": { "$ref": "#/components/schemas/RecurringIdInfo" }, "interface_type": { "$ref": "#/components/schemas/SourceInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/refund": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/refund", "description": "Request for refund to the customer's e-wallet", "operationId": "POST_v2-payment-wallet-refund", "parameters": [ { "name": "payment_method", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "merchant": { "$ref": "#/components/schemas/MerchantInfo" }, "payment": { "$ref": "#/components/schemas/RefundPaymentInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/wallet/{payment_method}/payout": { "post": { "tags": [ "Wallet" ], "summary": "/v2/payment/wallet/{payment_method}/payout", "description": "Request for payout via methods that use e-wallets", "operationId": "POST_v2-payment-wallet-payment-method-payout", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "customer", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfoPayout" }, "account": { "$ref": "#/components/schemas/AccountInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" }, "return_url": { "$ref": "#/components/schemas/ReturnUrl" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GateSuccessResponse" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/info": { "post": { "tags": [ "Requests for customer details" ], "summary": "/v2/customer/info", "description": "Request for retrieving customer data by customer identifier within the project", "operationId": "POST_v2-customer-info", "requestBody": { "content": { "application/json": { "schema": { "required": [ "customer" ], "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerGeneralInfo" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "customer", "signature" ], "type": "object", "properties": { "customer": { "required": [ "ip_address", "project_id" ], "type": "object", "properties": { "id": { "type": "string", "description": "Customer identifier unique within the project" }, "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`" }, "country": { "pattern": "^[A-Z]{2}$", "type": "string", "description": "Customer country code in the ISO 3166-1 alpha-2 format" }, "phone": { "pattern": "^[0-9]{4,24}$", "type": "string", "description": "Customer's phone number, can be 4 to 24 digits long" }, "email": { "maxLength": 255, "type": "string", "description": "Customer email address", "format": "email" }, "day_of_birth": { "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "type": "string", "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" }, "first_name": { "maxLength": 255, "type": "string", "description": "Customer first name" }, "last_name": { "maxLength": 255, "type": "string", "description": "Customer last name" }, "address": { "maxLength": 255, "type": "string", "description": "Customer address" }, "zip": { "maxLength": 255, "type": "string", "description": "Customer address postal code" }, "city": { "maxLength": 256, "type": "string", "description": "Name of customer's address city" }, "street": { "maxLength": 256, "type": "string", "description": "Street of customer address" }, "browser": { "maxLength": 512, "type": "string", "description": "A string that identifies the customer browser information" }, "ip_address": { "maxLength": 255, "type": "string", "description": "Customer IP address, both IPv4 and IPv6 are supported", "format": "ip-address" }, "billing": { "type": "object", "properties": { "country": { "pattern": "^[A-Z]{2}$", "type": "string", "description": "Country code of the customer's billing address in ISO 3166-1 alpha-2 format" }, "region": { "type": "string", "description": "The region or state of the customer's billing address" }, "city": { "type": "string" }, "address": { "type": "string" }, "postal": { "type": "string" } }, "description": "Billing info" }, "created_at": { "type": "string" } } }, "signature": { "type": "string", "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)." } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/saved_account/list": { "post": { "tags": [ "Requests for customer details" ], "summary": "/v2/customer/saved_account/list", "description": "Request for retrieving saved customer's payment instruments in the project", "operationId": "POST_v2-customer-saved_account-list", "requestBody": { "content": { "application/json": { "schema": { "required": [ "customer", "payment_method" ], "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerGeneralInfo" }, "payment_method": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Identifier of the payment method in the payment platform" } }, "description": "Object that contains customer details" } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "accounts", "signature" ], "type": "object", "properties": { "signature": { "type": "string", "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)." }, "accounts": { "type": "array", "description": "Array that contains information about the customer's saved payment accounts", "items": { "$ref": "#/components/schemas/SavedAccount" } } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorItems" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/customer/saved_account/delete": { "post": { "tags": [ "Requests for customer details" ], "summary": "/v2/customer/saved_account/delete", "description": "Request for removal of saved card or other saved account of the customer", "operationId": "POST_v2-customer-saved_account-delete", "requestBody": { "content": { "application/json": { "schema": { "required": [ "customer", "saved_account_id" ], "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/CustomerGeneralInfo" }, "saved_account_id": { "type": "integer", "description": "The ID of the customer's saved account received from the payment platform" }, "payment_method": { "type": "string", "default": "card", "enum": [ "card" ], "description": "Payment method type for saved accounts set" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "message", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of removing of the saved used account" }, "message": { "type": "string", "description": "Notification of the removal of the saved customer's account" } }, "description": "" } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorItems" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payment/status/request": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/payment/status/request", "description": "Request for clarifying the status and other data of the payment by ProjectId and RequestId", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "request_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer" }, "request_id": { "maxLength": 100, "type": "string" }, "signature": { "maxLength": 255, "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatusResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Payment not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-internal": false } }, "/v2/payment/status": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/payment/status", "description": "Request for retrieving the status and other data of the payment. Keep in mind that depending on the individual settings of the project the format of the response may vary. Presented below is the default format of the response", "operationId": "POST_v2-payment-status", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "destination": { "type": "string", "enum": [ "merchant", "terminal" ], "default": "merchant", "description": "Destination of notification (terminal, merchant, etc.)" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentStatusResponse" } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorItems" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/info/available-methods/{payment_direction}/list": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/available-methods/{payment_direction}/list", "description": "Returns availability of requested payment methods", "operationId": "POST_v2-info-available-methods-list", "parameters": [ { "name": "payment_direction", "in": "path", "description": "Payment direction", "required": true, "schema": { "type": "string", "enum": [ "payin", "payout" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "description": "Object that contains general request details", "type": "object", "required": [ "project_id", "signature" ], "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "payment_method_list": { "type": "array", "description": "Array of elements containing information about requested payment methods", "items": { "type": "object", "required": [ "payment_method" ], "properties": { "payment_method": { "type": "string", "description": "Payment method code" } } } } } } } }, "required": false }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "array", "description": "Array that contains information about payment methods", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorItems" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/info/banks/bycountry": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/bycountry", "operationId": "POST_v2-info-banks-bycountry", "description": "Returns bank list broken down by country", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "signature", "country" ], "type": "object", "properties": { "project_id": { "type": "integer" }, "signature": { "type": "string" }, "country": { "type": "string", "format": "[A-Z][A-Z][A-Z]" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/info/banks/byaggregator": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/byaggregator", "operationId": "POST_v2-info-banks-byaggregator", "description": "Returns bank list broken down by aggregator", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "aggregator_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer" }, "aggregator_id": { "type": "integer" }, "signature": { "type": "string", "minLength": 1 } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/info/banks/bypaymentmethod": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/bypaymentmethod", "operationId": "POST_v2-info-banks-bypaymentmethod", "description": "Returns bank list broken down by payment method", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "payment_method_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer" }, "payment_method_id": { "type": "integer" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency in ISO 4217 alpha-3 format" }, "type": { "type": "string" }, "signature": { "type": "string", "minLength": 1 } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/info/banks/byprovider": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/byprovider", "operationId": "POST_v2-info-banks-byprovider", "description": "Returns bank list broken down by provider", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "provider_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer" }, "provider_id": { "type": "integer" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency in ISO 4217 alpha-3 format" }, "type": { "type": "string" }, "signature": { "type": "string", "minLength": 1 } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/info/banks/{payment_method}/{operationType}/list": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/{payment_method}/{operationType}/list", "operationId": "POST_v2-info-banks-payment-method-operationType-list", "description": "Request to retrieve the list of banks available for the specified payment method and operation type", "parameters": [ { "name": "payment_method", "in": "path", "description": "Payment method", "required": true, "schema": { "type": "string" } }, { "name": "operationType", "in": "path", "description": "Operation type", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentBanksInfo" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/info/banks/{parentMethod}/{childMethod}/{operationType}/list": { "post": { "tags": [ "Requests for information", "sync" ], "summary": "/v2/info/banks/{parentMethod}/{childMethod}/{operationType}/list", "operationId": "POST_v2-info-banks-parentMethod-childMethod-operationType-list", "description": "Request to retrieve the list of banks available for the specified payment method and operation type (for groupped methods)", "parameters": [ { "name": "parentMethod", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "childMethod", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "operationType", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "payment": { "$ref": "#/components/schemas/PaymentInfo" } } } } }, "required": true }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": {} } } } } }, "400": { "description": "Validation errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid JSON data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "x-codegen-request-body-name": "request" } }, "/v2/recurring/retry-custom-schedule/save": { "post": { "tags": [ "Requests for recurring" ], "summary": "/v2/recurring/retry-custom-schedule/save", "description": "Request to save custom recurring retry schedule", "operationId": "POST_v2-recurring-retry-custom-schedule-save", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "interval_days" ], "type": "object", "properties": { "general": { "required": [ "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains general request details" }, "interval_days": { "type": "array", "minItems": 1, "maxItems": 10, "uniqueItems": true, "description": "The schedule by days when retry attempts for charging funds should be made", "items": { "type": "integer", "minimum": 1, "maximum": 10 } } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "status" ], "type": "object", "properties": { "status": { "maxLength": 255, "type": "string" } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/recurring/retry-custom-schedule/info": { "post": { "tags": [ "Requests for recurring" ], "summary": "/v2/recurring/retry-custom-schedule/info", "description": "Request to get custom recurring retry schedule", "operationId": "POST_v2-recurring-retry-custom-schedule-info", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "required": [ "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains general request details" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "project_id", "schedule" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of merchant project received from Ecommpay" }, "schedule": { "type": "object", "properties": { "interval_days": { "type": "array", "description": "The schedule by days when retry attempts for charging funds should be made", "items": { "type": "integer" } }, "status": { "type": "string", "enum": [ "active", "disabled" ] } } } } }, "examples": { "Example 1": { "value": { "project_id": 0, "schedule": { "interval_days": [ 1 ], "status": "active" } } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/recurring/retry-custom-schedule/disable": { "post": { "tags": [ "Requests for recurring" ], "summary": "/v2/recurring/retry-custom-schedule/disable", "description": "Request to disable custom recurring retry schedule", "operationId": "POST_v2-recurring-retry-custom-schedule-disable", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general" ], "type": "object", "properties": { "general": { "required": [ "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains general request details" } } } } }, "required": false }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "required": [ "status" ], "type": "object", "properties": { "status": { "maxLength": 255, "type": "string" } } } } } }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/recurring/retry_stop": { "post": { "tags": [ "Requests for recurring" ], "summary": "/v2/recurring/retry_stop", "description": "Request for restrict retry operation", "operationId": "POST_v2-recurring-retry_stop", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "recurring", "trigger_operation_id" ], "type": "object", "properties": { "general": { "type": "object", "description": "Object that contains general request details", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "required": [ "project_id", "signature" ] }, "recurring": { "type": "object", "description": "Object that contains Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique identifier of the recurring payment in the payment platform" } }, "required": [ "id" ] }, "trigger_operation_id": { "description": "Identifier of operation which initiated retry", "type": "integer" } } } } }, "required": false }, "responses": { "200": { "description": "OK" }, "400": { "description": "Data validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Access denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Invalid data structure or JSON parsing error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "AccountInfo": { "required": [ "number" ], "type": "object", "properties": { "number": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Customer's account number. Example: `21312`" }, "save": { "type": "boolean", "default": false, "description": "Indicator specifying whether the customer's account details should be saved" } }, "description": "Object that contains the minimum required details of the customer's payment instrument - account/wallet/voucher etc." }, "AccountAtmPayoutInfo": { "description": "Object that contains account information for payout performing by using ATMs", "type": "object", "properties": { "bank_id": { "type": "integer", "minimum": 1, "description": "Bank identifier received from the payment platform" }, "customer_name": { "type": "string", "description": "Account owner full name", "minLength": 1 }, "branch": { "type": "string", "description": "Bank branch", "maxLength": 255 }, "number": { "type": "string", "description": "Customer's account number. Example: `21312`", "minLength": 1 }, "region_id": { "type": "integer", "minimum": 1, "description": "Region or state identifier of the bank branch location received from the payment platform. Example: `3`" }, "city": { "type": "string", "maxLength": 255, "description": "Bank branch city code" } }, "required": [ "bank_id", "region_id" ] }, "AccountBankInfo": { "description": "Object that contains the account details of bank which is used for payment processing", "allOf": [ { "$ref": "#/components/schemas/AccountInfo" }, { "type": "object", "properties": { "type": { "type": "string", "maxLength": 255, "description": "Account type." }, "bank_id": { "type": "integer", "minimum": 1, "description": "Bank identifier received from the payment platform. Example: `137" }, "customer_name": { "type": "string", "description": "First name and last name of the account holder. Example: `John Johnson`" }, "security_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Payment confirmation code. Some payment methods may require this parameter (depending on the methods themselves). Example: `852923" }, "swift_code": { "type": "string", "minLength": 8, "maxLength": 11, "description": "SWIFT bank identification code" }, "routing_number": { "type": "string", "maxLength": 255, "description": "Identifier of the bank in the transfer system" }, "routing_type": { "type": "string", "maxLength": 255, "description": "Type of bank transfer. Possible values: `ACH CODE`—for the USA, `BANK CODE`—for Honkong, `BSB CODE`—for Australia, `IFSC`—for India, `SORT CODE`—for Great Britain, `TRANSIT NUMBER`—for Canada, `BRANCH CODE`—for Brazil, `SWIFT`—for other countries that support this method." }, "iban": { "type": "string", "minLength": 5, "maxLength": 34, "description": "International bank account number" }, "bank_name": { "type": "string", "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`" }, "bank_branch_name": { "type": "string", "description": "Name of the bank branch" }, "bank_branch_code": { "type": "string", "description": "Code of the bank branch" }, "bank_branch_city": { "type": "string", "description": "City of the bank branch's location" }, "bank_branch_address": { "type": "string", "description": "Address of bank branch" }, "bank_code": { "type": "string", "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`" }, "fin": { "type": "string", "description": "Financial institution number" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country code in the ISO 3166-1 alpha-2 format" } } } ] }, "AccountBankPayoutInfo": { "description": "Object that contains the details of the customer's bank account for payout performing", "allOf": [ { "$ref": "#/components/schemas/AccountInfo" }, { "type": "object", "properties": { "bank_id": { "type": "integer", "minimum": 1, "description": "Bank identifier received from the payment platform" }, "customer_name": { "type": "string", "description": "Account owner full name", "minLength": 1 }, "branch": { "type": "string", "description": "Bank branch", "maxLength": 255 }, "number": { "type": "string", "description": "Customer's account number. Example: `21312`", "minLength": 1 }, "region_id": { "type": "integer", "minimum": 1, "description": "Region or state identifier of the bank branch location received from the payment platform. Example: `3`" }, "city": { "type": "string", "maxLength": 255, "description": "Bank branch city code" }, "bank_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`" }, "bank_address": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Address of bank location" }, "bik": { "type": "string", "minLength": 9, "maxLength": 9, "description": "Bank code on the Russian Federation" }, "bank_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`" }, "branch_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Bank branch code" }, "native_customer_name": { "type": "string", "description": "Native account owner full name", "minLength": 1 } } } ] }, "AccountBankPurchaseInfo": { "type": "object", "properties": { "bank_id": { "type": "integer", "minimum": 0, "description": "Bank identifier received from the payment platform" }, "number": { "type": "string", "description": "Customer's account number. Example: `21312`", "minLength": 1 }, "bank_code": { "type": "string", "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`" }, "customer_name": { "type": "string", "description": "Account owner full name", "minLength": 1 } }, "description": "Object that contains the details of the customer's bank account for payment performing" }, "AccountBankRefundInfo": { "type": "object", "properties": { "bank_id": { "type": "integer", "minimum": 0, "description": "Bank identifier received from the payment platform" }, "number": { "type": "string", "description": "Customer's account number. Example: `21312`", "minLength": 1 }, "customer_name": { "type": "string", "description": "Account owner full name", "minLength": 1 } }, "description": "Object that contains the details of the customer's bank account for refund performing" }, "AccountInfoAtMerchant": { "type": "object", "properties": { "additional": { "type": "string", "maxLength": 64, "description": "Additional information about the customer's account in free text such as its identifier" }, "date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date created account. Format: DD-MM-YYYY" }, "change_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date of the most recent change of account data, excluding password updates or resets. Format: DD-MM-YYYY" }, "pass_change_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date of the most recent password change or reset. Format: DD-MM-YYYY" }, "purchase_number": { "type": "integer", "maximum": 9999, "description": "Number of purchases made via the customer's account in the last 6 months, 4 characters maximum" }, "provision_attempts": { "type": "integer", "maximum": 999, "description": "Number of attempts to add a new card to a customer's account in the last 24 hours" }, "activity_day": { "type": "integer", "maximum": 999, "description": "Number of payment attempts in the last 24 hours" }, "activity_year": { "type": "integer", "maximum": 999, "description": "Number of payment attempts in the last 365 days" }, "payment_age": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Card record creation date. Format: DD-MM-YYYY" }, "suspicious_activity": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicator specifying whether the merchant has experienced suspicious activity on the cardholder account. Possible values: `01` —no suspicious activity detected, `02`—suspicious activity detected" }, "auth_method": { "type": "string", "pattern": "^0[1-4]$", "description": "Indicator specifying how the customer was authenticated during their most recent login to the web service. Possible values: `01`—no authentication, `02`—logging in with authentication data kept on file by the merchant,`03`—logging in with the federated identity credentials (for example, Google Account or Facebook ID), `04`—logging in with the use of FIDO authenticator (Fast Identity Online)" }, "auth_time": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}\\d{2}:\\d{2}$", "description": "Date and time of the customer's most recent account login. Format: DD-MM-YYYYhh:mm. Example: `01-10-202213:12`" }, "auth_data": { "type": "string", "maxLength": 255, "description": "Additional login information in free text" }, "age_indicator": { "type": "string", "pattern": "^0[1-5]$", "description": "Number of days since the customer account was created. Possible values: `01`—guest checkout, `02`—the account was created at the moment of making a payment, `03`—fewer than 30 days, `04`—between 30 and 60 day, `05`—more than 60 days" }, "change_indicator": { "type": "string", "pattern": "^0[1-4]$", "description": "Number of days since the most recent change to the account, except for the password change or password reset. Possible values: `01`—the account was updated on the day when the payment was made, `02`—fewer than 30 days, `03`—between 30 and 60 days, `04`—more than 60 days" }, "pass_change_indicator": { "type": "string", "pattern": "^0[1-5]$", "description": "Number of days since the most recent password change or reset. Possible values: `01`—password was not changed or reset, `02`—password was changed or reset on the day when the payment was made, `03`—fewer than 30 days, `04`—between 30 and 60 days, `05`—more than 60 days" }, "payment_age_indicator": { "type": "string", "pattern": "^0[1-5]$", "description": "Number of days since the payment card details were saved to a customer's account. Possible values: 01—guest checkout, 02—card details were saved on the day when the payment was made, 03—fewer than 30 days, 04—between 30 and 60 days, 05—more than 60 days" } }, "description": "An object that contains account data in merchant's web service." }, "AccountOnlineBankingPayoutInfo": { "type": "object", "properties": { "number": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Customer's account number. Example: `21312`" }, "bank_code": { "type": "string", "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`" }, "clearinghouse": { "type": "string", "maxLength": 255, "minLength": 1, "description": "Registration country of the interbank clearing center used by the bank of the account holder. Example: `SWEDEN`" } }, "description": "Object that contains the account details for payout processing" }, "AccountVerificationPaymentInfo": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 0, "description": "Payment amount in minor currency units, should be passed with zero value" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in ISO 4217 alpha-3 format" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment" }, "debt_account": { "type": "string", "maxLength": 10, "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`" } }, "description": "Stub object that contains necessary details for payment instrument verification. Amount should be passed with zero value" }, "AccountVerificationPaymentInfoForCard": { "allOf": [ { "$ref": "#/components/schemas/AccountVerificationPaymentInfo" }, { "$ref": "#/components/schemas/CryptoPayment" }, { "type": "object", "description": "Stub object that contains necessary details for payment instrument verification. Amount should be passed with zero value", "properties": { "debt_account": { "type": "string", "maxLength": 10, "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`" } } }, { "$ref": "#/components/schemas/MotoInfo" } ] }, "ACSReturnUrl": { "type": "object", "properties": { "return_url": { "type": "string", "description": "Return url for authenticated status" }, "3ds_notification_url": { "type": "string", "description": "Url for callback from ACS" } } }, "AddendumData": { "type": "object", "properties": { "lodging": { "oneOf": [ { "$ref": "#/components/schemas/AddendumLodgingInitial" }, { "type": "array", "items": { "$ref": "#/components/schemas/AddendumLodgingInitial" } } ] }, "airlines": { "oneOf": [ { "$ref": "#/components/schemas/AddendumAirlines" }, { "type": "array", "items": { "$ref": "#/components/schemas/AddendumAirlines" } } ] }, "professional_services": { "oneOf": [ { "$ref": "#/components/schemas/AddendumProfessionalServices" }, { "type": "array", "items": { "$ref": "#/components/schemas/AddendumProfessionalServices" } } ] }, "retail": { "oneOf": [ { "$ref": "#/components/schemas/AddendumRetail" }, { "type": "array", "items": { "$ref": "#/components/schemas/AddendumRetail" } } ] } } }, "Addendum": { "type": "object", "properties": { "lodging": { "$ref": "#/components/schemas/AddendumLodging" } } }, "AddendumAirlines": { "required": [ "departure_airport", "departure_date", "departure_time", "ticket", "trip_leg" ], "type": "object", "properties": { "departure_date": { "type": "string", "maxLength": 10, "pattern": "^(?:\\d{2})(1[012]|0?[1-9])(3[01]|[12][0-9]|0?[1-9])$", "description": "Departure date in YYMMDD format" }, "departure_airport": { "type": "string", "maxLength": 3, "description": "Originating airport name’s standard abbreviation" }, "departure_time": { "type": "string", "maxLength": 4, "pattern": "^([0-1][0-9]|2[0-3])[0-5][0-9]$", "description": "Time of departure provided by the airline. Format: HHMM" }, "arrival_time": { "type": "string", "maxLength": 4, "pattern": "^([0-1][0-9]|2[0-3])[0-5][0-9]$", "description": "Arrival time provided by the airline: Format: HHMM" }, "endorsements_restr": { "type": "string", "maxLength": 20, "description": "" }, "exchange_ticket": { "type": "string", "maxLength": 15, "description": "Original ticket number replaced by a new ticket number" }, "ticket": { "$ref": "#/components/schemas/AddendumAirlinesTicket" }, "trip_leg": { "$ref": "#/components/schemas/AddendumAirlinesTripLeg" } } }, "AddendumAirlinesTicket": { "required": [ "customer_ref", "issuing_carrier", "passenger_name", "ticket_number" ], "type": "object", "properties": { "passenger_name": { "type": "string", "maxLength": 20, "description": "Name of the passenger to whom the ticket was issued" }, "ticket_number": { "type": "string", "maxLength": 15, "description": "Number on the ticket" }, "issuing_carrier": { "type": "string", "maxLength": 2, "description": "Standard abbreviation for the airline carrier issuing the ticket" }, "customer_ref": { "type": "string", "maxLength": 25, "description": "Number or code that identifies the customer or consumer." }, "travel_agency_code": { "type": "string", "maxLength": 8, "description": "Code assigned to the travel agency" }, "travel_agency_name": { "type": "string", "maxLength": 25, "description": "Name of the travel agency issuing the ticket" }, "restricted_ticket_indicator": { "type": "boolean", "description": "Identifier noting that the ticket purchased has some restriction associated with its use" }, "ticket_issue_date": { "type": "string", "maxLength": 10, "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$", "description": "Date in which the Ticket was Issued" }, "total_tax_amount": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800`" } } }, "AddendumAirlinesTripLeg": { "required": [ "carrier_code", "destination_airport", "fare_bassis", "flight_number", "service_class", "stop_over_code" ], "type": "object", "properties": { "carrier_code": { "type": "string", "maxLength": 2, "description": "Standard abbreviation for the airline carrier" }, "service_class": { "type": "string", "maxLength": 1, "pattern": "^([F|J|Y|W])$", "description": "Service type (such as coach or first class)" }, "destination_airport": { "type": "string", "maxLength": 3, "description": "Destination airport name’s standard abbreviation" }, "stop_over_code": { "type": "boolean", "description": "Code indicating whether there was a direct or a non-direct flight or route on the same ticket number" }, "fare_bassis": { "type": "string", "maxLength": 6, "description": "Code that carriers assign to a particular ticket type, such as business class or discounted/nonrefundable" }, "flight_number": { "type": "string", "maxLength": 5, "description": "Number that the operating or marketing carrier assigned" } } }, "AddendumInitialCard": { "type": "object", "description": "Available to merchants with eligible MCCs", "properties": { "airlines": { "$ref": "#/components/schemas/AddendumAirlinesCard" }, "lodging": { "$ref": "#/components/schemas/AddendumLodgingInitial" } } }, "AddendumAirlinesCard": { "required": [ "ticket_number", "passenger_name", "customer_ref", "ticket_issuer_code", "ticket_issue_date", "trip_legs" ], "type": "object", "properties": { "ticket_number": { "type": "string", "maxLength": "15", "description": "Ticket number assigned by the issuer", "example": "1051426005635" }, "passenger_name": { "type": "string", "maxLength": "20", "description": "Full passenger name (name and last name, title if available)", "example": "EDDINGTON/ARTHUR MR" }, "ticket_issuer_code": { "type": "string", "maxLength": "2", "description": "IATA 2-character code of the airline that issued the ticket", "example": "AY" }, "ticket_issue_date": { "type": "string", "format": "date", "description": "Date of ticket issuance, in ISO 8601 (YYYY-MM-DD) format", "example": "2025-10-04" }, "customer_ref": { "type": "string", "maxLength": "25", "description": "Identifier of the passenger record in the reservation system", "example": "T7H3PD" }, "travel_agency_code": { "type": "string", "maxLength": "8", "description": "IATA-accreditation code assigned to a travel agency", "example": "2921540" }, "travel_agency_name": { "type": "string", "maxLength": "25", "description": "Name of the travel agency that issued the ticket", "example": "Deep Sky Tours" }, "restricted_ticket_indicator": { "type": "boolean", "description": "Indicator that specifies refund restrictions applied to the ticket, (i.e. the ticket is non-refundable or can be returned)", "example": true }, "computerized_reservation_system": { "type": "string", "maxLength": "4", "description": "Code of the computerised reservation system, may be needed for payments in Germany, (STRT – Start, PARS – TWA, DATS – Delta, SABR – Sabre, DALA – Covia-Apollo, BLAN – Dr. Blank, DERD – DER, TUID – TUI)", "example": "TUID" }, "total_fare_amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Total amount of the ticket", "example": 23500 }, "total_tax_amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount of all the taxes associated with the ticket", "example": 135 }, "total_fees_amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount of the fees associated with the ticket", "example": 1447 }, "trip_legs": { "required": [ "trip_leg1" ], "type": "object", "properties": { "trip_leg1": { "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg" }, "trip_leg2": { "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg" }, "trip_leg3": { "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg" }, "trip_leg4": { "$ref": "#/components/schemas/AddendumAirlinesCardTripLeg" } } } } }, "AddendumAirlinesCardTripLeg": { "required": [ "flight_number", "carrier_code", "departure_airport", "departure_at", "destination_airport", "arrival_at", "stop_over_code", "service_class", "fare_bassis" ], "type": "object", "properties": { "flight_number": { "type": "string", "maxLength": "5", "description": "The flight number assigned by operating or marketing carrier. Airline carrier code must not be included", "example": "156" }, "carrier_code": { "type": "string", "maxLength": "2", "description": "2-character IATA carrier code", "example": "AY" }, "departure_airport": { "type": "string", "maxLength": "3", "description": "3-character IATA code of the departure airport", "example": "IVL" }, "departure_at": { "type": "string", "format": "date-time", "description": "Date and time of departure, in the YYYY-MM-DDThh:mm:ss±hh:mm format (according to ISO 8601)", "example": "2025-10-31T16:05:00+02:00" }, "destination_airport": { "type": "string", "maxLength": "3", "description": "3-character IATA code of the destination airport", "example": "PFO" }, "arrival_at": { "type": "string", "format": "date-time", "description": "Date and time of arrival, in the YYYY-MM-DDThh:mm:ss±hh:mm format (according to ISO 8601)", "example": "2025-10-31T20:15:00+02:00" }, "stop_over_code": { "type": "boolean", "description": "Indicates whether the flight is direct (no stopover) or non-direct (includes stopover)", "example": true }, "service_class": { "type": "string", "maxLength": "1", "description": "IATA code of service class (R – Supersonic, P – First Class Premium, F – First Class, A – First Class Discounted; J – Business Class Premium, C – Business Class, {D, I, Z} – Business Class Discounted; W – Economy/Coach Premium, {S, Y} – Economy/Coach, {B, H, K, L, M, N, Q, T, V, X} – Economy/Coach Discounted)", "example": "Y" }, "fare_bassis": { "type": "string", "maxLength": "6", "description": "Particular fare applied by the carrier", "example": "YE3MFI" }, "exchange_ticket": { "type": "string", "maxLength": "15", "description": "The original ticket number replaced by a new ticket number (if applicable)", "example": "3904082308998" }, "conjunct_ticket": { "type": "string", "maxLength": "15", "description": "The ticket that contains additional coupons on an itinerary that is more than four segments (if present)", "example": "6065511855011" }, "coupon_number": { "type": "string", "maxLength": "3", "pattern": "\\d", "description": "Number of a coupon assigned to the leg inside the ticket", "example": "1" }, "endorsements_restr": { "type": "string", "maxLength": "20", "description": "Added notation specifying any relevant information about restrictions, additional data, and endorsement information", "example": "No changes allowed" } } }, "AddendumLodging": { "type": "object", "properties": { "check_out_date": { "maxLength": 19, "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$", "type": "string", "description": "Customer's check-out date in the dd-mm-yyyy format. Example: `22-12-2019`" }, "room": { "type": "object", "properties": { "rate": { "maximum": 999999999999, "type": "integer", "description": "Daily room charges exclusive of taxes and fees. Is used to calculate base lodging cost. This psrsmeter is provided in minor units of currency. Example: `12`" }, "number_of_nights": { "maximum": 99, "minimum": 1, "type": "integer", "description": "Total number of nights for which a room was contracted during a lodging stay. Example: `10" } } }, "total_tax": { "maximum": 999999999999, "minimum": 0, "type": "number", "description": "Total amount of sales tax or value added tax (VAT) on the total purchase amount. This parameter is provided in minor units of the payment's currency" }, "charges": { "$ref": "#/components/schemas/AddendumLodgingCharges" } }, "description": "Available only if MCC is 3501-3999 or 7011" }, "AddendumLodgingCharges": { "type": "object", "properties": { "room_service": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the room service charges. This parameter provided in minor units of currency" }, "bar_or_lounge": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the lounge or bar charges. This parameter provided in minor units of currency" }, "transportation": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the transportation charges. This parameter provided in minor units of currency" }, "gratuity": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the gratuity charges. This parameter provided in minor units of currency" }, "conference_room": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the charges associated with conference room use. This parameter provided in minor units of currency" }, "audio_or_visual": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the audiovisual equipment charges. This parameter provided in minor units of currency" }, "banquet": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the banquet charges. This parameter provided in minor units of currency" }, "internet_access": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of the Internet access charges. This parameter provided in minor units of currency" }, "early_departure": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount charged because of early departure. This parameter provided in minor units of currency" }, "phone": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of charges for all phone calls. This parameter provided in minor units of currency" }, "restaurant": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of all restaurant charges. This parameter provided in minor units of currency" }, "minibar": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of in-room “mini-bar” service charges. This parameter provided in minor units of currency" }, "gift_shop": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of all gift shop and specialty shop charges. This parameter provided in minor units of currency" }, "laundry_or_cleaning": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount of cleaning charges. This parameter provided in minor units of currency" }, "valet": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Charges associated with the use of valet services. This parameter provided in minor units of currency" }, "movie": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount charged for in-room movies. This parameter provided in minor units of currency" }, "business_center": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount charged for business center use and supplies. This parameter provided in minor units of currency" }, "health_club": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Amount charged for health club use and supplies. This parameter provided in minor units of currency" } } }, "AddendumLodgingInitial": { "required": [ "check_in_date", "check_out_date", "customer_service_toll_free_number", "fire_safety_act_indicator", "folio_number", "room" ], "type": "object", "properties": { "customer_service_toll_free_number": { "type": "string", "maxLength": 17, "description": "A toll-free phone number for the customer service of the booked hotel or other type of accommodation. Example: `18005553535`" }, "hotel_name": { "type": "string", "maxLength": 255, "description": "Name of the hotel or other type of accommodation where the customer is staying. Example:`Best Eastern`" }, "check_in_date": { "type": "string", "maxLength": 19, "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$", "description": "Customer's check-in date in the dd-mm-yyyy format. Example: `10-12-2019`" }, "check_out_date": { "type": "string", "maxLength": 19, "pattern": "^(3[01]|[12][0-9]|0?[1-9])-(1[012]|0?[1-9])-((?:19|20)\\d{2})$", "description": "Customer's check-out date in the dd-mm-yyyy format. Example: `22-12-2019`" }, "folio_number": { "type": "string", "maxLength": 25, "description": "Card acceptor’s internal invoice or billing ID reference number. Example: `56265655ABC`" }, "room": { "description": "Object with room details", "properties": { "tax": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "Tax amount information such as the daily room tax, occupancy tax, energy tax, and tourist tax amounts. Example: `25`" }, "rate": { "type": "integer", "maximum": 999999999999, "description": "Daily room charges exclusive of taxes and fees. this parameter is used to calculate base lodging cost and is provided in minor units of currency. Example: `12`" }, "number_of_nights": { "type": "integer", "minimum": 1, "maximum": 99, "description": "Total number of nights for which room was contracted during lodging stay" } }, "required": [ "rate" ] }, "fire_safety_act_indicator": { "type": "boolean", "description": "Facility complies with the Hotel and Motel Fire Safety Act of 1990 (PL101-391) or similar legislation" }, "guest_name": { "type": "string", "maxLength": 40, "description": "Customer full name" }, "guest_number": { "type": "string", "maxLength": 25, "description": "Number assigned to the lodging customer" }, "billing_adjustment": { "type": "string", "maxLength": 12, "description": "Additional charges incurred after the cardholder departure" }, "property_phone_number": { "type": "string", "maxLength": 17, "description": "Specific lodging property location by its local phone number" }, "no_show_indicator": { "type": "boolean", "description": "Customer did not show up after making lodging reservation" }, "prepaid_expenses": { "type": "integer", "maximum": 999999999999, "description": "Amount of deposit or other prepaid amounts for the lodging stay. This parameter is provided in minor units of currency." }, "total_tax": { "type": "number", "minimum": 0, "maximum": 999999999999, "description": "The amount of all the taxes associated with the lodging. Applicable only to the Visa, Visa Electron and Maestro cards. Not applicable for Mastercard. This parameter is provided in minor units of the payment's currency" }, "charges": { "$ref": "#/components/schemas/AddendumLodgingCharges" } }, "description": "Available only if MCC is 3501-3999 or 7011" }, "AddendumProfessionalServices": { "required": [ "admission_notice_url" ], "type": "object", "properties": { "admission_notice_url": { "type": "string", "description": "Admission notice url" } } }, "AddendumRetail": { "required": [ "goods", "quantity" ], "type": "object", "properties": { "goods": { "type": "string", "description": "Name goods" }, "quantity": { "type": "integer", "description": "Quantity goods" } } }, "AdditionalData": { "type": "object", "properties": { "avs_data": { "$ref": "#/components/schemas/AvsInfo" } }, "description": "Object that contains additional payment information submission for payment processing. The object can contain any objects requested by the payment platform as specified in the **clarification_fields** object" }, "AnotherAccountBankInfo": { "description": "Object that contains the account details of bank which is used for payment processing. Used when account number is not required.", "allOf": [ { "$ref": "#/components/schemas/AnotherAccountInfo" }, { "type": "object", "properties": { "type": { "type": "string", "maxLength": 255, "description": "Account type." }, "bank_id": { "oneOf": [ { "type": "string", "minLength": 1, "description": "Bank identifier received from the payment platform" }, { "type": "integer", "minimum": 1, "description": "Bank identifier" } ] }, "customer_name": { "type": "string", "description": "Bank account's owner full name" }, "security_code": { "type": "string", "minLength": 1, "maxLength": 255, "description": "First 2 digits of the password" }, "swift_code": { "type": "string", "minLength": 8, "maxLength": 11, "description": "SWIFT bank identification code" }, "routing_number": { "type": "string", "maxLength": 255, "description": "Bank account's routing number" }, "routing_type": { "type": "string", "maxLength": 255, "description": "Bank account's routing type" }, "iban": { "type": "string", "minLength": 5, "maxLength": 34, "description": "International bank account number" }, "bank_name": { "type": "string", "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`" }, "bank_branch_name": { "type": "string", "description": "Bank branch name" }, "bank_branch_code": { "type": "string", "description": "Bank branch code" }, "bank_branch_city": { "type": "string", "description": "City of bank branch location" }, "bank_branch_address": { "type": "string", "description": "Address of bank branch location" }, "bank_code": { "type": "string", "description": "International bank identifier (BIC or SWIFT) or, in certain countries, a specific code used by the national interbank clearing center. Example: `1234`" }, "fin": { "type": "string", "description": "Financial institution number" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country code in the ISO 3166-1 alpha-2 format" } } } ] }, "AnotherAccountInfo": { "type": "object", "properties": { "number": { "type": "string", "maxLength": 100, "minLength": 1, "description": "Customer's account number. Example: `21312`" }, "save": { "type": "boolean", "default": false, "description": "Indicator specifying whether the customer's account details should be saved" } }, "description": "Object that contains the minimum required details of the customer's payment instrument - account/wallet/voucher etc. Used when account number is not required." }, "ApplePaySessionPaymentInfo": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in the ISO 4217 alpha-3 format" }, "customer_amount": { "type": "integer", "minimum": 0, "maximum": 10000000000000, "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment for additional data analisys by using Dashboard" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "best_before": { "type": "string", "format": "date-time", "description": "Payment expiration date in the date-time format according to the ISO 8601 standart" }, "challenge_indicator": { "type": "string", "pattern": "^0[1-9]$", "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "challenge_window": { "type": "string", "pattern": "^0[1-5]$", "description": "The dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "reorder": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_purchase": { "type": "string", "pattern": "^0[1-2]$", "description": "Parameter specifying whether the current purchase is pre-ordered. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format" }, "gift_card": { "$ref": "#/components/schemas/GiftCardInfo" }, "device_channel": { "type": "string", "pattern": "^0[1-3]$", "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined" } }, "description": "Object that contains payment details" }, "AuthenticationData": { "required": [ "xid" ], "type": "object", "properties": { "cavv": { "type": "string", "maxLength": 255, "description": "Cardholder authentication verification value. Mandatory if `authentication_status`=`Y` or `A`" }, "ds_operation_id": { "type": "string", "maxLength": 36, "description": "Operation identifier assigned by the Directory Server" }, "eci": { "type": "string", "enum": [ "00", "01", "02", "05", "06", "07" ], "description": "The electronic commerce indicator" }, "threeds_version": { "type": "string", "enum": [ "3ds_1", "3ds_2", "non_3ds" ], "description": "Indicator of the 3‑D Secure authentication" }, "xid": { "type": "string", "maxLength": 255, "description": "The operation identifier (Base64-encoded, 20 bytes in a decoded form)" }, "enrollement_status": { "type": "string", "enum": [ "Y", "N", "U" ], "description": "The enrollment response from the VERes message from the directory server ('Y','N','U'). Supported for 3D Secure 1" }, "authentication_status": { "type": "string", "enum": [ "Y", "U", "A" ], "description": "Customer's authentication status. Possible values: `Y`—the cardholder was successfully authenticated by their card issuer, `A`—the cardholder authentication was attempted, `U`—the card issuer was unavailable during the authentication attempt" }, "authentication_flow": { "type": "string", "enum": [ "Frictionless", "Challenge" ], "description": "The indicator of the flow that was used for the customer 3-D Secure 2 authentication on the merchant side within the operation being processed" }, "threeds_full_version": { "type": "string", "description": "The full version of the 3-D Secure protocol", "example": "2.3.1", "maxLength": 8, "minLength": 5, "pattern": "^(\\d{1,2})\\.(\\d{1,2})\\.(\\d{1,2})(\\.(\\d{1,2}))?$" }, "authentication_status_reason_code": { "type": "string", "description": "Reason code for `authentication_status`", "maxLength": 2, "minLength": 2, "example": "01" } }, "description": "Object that contains 3DS Authentication Data from merchant" }, "AvsInfo": { "required": [ "avs_post_code", "avs_street_address" ], "type": "object", "properties": { "avs_post_code": { "type": "string", "description": "Postal code of the customer. Example: `WS13 6LG`", "minLength": 1 }, "avs_street_address": { "type": "string", "description": "Address of the customer. Example: `4 Breadmarket Street`", "minLength": 1 } }, "description": "Object that contains customer details for verification by the Address Verification Service. For more information, see [AVS Check](https://developers.ecommpay.com/en/en_Gate_avs.html)" }, "BankTransferCustomerInfo": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "properties": { "building": { "type": "string", "maxLength": 255, "description": "Customer building number" } } } ] }, "BookingInfo": { "type": "object", "description": "Object that contains general booking details", "properties": { "bookers": { "type": "array", "description": "List of customers included in the booking", "additionalProperties": false, "uniqueItems": true, "items": { "type": "object", "description": "Object that contains booker details", "additionalProperties": false, "properties": { "first_name": { "maxLength": 255, "type": "string", "description": "First name of the customer provided at the time of booking. Example: `William`" }, "last_name": { "maxLength": 255, "type": "string", "description": "Last name of the customer provided at the time of booking. Example: `Herschel`" }, "email": { "maxLength": 255, "type": "string", "format": "email", "description": " Email provided at the time of booking. Example: `rsfellow@mail.com`" } } } }, "items": { "type": "array", "description": "List of services included in the booking", "additionalProperties": false, "uniqueItems": true, "items": { "type": "object", "description": "Object that contains the details of each service included in the booking", "additionalProperties": false, "properties": { "description": { "type": "string", "maxLength": 255, "description": "Description of the service included in the booking. Example: `VIP Arrival`" }, "start_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Starting date of the service included in the booking, in the DD-MM-YYYY format. Example: `12-08-2026`" }, "end_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Ending date of the service included in the booking, in the DD-MM-YYYY format. Example: `12-08-2026`" } } } }, "start_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Starting date of the booked service, in the DD-MM-YYYY format. Example: `12-08-2026`" }, "end_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Ending date of the booked service, in the DD-MM-YYYY format. Example: `13-08-2026`" }, "description": { "type": "string", "maxLength": 255, "description": "Free-form description of the booked service. Example: `Siders music festival full pass`" }, "total": { "type": "integer", "description": "The total cost of the booking in minor units of currency. Value cannot be`0`. Example: `200000`" }, "pax": { "type": "integer", "description": "Number of people per booking. Value cannot be `0`. Example: `4`" }, "reference": { "type": "string", "maxLength": 255, "description": " Booking reference, which can be the URL, the name of the booked service, or its code in the merchant's web service. Example: `musicfestlink`" }, "id": { "type": "string", "maxLength": 255, "description": "Identifier of the booking, unique in the merchant's web service. Example: `83`" } } }, "CallbackInfo": { "type": "object", "properties": { "delay": { "type": "integer", "description": "Delay time for sending callbacks, in seconds. Example: `42`", "minimum": 0, "maximum": 600 }, "force_disable": { "type": "boolean", "description": "Indicator for disabling callbacks. Possible values: `true`—for disabling callbacks with information about the given payment, and `false`—for enabling these callbacks" } }, "description": "Object that contains additional callback sending conditions" }, "CancelPaymentInfo": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Refund amount in minor currency units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code in ISO-4217 alpha-3 format" }, "description": { "type": "string", "maxLength": 255, "description": "Refund description or comment" } }, "description": "Object that contains information about refund" }, "CardInfo": { "required": [ "month", "pan", "year" ], "type": "object", "properties": { "pan": { "type": "string", "format": "pan", "maxLength": 32, "description": "For cards - the number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. For network tokens - the token without masked characters, spaces, or other separator. Example:`4314220000000056`" }, "year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "For cards - the year of the card's expiration date. For network tokens - the year of the token's expiration date (according to the Gregorian calendar)" }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "For cards - the month of the card's expiration date. For network tokens - the month of the token's expiration date" }, "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession" }, "security_code": { "type": "string", "pattern": "^[0-9]{2}$", "description": "First 2 digits of the password." }, "save": { "type": "boolean", "description": "Indicator specifying whether the customer's account details should be saved" }, "stored_card_type": { "$ref": "#/components/schemas/StoredCardType" } }, "description": "Object that contains the information about customer's card that is used for payment. Contains parameters to specify card details or the information about the network token associated with the card" }, "CardInfoForSaleAuth": { "required": [ "month", "pan", "year" ], "type": "object", "properties": { "pan": { "type": "string", "format": "pan", "maxLength": 32, "description": "For cards - the number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. For network tokens - the token without masked characters, spaces, or other separator. Example:`4314220000000056`" }, "year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "For cards - the year of the card's expiration date. For network tokens - the year of the token's expiration date (according to the Gregorian calendar)" }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "For cards - the month of the card's expiration date. For network tokens - the month of the token's expiration date" }, "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession" }, "security_code": { "type": "string", "pattern": "^[0-9]{2}$", "description": "First 2 digits of the password" }, "save": { "type": "boolean", "description": "Indicator specifying whether the customer's account details should be saved" }, "stored_card_type": { "$ref": "#/components/schemas/StoredCardType" } }, "description": "Object that contains the information about customer's card that is used for payment. Contains parameters to specify card details or the information about the network token associated with the card" }, "CardInfoForTokenize": { "required": [ "month", "pan", "year" ], "type": "object", "properties": { "pan": { "type": "string", "format": "pan", "maxLength": 32, "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`" }, "year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "Year of the card's expiration date, intended to indicate the last valid year for card usage" }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month of the card's expiration date, intended to indicate the last valid month for card usage" }, "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" } }, "description": "Object that contains the customer's card details that is used for tokenize" }, "CardInfoLight": { "required": [ "pan" ], "type": "object", "properties": { "pan": { "type": "string", "format": "pan", "maxLength": 32, "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`" }, "year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "Year of the card's expiration date, intended to indicate the last valid year for card usage" }, "month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month of the card's expiration date, intended to indicate the last valid month for card usage" }, "issue_year": { "type": "integer", "maximum": 9999, "description": "Year of issuing date of the card" }, "issue_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month of issuing date of the card" }, "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" }, "cvv": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Card Verification Value/Code (CVV/CVC), intended to verify that the customer has the card in their possession" }, "save": { "type": "boolean", "description": "Indicator specifying whether the customer's account details should be saved" }, "stored_card_type": { "$ref": "#/components/schemas/StoredCardType" } }, "description": "Object that contains the customer's card details that is used for payment" }, "CupReturnUrl": { "allOf": [ { "$ref": "#/components/schemas/ReturnUrl" }, { "type": "object", "required": [ "success" ] } ] }, "CustomerGeneralInfo": { "required": [ "id", "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Customer identifier unique within the project" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains general customer details in merchant project" }, "CustomerInfo": { "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoBase" }, { "type": "object", "required": [ "ip_address" ] } ] }, "CustomerInfoBase": { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255, "description": "Customer identifier unique within the project" }, "identification_level": { "type": "string", "maxLength": 255, "description": "Indicator specifying whether the customer is trusted; provided by the merchant. Example: `1`—the customer is trusted" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "city": { "type": "string", "maxLength": 256, "description": "Name of customer's address city" }, "state": { "type": "string", "maxLength": 256, "description": "Name of the region (state, province, or other administrative subdivision type) of the customer's address. Example: `Greater London`" }, "phone": { "type": "string", "pattern": "^[0-9]{4,24}$", "description": "Customer's phone number, can be 4 to 24 digits long" }, "iin": { "type": "string", "maxLength": 255, "description": "Customer's individual identification number. Issued by the government or other official authority. Can be used for identity verification, regulatory compliance, and fraud prevention checks" }, "home_phone": { "type": "string", "pattern": "^[0-9]{4,24}$", "description": "Customer's home phone number, can be 4 to 24 digits long" }, "work_phone": { "type": "string", "pattern": "^[0-9]{4,24}$", "description": "Customer's work phone number, can be 4 to 24 digits long" }, "save": { "type": "boolean", "description": "Indicator specifying whether the customer's account details should be saved" }, "account_save": { "type": "boolean", "description": "Indicator specifying whether the customer's account details should be saved" }, "day_of_birth": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" }, "person_type": { "type": "string", "maxLength": 255, "description": "Type of the customer as a legal person, for example, a company or an individual, used for compliance" }, "birthplace": { "type": "string", "maxLength": 255, "description": "Name of the customer's birthplace (e.g., town, city, or other settlement type). Example: `London`" }, "first_name": { "type": "string", "maxLength": 255, "description": "First name of the customer. Example: `Jane`" }, "middle_name": { "type": "string", "maxLength": 255, "description": "Middle, second, or patronymic name of the customer. Example: `Mary`" }, "last_name": { "type": "string", "maxLength": 255, "description": "Last name of the customer. Example: `Smith`" }, "email": { "type": "string", "maxLength": 255, "format": "email", "description": "Email address of the customer. The string consists of a local-part and a domain name, separated by the `@` symbol. Example: `helen@example.com`." }, "browser": { "type": "string", "maxLength": 512, "description": "Name and version of the customer's browser used to access the web service. Can be used to identify the customer environment for risk and fraud analysis" }, "ip_address": { "type": "string", "maxLength": 255, "format": "ip-address", "description": "IP address of the customer's device. Can be used for security checks, geolocation, and fraud prevention" }, "device_type": { "type": "string", "description": "Browser engine that can be used for rendering web pages. Example: `WebKit`" }, "device_id": { "type": "string", "description": "Identifier of the customer's device" }, "datetime": { "type": "string", "format": "dateTime", "description": "Date and time when the payment form was opened by the customer in the YYYY-MM-DD hh-mm-ss format. Useful for tracking customer activity and timing of payment initiation. Example: `2022-01-01 15:15:15`" }, "screen_res": { "type": "string", "description": "Screen resolution of the customer's device, in pixels, with an `x` character as a delimiter. Example: `360x640`" }, "session_id": { "type": "string", "description": "Identifier of the session cookie used by the customer" }, "language": { "type": "string", "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`" }, "zip": { "type": "string", "maxLength": 10, "description": "Postal or zip code in the customer's address. Example: `75001`" }, "address": { "type": "string", "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the customer. Example: `Via Dietro Duomo 36`" }, "district": { "type": "string", "maxLength": 255, "description": "District of the customer's address" }, "street": { "type": "string", "maxLength": 255, "description": "Name of the street in the customer's address. Example: `Breadmarket Street`" }, "building": { "type": "string", "maxLength": 255, "description": "Building number in the customer’s address. Example: `4`" }, "account_id": { "type": "string", "description": "Identifier of the customer's account in the external payment system" }, "gender": { "type": "string", "enum": [ "male", "female" ], "description": "Identifier of the customer's gender. Possible values: male or female" }, "qq_account_number": { "type": "string", "description": "Customer login in QQ social network" }, "ssn": { "type": "integer", "maxLength": 4, "description": "The last 4 digits of the customer's US social security number" }, "device_fingerprint": { "type": "string", "description": "Identifier generated based on a device's characteristics such as browser type, screen resolution, operating system, fonts, and others" }, "identify": { "type": "object", "description": "Object that contains customer identification document details", "properties": { "doc_number": { "type": "string", "maxLength": 255, "description": "Identifier of the document serving as a proof of identity for the customer. Example: `65432334567`" }, "doc_type": { "type": "string", "maxLength": 255, "description": "Type of identification document" }, "doc_issue_date": { "type": "string", "maxLength": 255, "description": "Date when the identification document was issued. Used for identity verification. Example: `20.12.2012`" }, "doc_issue_by": { "type": "string", "maxLength": 255, "description": "Name of the authority that issued the identification document. Can be used for identity verification. Example: `12346`" }, "doc_issue_country": { "type": "string", "maxLength": 255, "description": "Name of the country where the identification document was issued. Can be used for identity verification" } } }, "billing": { "type": "object", "description": "Object contains customer billing address details", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "region": { "type": "string", "description": "Region or state of the customer's billing address" }, "region_code": { "type": "string", "pattern": "^[0-9A-Z]{1,3}$", "description": "The region or state code of the customer's billing address in ISO 3166-2 format" }, "city": { "type": "string", "maxLength": 256, "description": "Name of the place of residence (e.g., town, city, or other settlement type) in the customer's billing address. Example: `London`" }, "address": { "type": "string", "maxLength": 512, "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the customer's billing address. Example: `Via Dietro Duomo 36`" }, "postal": { "type": "string", "maxLength": 16, "description": "Postal code in the customer's billing address.Example: `BR1 1AA`" }, "canadian_province": { "type": "string", "enum": [ "ON", "BC", "AB", "MB", "SK", "QC", "NS", "NB", "NF", "PE", "NT", "NU", "YT" ], "description": "Abbreviation of Canadian province" } } }, "citizenship": { "type": "string", "minLength": 1, "description": "Сode of the sender's country of citizenship in ISO 3166-1 alpha-2" }, "accept_header": { "type": "string", "minLength": 1, "description": "Value of the HTTP Accept request header as received from the customer's browser" }, "color_depth": { "type": "integer", "description": "Colour depth of the screen as supported by the customer's browser, bits per pixel" }, "java_enabled": { "type": "boolean", "description": "Indicator specifying whether the customer's browser supports Java" }, "js_enabled": { "type": "boolean", "description": "Indicator specifying whether the customer's browser supports JavaScript" }, "timezone_offset": { "type": "string", "minLength": 1, "description": "Difference between the time in UTC (Coordinated Universal Time) and the local time of the browser, specified in minutes. Example: `-110`" }, "timezone_name": { "type": "string", "description": "Name of the time zone the customer's browser is set to. Example: `Europe/London`" }, "address_match": { "type": "boolean", "description": "Indicator specifying whether the customer's billing address matches the address specified in the shipping object. Possible values: `true`—addresses match, `false`—addresses do not match" }, "account": { "$ref": "#/components/schemas/AccountInfoAtMerchant" }, "shipping": { "$ref": "#/components/schemas/ShippingInfo" }, "mpi_result": { "$ref": "#/components/schemas/MpiResult" }, "accept_language_header": { "type": "string", "minLength": 1, "description": "Indicates the preferred language(s) of the customer's browser, derived from the Accept-Language HTTP header, for example `en-GB,en;q=0.8,fr;q=0.3`" } }, "description": "Object that contains customer details without ip_address. Use CustomerInfo instead of this" }, "CustomerInfoBnplSale": { "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoBase" }, { "type": "object", "properties": {}, "required": [ "id", "ip_address" ] } ] }, "CustomerInfoCard": { "type": "object", "description": "Object that contains customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "properties": { "card_product_type": { "description": "Card product type: business or individual", "type": "string", "enum": [ "Business Card", "Individual Card" ] } }, "required": [ "id" ] } ] }, "CustomerInfoInvoice": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "string", "maxLength": 255, "description": "Customer identifier unique within the project" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "city": { "type": "string", "maxLength": 256, "description": "Customer's address city name" }, "state": { "type": "string", "maxLength": 256, "description": "State" }, "phone": { "type": "string", "pattern": "^[0-9]{4,24}$", "description": "Customer's phone number, can be 4 to 24 digits long" }, "day_of_birth": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Customer's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" }, "birthplace": { "type": "string", "maxLength": 255, "description": "Customer's place of birth" }, "first_name": { "type": "string", "maxLength": 255, "description": "Customer first name" }, "middle_name": { "type": "string", "maxLength": 255, "description": "Customer's patronymic" }, "last_name": { "type": "string", "maxLength": 255, "description": "Customer last name" }, "email": { "type": "string", "maxLength": 255, "format": "email", "description": "Customer email" }, "language": { "type": "string", "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`" }, "address": { "type": "string", "description": "Customer’saddress" }, "ssn": { "type": "integer", "maxLength": 4, "description": "The last 4 digits of the social security number of US." }, "billing": { "type": "object", "description": "Object contains billing address fields", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "region": { "type": "string", "description": "The region or state of the customer's billing address" }, "city": { "type": "string", "maxLength": 256, "description": "City of the billing customer address" }, "address": { "type": "string", "maxLength": 512, "description": "Street account address of the customer" }, "postal": { "type": "string", "maxLength": 16, "description": "Postal code of the billing address of the customer" } } }, "accept_language_header": { "type": "string", "minLength": 1, "description": "Indicates the preferred language(s) of the customer's browser, derived from the Accept-Language HTTP header, for example `en-GB,en;q=0.8,fr;q=0.3`" }, "account_id": { "type": "string", "description": "Customer identifier in external payment system that is used for payment performing" } }, "description": "Object that contains information about the customer" }, "CustomerInfoNameValidation": { "description": "Object that contains customer details for name validation", "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "properties": { "name_validation": { "type": "boolean", "description": "Parameter that indicates name validation is required for the request" } } } ] }, "CustomerInfoPayout": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Customer identifier unique within the project" } }, "required": [ "id" ] } ] }, "CustomerInfoWalletRecurring": { "description": "Object that contains customer details for recurring payments performing by using e-wallets", "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "id" ] } ] }, "CustomerInfoWithId": { "description": "Object that contains customer details with mandatory identifier", "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "id" ] } ] }, "CryptoPayment": { "type": "object", "properties": { "cryptocurrency_type": { "type": "string", "enum": [ "cbdc", "stablecoins_fiat_backed", "native_tokens", "other" ], "description": "Indicator that specifies the type of the cryptocurrency, required for Mastercard and Visa payments involving cryptocurrencies" } } }, "Descriptor": { "type": "object", "properties": { "descriptor": { "type": "string", "maxLength": 255, "description": "also known as billing descriptor, which is the text identifying the merchant and providing additional information about the payment (for example, the customer identifier, phone number, location information, etc.). In case of card payments, the merchant descriptor is sent to the issuing bank and can be shown on the customer’s bank statement. It can also be utilised otherwise as per specifics of various payment methods." } } }, "ErrorItem": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code intended to represent the result of the operation processing. Example: `3287`" }, "message": { "type": "string", "description": "Message intended to provide additional details clarifying the cause of the error. Example: `The payment currency is required`" }, "field": { "type": "string", "description": "Name of the parameter that was erroneously specified (if such parameter is identified)" }, "constraint": { "type": "string", "description": "Information about the error. This information can be used to clarify the failure. Example: `required`" } }, "description": "Object that contains single error information" }, "ErrorItems": { "type": "object", "properties": { "errors": { "type": "array", "description": "Array that contains information of one or more error messages", "items": { "$ref": "#/components/schemas/ErrorItem" } } }, "description": "Object that contains information of one or more error messages" }, "ErrorResponse": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "Status of receiving of the request" }, "code": { "type": "string", "description": "Error code" }, "message": { "type": "string", "description": "Message that clarifies the cause of the error" } }, "description": "Object that contains information about request registration or processing error. Detailed information about the error see in the message parameter of the response" }, "ETokenInfoLight": { "required": [ "token" ], "type": "object", "properties": { "token": { "type": "string", "description": "Token from payment system" } }, "description": "Information about token from payments system" }, "GateSuccessResponse": { "required": [ "payment_id", "project_id", "request_id", "status" ], "type": "object", "properties": { "status": { "type": "string", "maxLength": 255, "description": "Status indicating the result of the request acceptance" }, "request_id": { "type": "string", "maxLength": 100, "description": "Identifier of the request specified by the payment platform" }, "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`" }, "payment_id": { "type": "string", "maxLength": 255, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" } }, "description": "Object that contains information about request acceptance or execution in the payment platform" }, "GeneralInfo": { "type": "object", "description": "Object that contains general request details", "required": [ "project_id", "payment_id", "signature" ], "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" }, "merchant_callback_url": { "type": "string", "minLength": 1, "maxLength": 255, "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`" } } }, "GeneralInfoInvoice": { "required": [ "payment_id", "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "merchant_callback_url": { "type": "string", "minLength": 1, "maxLength": 255, "description": "URL for handling request callbacks. This parameter should be passed when callbacks for a request need to be sent to an address that is different from that specified by default (for information about callbacks and how to use them, see [Handling callbacks](https://developers.ecommpay.com/en/en_platform_callbacks.html)). Example: `https://cosmoshop.earth/specialorder`" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains parameters for generating and submitting a payment link purchase to the payment platform" }, "GeneralInfoClarification": { "type": "object", "description": "Object that contains general request details", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "required": [ "project_id", "payment_id", "signature" ] }, "GeneralInfo3DS": { "type": "object", "description": "Object that contains general request details", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "required": [ "project_id", "payment_id", "signature" ] }, "GiftCardInfo": { "type": "object", "properties": { "amount": { "type": "integer", "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "maxLength": 3, "description": "Currency code in ISO 4217 alpha-3 format" }, "count": { "type": "integer", "maximum": 99, "description": "Number of gift cards" } }, "description": "Object that contains information about gift card" }, "GooglePayETokenInfoLight": { "required": [ "token" ], "type": "object", "properties": { "token": { "type": "string", "description": "Token from the Google Pay service" }, "google_gateway_type": { "type": "string", "description": "GooglePay gateway type. Possible values: `gateway`—the payment data is processed by Ecommpay's acquiring system, `merchant`—the payment data is processed through a third-party payment system" }, "google_tokenization_type": { "type": "string", "description": "GooglePay tokenisation type. Possible values: `DIRECT`—decryption of the Google Pay response on third-party servers, `PAYMENT_GATEWAY`—decryption of the Google Pay response on the Ecommpay side as the payment gateway" }, "google_gateway_id": { "type": "string", "description": "Identifier of the gateway. This parameter is assigned by Google Pay" }, "google_merchant_id": { "type": "string", "description": "Identifier of the merchant. This parameter is assigned by Google Pay" }, "google_gateway": { "type": "string", "description": "Payment gateway in Google Pay, for example `ecommpay` for Ecommpay" }, "google_transaction_id": { "type": "string", "description": "Identifier of the Google Pay payment" } }, "description": "Information about token from payments system" }, "Installment": { "type": "object", "properties": { "ext_plan_id": { "type": "string", "description": "Installment plan ID assigned by VIS" }, "count": { "type": "integer", "description": "Number of installment periods" }, "frequency": { "type": "string", "enum": [ "A", "B", "C", "M", "Q", "S", "T", "W", "2" ], "description": "Payment frequency" }, "terms_and_conditions": { "type": "object", "description": "Terms and conditions of the contract", "properties": { "language": { "type": "string", "description": "Customer’s language and country settings. May be used to personalise customer interface, notifications, and messages. The value is provided according to ISO 639-1 (language) and ISO 3166-1 alpha-2 (country) standards. Example: `en_US`" }, "version": { "type": "number", "description": "Version" } } } } }, "MerchantAuthGeneralInfo": { "required": [ "payment_id", "project_id", "signature", "type" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "type": { "type": "string", "enum": [ "start", "finish" ], "description": "Type of merchant auth request" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "description": "Object that contains required details of the merchant auth request (customer authentication by the payment system on merchant's request)" }, "MerchantInfo": { "type": "object", "properties": { "descriptor": { "type": "string", "pattern": "^[^!@&~№{}|<>\\[\\]Ёё]*$", "maxLength": 255, "description": "also known as billing descriptor, which is the text identifying the merchant and providing additional information about the payment (for example, the customer identifier, phone number, location information, etc.). In case of card payments, the merchant descriptor is sent to the issuing bank and is shown on the customer’s bank statement. It can also be utilised otherwise as per specifics of various payment methods." }, "data": { "type": "string", "minLength": 1, "description": "Information about the payment provided by the merchant. Can include details about the purchased items or services (number, description, SKU, etc.) or any other relevant data. This information is not sent to the payment provider or other third parties and is used at the merchant’s discretion" } }, "description": "Object that contains additional information provided by the merchant" }, "MotoInfo": { "type": "object", "description": "Object that contains payment details including MO/TO type", "properties": { "moto_type": { "type": "integer", "default": 0, "enum": [ 0, 1, 2 ], "description": "Type of a Mail Order/telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment" } } }, "MpiResult": { "type": "object", "properties": { "acs_operation_id": { "type": "string", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$", "description": "Operation identifier in ACS" }, "authentication_flow": { "type": "string", "pattern": "^0[1-2]$", "description": "The indicator of the flow that was used for the customer 3-D Secure 2 authentication within the previous operation" }, "authentication_timestamp": { "type": "string", "pattern": "^\\d{12}$", "description": "Date and time of the previous successful customer authentication as returned in the `mpi_timestamp` parameter of the callback with payment processing result. Format: A numeric string containing exactly 12 digits with no spaces, letters, or special characters" } }, "description": "An object that contains information about previous mpi result" }, "OperationInfo": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the operation in the payment platform" }, "type": { "type": "string", "description": "Operation type" }, "status": { "type": "string", "description": "Operation status" }, "date": { "type": "string", "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format" }, "created_date": { "type": "string", "description": "Date and time when the operation was created in the payment platform in the format according to the ISO 8601 standart" }, "sum_initial": { "$ref": "#/components/schemas/Sum" }, "sum_converted": { "$ref": "#/components/schemas/Sum" }, "request_id": { "type": "string", "description": "Identifier of the request specified by the payment platform" }, "provider": { "$ref": "#/components/schemas/ProviderResultInfo" }, "code": { "type": "string", "description": "Operation processing result code" }, "message": { "type": "string", "description": "Operation processing result message" }, "eci": { "type": "string", "description": "Electronic Commerce Indicator, used for communicating whether the authentication was initiated and what was its outcome as well as whether the issuer or the merchant is responsible for approving payment processing and will take potential financial responsibility if a chargeback occurs. For more information, see [Electronic Commerce Indicators](https://developers.ecommpay.com/en/en_ECI_codes.html)" }, "operation_fee": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Operation fee amount in minor currency units. Example: `31`" }, "currency": { "type": "string", "pattern": "^[:_A-Z0-9]{3,27}$", "description": "Currency code in the ISO-4217 alpha-3 format. Example: `USD`" } } } }, "description": "Object that contains operation details" }, "PaymentBanksInfo": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in the ISO 4217 alpha-3 format" }, "customer_amount": { "type": "integer", "minimum": 0, "maximum": 10000000000000, "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment for additional data analisys by using Dashboard" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "best_before": { "type": "string", "format": "date-time", "description": "Payment expiration date in the date-time format according to the ISO 8601 standart" }, "challenge_indicator": { "type": "string", "pattern": "^0[1-9]$", "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "challenge_window": { "type": "string", "pattern": "^0[1-5]$", "description": "The dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "reorder": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_purchase": { "type": "string", "pattern": "^0[1-2]$", "description": "Parameter specifying whether the current purchase is pre-ordered. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format" }, "gift_card": { "$ref": "#/components/schemas/GiftCardInfo" }, "local_conversion_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Conversion currency code, provided in ISO 4217 alpha-3 format" }, "details": { "type": "object", "description": "Object that contains customer identification document details", "properties": { "document_number": { "type": "string", "description": "Number of the identification document used for verification" }, "document_date": { "type": "string", "description": " Date when the relevant contract or document was concluded" } } }, "device_channel": { "type": "string", "pattern": "^0[1-3]$", "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined" } }, "description": "Object that contains payment details" }, "PaymentInfo": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in ISO-4217 alpha-3 format. Example: `USD`" }, "customer_amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency" }, "description": { "type": "string", "maxLength": 255, "description": "Description of the payment intended to provide additional context or comments" }, "end_to_end_id": { "type": "string", "maxLength": 35, "description": "Identifier provided by the SEPA payment initiator. This parameter is intended to be routed through the entire SEPA payment process" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "best_before": { "type": "string", "format": "date-time", "description": "Payment link expiry date and time, in the ISO 8601 format" }, "challenge_indicator": { "type": "string", "pattern": "^0[1-9]$", "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "challenge_window": { "type": "string", "pattern": "^0[1-5]$", "description": "Dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "reorder": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeated purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_purchase": { "type": "string", "pattern": "^0[1-2]$", "description": "Parameter specifying whether the current purchase is pre-ordered. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format" }, "gift_card": { "$ref": "#/components/schemas/GiftCardInfo" }, "local_conversion_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment conversion currency code, provided in ISO 4217 alpha-3 format" }, "details": { "type": "object", "description": "Object intended to contain the customer's identification document details", "properties": { "document_number": { "type": "string", "description": "Number of the identification document used for verification" }, "document_date": { "type": "string", "description": "Date when the relevant contract or document was concluded" } } }, "device_channel": { "type": "string", "pattern": "^0[1-3]$", "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined" }, "is_fast": { "type": "boolean", "description": "Indicator specifying whether the payment is processed using a fast payment method" } }, "description": "Object that contains payment details" }, "PaymentInfoDirectDebit": { "required": [ "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[:_A-Z0-9]{3,27}$", "description": "Payment currency in the ISO 4217 alpha-3 format" }, "customer_amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount converted into the currency selected by the customer. This parameter is specified in minor units of currency" }, "description": { "type": "string", "maxLength": 255, "description": "Textual comment or description of the payment, can be used for additional data analysis and reporting in Dashboard" }, "end_to_end_id": { "type": "string", "maxLength": 35, "description": "SEPA identifier (provided by initiating SEPA transaction end-customer), routed through the whole payment process." }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "best_before": { "type": "string", "format": "date-time", "description": "Payment expiration date in the date-time format according to the ISO 8601 standart" }, "challenge_indicator": { "type": "string", "pattern": "^0[1-9]$", "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "challenge_window": { "type": "string", "pattern": "^0[1-5]$", "description": "The dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "reorder": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeat purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_purchase": { "type": "string", "pattern": "^0[1-2]$", "description": "Parameter specifying whether the current purchase is pre-ordered. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format" }, "gift_card": { "$ref": "#/components/schemas/GiftCardInfo" }, "local_conversion_currency": { "type": "string", "pattern": "^[:_A-Z0-9]{3,27}$", "description": "Payment conversion currency code, provided in ISO 4217 alpha-3 format" }, "details": { "type": "object", "description": "Object intended to contain customer identification document details", "properties": { "document_number": { "type": "string", "description": "Number of the identification document that can be used for verification" }, "document_date": { "type": "string", "description": "Date when the relevant contract or document was concluded" } } }, "device_channel": { "type": "string", "pattern": "^0[1-3]$", "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined" }, "is_fast": { "type": "boolean", "description": "Indicator intended to show whether the payment is processed using a fast payment method" } } }, "PaymentInfoForCard": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfoWMoTo" }, { "$ref": "#/components/schemas/CryptoPayment" }, { "type": "object", "description": "Object that contains payment details for card", "properties": { "debt_account": { "type": "string", "maxLength": 10, "description": "The number of the account designated to receive funds as part of the debt settlement purchases. Example: `an9876170i`" }, "allow_partial_approval": { "type": "boolean", "description": "Parameter that indicates whether the merchant accepts partial approval for this purchase" } } } ] }, "PaymentInfoInvoice": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfoInvoiceByToken" }, { "type": "object", "properties": { "force_method": { "type": "string", "maxLength": 255, "description": "Identifier of the payment method intended to be opened by default, without the option for the customer to select a different payment method. For complete list of payment methods codes, see [Payment method codes](https://developers.ecommpay.com/en/en_pm_codes.html)" } } } ] }, "PaymentInfoInvoiceByToken": { "required": [ "amount", "best_before", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in ISO 4217 alpha-3 format" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "best_before": { "type": "string", "format": "date-time", "description": "Date and time of payment expiration. Keep in mind that the validity period of the payment link cannot exceed 30 days" }, "moto_type": { "type": "integer", "default": 0, "enum": [ 0, 1, 2 ], "description": "Type of a Mail Order/Telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment" } }, "description": "Object which contains payment information for invoice by token" }, "PaymentInfoPayoutOnlineBanking": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in ISO 4217 alpha-3 format" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" } }, "description": "Object which contains payment information" }, "PaymentInfoRecurring": { "required": [ "amount", "currency" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Payment amount in minor units of currency" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in the ISO 4217 alpha-3 format. Example: `USD`" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment for additional data analisys by using Dashboard" }, "extra_param": { "type": "string", "maxLength": 255, "description": "Parameter for passing additional settings for customise the payment processing flow" }, "challenge_indicator": { "type": "string", "pattern": "^0[1-9]$", "description": "Indicates whether the challenge flow is preferred. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "challenge_window": { "type": "string", "pattern": "^0[1-5]$", "description": "The dimensions of a window in which the authentication page opens. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "reorder": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicates whether the customer is buying the merchandise or the service for the first time or it is a repeated purchase. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_purchase": { "type": "string", "pattern": "^0[1-2]$", "description": "Parameter specifying whether the current purchase is pre-ordered. For more information, see [3‑D Secure authentication](https://developers.ecommpay.com/en/en_gate_payment_3ds.html). Example: `01`" }, "preorder_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the preordered merchandise or service will be available in the DD-MM-YYYY format" }, "gift_card": { "$ref": "#/components/schemas/GiftCardInfo" }, "local_conversion_currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Payment currency code in the ISO 4217 alpha-3 format" }, "details": { "type": "object", "description": "Object that contains customer identification document details", "properties": { "document_number": { "type": "string", "description": "Number of the identification document used for verification" }, "document_date": { "type": "string", "description": "Date when the relevant contract or document was concluded" } } }, "device_channel": { "type": "string", "pattern": "^0[1-3]$", "description": "Indicator that specifies the type of the interface through which the web service initiates the 3-D Secure authentication. By default, it is set to `02` (Browser-based). In specific cases that must be agreed upon and approved, the value of this parameter can be `01` (App-based) and `03` (3DS Requestor Initiated). If `01` or `03` value is passed when it was not initially agreed upon, the payment may get declined" } }, "description": "Object that contains payment details" }, "PaymentInfoWMoTo": { "allOf": [ { "$ref": "#/components/schemas/PaymentInfo" }, { "type": "object", "description": "Object that contains payment details including MO/TO type", "properties": { "moto_type": { "type": "integer", "default": 0, "enum": [ 0, 1, 2 ], "description": "Type of a Mail Order/telephone Order purchase determined by the way the cardholder provides the card details (phone, mail, fax, or email). Possible values: `0`—not a MO/TO payment, `1`—Mail Order payment, `2`—Telephone Order payment" } } } ] }, "PaymentResultInfo": { "type": "object", "properties": { "id": { "type": "string", "description": "payment id" }, "payment_system_id": { "type": "integer", "description": "Identifier of the payment provider in the payment platform" }, "method": { "type": "string" }, "endpoint_id": { "type": "integer" }, "result_code": { "type": "string" }, "result_message": { "type": "string" }, "date": { "type": "string", "description": "Date of the payment processing" } }, "description": "information about external payment system used" }, "PaymentStatusResponse": { "required": [ "operations", "payment", "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`" }, "payment": { "type": "object", "description": "Object that contains payment details", "properties": { "id": { "type": "string", "description": "Unique identification of the payment in the payment platform" }, "type": { "type": "string", "description": "Payment type" }, "status": { "type": "string", "description": "Payment status", "minLength": 1 }, "sum": { "$ref": "#/components/schemas/Sum" }, "date": { "type": "string", "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format" }, "description": { "type": "string", "description": "Description of the payment passed in the initial request" }, "method": { "type": "string", "description": "Payment method that used to perform the payment" } }, "required": [ "status" ] }, "operations": { "type": "array", "description": "List of operations performed within the payment", "items": { "$ref": "#/components/schemas/OperationInfo" } }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "recurring": { "type": "object", "description": "Object that contains recurring registration details of the payment. Details is submitted if the initial request for payment is passed with `recurring_registration=1` and the payment is successfully processed", "properties": { "id": { "type": "integer", "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases" }, "currency": { "type": "string", "description": "Payment currency code in ISO 4217 alpha-3 format" }, "valid_thru": { "type": "string", "description": "Expiration date of the record about a series of funds debiting. Example: `2025-03-30 16:15:00`" } } }, "account": { "type": "object", "description": "Object that contains customer's payment instrument (card, bank account, wallet, etc.) details", "properties": { "number": { "type": "string", "description": "Customer's account number. Example: `21312`", "minLength": 1 }, "type": { "type": "string", "description": "Payment instrument type" }, "card_holder": { "type": "string", "description": "Name of the cardholder as specified on the payment card" }, "token": { "type": "string", "description": "Customer's card token identifier" }, "token_created_at": { "type": "string", "description": "Date and time of the token generation, specified in the ISO 8601 format with the UTC offset. Example: `2024-07-21T03:31:24+0000" } }, "required": [ "number" ] }, "acs": { "type": "object", "description": "Object that contains 3-D Secure data in case the card requires 3-D Secure authentication", "properties": { "pa_req": { "type": "string", "description": "Payer Authentication Request message received during the 3‑D Secure authentication", "minLength": 1 }, "md": { "type": "string", "description": "Merchant data received from a global card network during the 3‑D Secure authentication", "minLength": 1 }, "acs_url": { "type": "string", "description": "URL of the page to which the customer is redirected for the 3‑D Secure authentication (Access Control Server page)", "minLength": 1 } }, "required": [ "pa_req", "md", "acs_url" ] }, "errors": { "type": "array", "description": "Array of error messages", "items": { "$ref": "#/components/schemas/ErrorItem" } }, "signature": { "type": "string", "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)." } }, "description": "Object that contains the payment details passed to the request for payment status clarifying" }, "ProviderResultInfo": { "type": "object", "properties": { "id": { "type": "integer", "description": "Payment provider identifier in the payment platform. Example: `123`" }, "payment_id": { "type": "string", "description": "Identifier of the payment that uniquely identifies a payment within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return. Example: `payment_443`" }, "auth_code": { "type": "string", "description": "Authorisation code received from a provider or a payment system. Example: `591748`" }, "endpoint_id": { "type": "integer", "description": "Identifier of the payment gateway provided by the payment provider or system in CRC32 format. Example: `2`" }, "result_code": { "type": "string", "description": "Result code provided by the payment provider or the payment system intended to indicate the result of the operation. Example: `00`" }, "result_message": { "type": "string", "description": "Message with the result of operation. The parameter is provided by the payment provider or the payment system and offers additional details regarding the operation status and any related information. Example: `Success`" }, "date": { "type": "string", "description": "Date and time when processing of the payment was completed on a provider or a payment system side. Example: `2022-02-22T19:52:14+0000`" } }, "description": "Object containing information from the payment provider regarding the result of the operation" }, "ReceiptData": { "type": "object", "properties": { "positions": { "type": "array", "items": { "$ref": "#/components/schemas/ReceiptPositionData" }, "minItems": 1, "maxItems": 300 }, "total_tax_amount": { "type": "integer", "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800``" }, "common_tax": { "type": "number", "multipleOf": 0.01, "description": "Applicable tax rate, specified if it is the same for all line items in the order. Example: `18`" } }, "description": "Object that contains the list of line items to be sent to the customer in the receipt once the payment is processed" }, "ReceiptPositionData": { "required": [ "amount" ], "type": "object", "properties": { "quantity": { "type": "number", "multipleOf": 0.000001, "description": "Quantity of the goods and services. Example: `3`" }, "amount": { "type": "integer", "description": "Total cost for a particular line item. Calculated by multiplying the quantity of that item by its unit price. Specified in minor units of currency. Example: `10000`" }, "tax": { "type": "number", "multipleOf": 0.01, "description": "Tax percentage applicable to the product or service. Example: `18`" }, "tax_amount": { "type": "integer", "description": "Tax amount for a line item, specified in minor units of currency. Example: `1800`" }, "description": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Description of a specific product or service being purchased. Example: `Photo frame`" } }, "description": "Object that contains information about each line item in the purchase" }, "RecipientForCard": { "anyOf": [ { "required": [ "wallet_owner", "wallet_id" ], "type": "object", "description": "Object that contains the data of the payment recipient", "properties": { "wallet_owner": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "First and last name of the recipient who owns the digital wallet to which the funds will be credited. Example: `Fran Petrarca`" }, "wallet_id": { "type": "string", "maxLength": 64, "pattern": "^[^!@&~№{}|<>\\[\\]]*$", "description": "Identifier of the digital wallet. Specified as is, without masked characters, spaces, or other separators. Example:`WID20071304`" }, "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the recipient (as specified on the card)" }, "country": { "maxLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Recipient's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "address": { "maxLength": 99, "type": "string", "description": "Recipient address" }, "city": { "maxLength": 25, "type": "string", "description": "Name of recipient's address city" }, "state_code": { "maxLength": 3, "pattern": "^[A-Z]+$", "type": "string", "description": "State code of recipient" }, "day_of_birth": { "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "type": "string", "description": "Recipient's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" } } }, { "required": [ "card_holder", "pan" ], "type": "object", "description": "Object that contains the data of the transfer recipient", "properties": { "card_holder": { "type": "string", "maxLength": 255, "pattern": "^[a-zA-Z0-9\\s\\-.']+$", "description": "Name of the cardholder as specified on the payment card" }, "pan": { "type": "string", "pattern": "^[0-9]{15,19}$", "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`" }, "country": { "maxLength": 2, "pattern": "^[A-Z]{2}$", "type": "string", "description": "Recipient's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "address": { "maxLength": 99, "type": "string", "description": "Recipient address" }, "city": { "maxLength": 25, "type": "string", "description": "Namr of recipient's address city" }, "state_code": { "maxLength": 3, "pattern": "^[A-Z]+$", "type": "string", "description": "State code of recipient" }, "day_of_birth": { "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "type": "string", "description": "Recipient's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" } } } ] }, "RecurringIdInfo": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Unique identifier of the recurring payment in the payment platform" } }, "description": "Object that contains Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchasesentifier" }, "RecurringInfo": { "type": "object", "properties": { "type": { "type": "string", "pattern": "^[RCU]$", "description": "Payment type" }, "expiry_year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "Year of expiration for credential-on-file (COF) payment. Can be used to define the last year when COF payment are allowed. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month of expiration for credential-on-file (COF) payment. Can be used together with `expiry_year` to set the final period of recurring payment validity. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)" }, "expiry_day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "Day of expiration for credential-on-file (COF) payment. Can be used together with `expiry_month` and `expiry_year` to specify the exact expiration date. If this parameter is not passed in the request, the payment platform will use the default values (for detailed information, refer to the documentation portal)" }, "interval": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Interval of performing regular purchases. This parameter should be assigned a numeric value from `1` to `100` (for example, each three weeks) and is necessarily used in conjunction with the **period** parameter. May be used to configure payment recurrence frequency" }, "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount of payment in minor currency units" }, "period": { "type": "string", "pattern": "^[DWMQY]$", "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year" }, "time": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "description": "Time of performing subsequent debits (for a regular purchase) in the hh:mm:ss format. The parameter may be used if the **period** parameter is specified in the request" }, "register": { "type": "boolean", "description": "Indicator that defines whether the payment should be registered as credential-on-file. Is assigned to the true value to register credential-on-file payment" }, "scheduled_payment_id": { "type": "string", "maxLength": 255, "description": "Identifier assigned to the payment (as **payment_id**) within which scheduled debits are performed; it must differ from the identifier of the payment made to register a credential-on-file purchase and must be unique within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return Example: `A2323`" }, "start_date": { "type": "string", "maxLength": 19, "pattern": "^([0-3]\\d-){2}[1-2]\\d{3}$", "description": "First automatic payment date and time in DD-MM-YYYY format. Obligatory when `scheduled_payment_id` is set. Applicable only when **recurring.type = R** and **recurring.period** is set. Is used to authorize and perform the next recurring payment. **start_date** can't be less than the response date of the initial *sale/auth* request within which the recurring was registered" } }, "description": "Object that contains recurring payment details and conditions" }, "RecurringInfoSuccess": { "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`" }, "recurring": { "type": "object", "description": "Object that contains information about the credential-on-file (COF) purchase. For more information, see [Credential-on-file (COF) purchases](https://developers.ecommpay.com/en/en_Gate__payments_on_saved_data.html)", "properties": { "id": { "type": "integer", "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases" }, "type": { "type": "string", "description": "Indicator of the credential-on-file purchase type. Example: `R`" }, "period": { "type": "string", "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year" }, "period_interval": { "type": "string", "description": "Multiplicator to increase debiting period, for example to run debiting every third week, `period` should be set to `W` and `interval` should be set to `3`. Possible values: from `1` to `100`. Example: `3`" }, "start_date": { "type": "string", "description": "Date to perform the first debit in the yyyy-mm-dd format." }, "start_time": { "type": "string", "description": "Time of subsequent debiting in the HH:mm format" }, "amount": { "type": "string", "description": "Debit amount in minor units of currency" }, "currency": { "type": "string", "description": "Currency code in ISO-4217 alpha-3 format" }, "payment_method": { "type": "string", "description": "Code of the payment method that was used to make the payment to register a COF purchase (according to [the reference table](https://developers.ecommpay.com/en/en_pm_codes.html), with relevant codes listed in the Gate, Dashboard column)" }, "last_payment_at": { "type": "string", "description": "The date when the last debit was made. Example: `2025-03-30 16:15:00`" }, "valid_thru": { "type": "string", "description": "Expiration date of the record about a series of funds debiting" }, "status": { "type": "string", "description": "Indicator of the current state of the debiting series record created after a successful COF purchase registration. Example: `active`" }, "description": { "type": "string", "description": "Description of the credential-on-file purchase", "maxLength": 255 }, "schedule_date": { "type": "object", "properties": { "next": { "type": "string", "description": "Next scheduled payment date in the YYYY-MM-DD hh-mm-ss format" }, "last": { "type": "string", "description": "Last scheduled payment date in the YYYY-MM-DD hh-mm-ss format" } } } } }, "retry_info": { "type": "object", "description": "Object that contains information about the credential-on-file purchase retry attempts", "properties": { "trigger_operation_id": { "type": "integer", "description": "Identifier of the debit operation that is being retried. Example: `092384`" }, "next_retry_exists": { "type": "boolean", "description": "Indicator that shows whether the next scheduled attempt is available. Possible values: `true`—specified when the debiting resulted in decline and there is an available retry attempt (the number of attempts and the time allocated for making them are not used up); `false`—in all other cases" }, "next_retry_date": { "type": "string", "description": "Scheduled date and time of the next retry attempt. Example: `2023-05-24T16:58:02+0000`" } } } }, "description": "Object that contains general information about the credential-on-file purchase" }, "RecurringRequiredInfo": { "allOf": [ { "$ref": "#/components/schemas/RecurringInfo" }, { "required": [ "type" ] } ] }, "RecurringUpdateInfo": { "required": [ "id" ], "type": "object", "properties": { "id": { "type": "integer", "minimum": 1, "description": "Identifier of the created credential-on-file (COF) purchase. Can be used to perform and manage COF purchases" }, "expiry_year": { "type": "integer", "minimum": 2020, "maximum": 9999, "description": "Year of expiration for credential-on-file (COF) payment. Can be used to define the last year when COF payment are allowed" }, "expiry_month": { "type": "integer", "minimum": 1, "maximum": 12, "description": "Month of expiration for credential-on-file (COF) payment. Can be used together with expiry_year to set the final period of recurring payment validity" }, "expiry_day": { "type": "integer", "minimum": 1, "maximum": 31, "description": "Day of expiration for credential-on-file (COF) payment. Can be used together with expiry_month and expiry_year to specify the exact expiration date" }, "interval": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Interval of performing regular purchases. This parameter should be assigned a numeric value from `1` to `100` (for example, each three weeks) and is necessarily used in conjunction with the **period** parameter. May be used to configure payment recurrence frequency" }, "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount of payment in minor currency units" }, "period": { "type": "string", "pattern": "^[DWMQY]$", "description": "Frequency interval of recurring debit operations executed within a credential-on-file (COF) payment. Possible values: `D`—Day, `W`—Week, `M`—Month, `Q`—Quarter, `Y`—Year" }, "time": { "type": "string", "pattern": "^([0-1][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]$", "description": "Time of performing subsequent debits (for a regular purchase) in hh:mm:ss format. The parameter may be used if the **period** parameter is specified in the request" }, "scheduled_payment_id": { "type": "string", "maxLength": 255, "description": "Identifier assigned to the payment (as **payment_id**) within which scheduled debits are performed; it must differ from the identifier of the payment made to register a credential-on-file purchase and must be unique within the project. This identifier is case-insensitive: identifiers such as `order_314` and `Order_314` are considered identical. The identifier can include any letters, digits, and symbols in UTF-8 encoding, except when certain characters appear at the beginning or at the end of the string. These characters include a space, a horizontal tab, a null byte, a vertical tab, a newline/line feed, and a carriage return Example: `A2323`" }, "start_date": { "type": "string", "maxLength": 19, "pattern": "^([0-3]\\d-){2}[1-2]\\d{3}$", "description": "First automatic payment date and time in format **DD-MM-YYYY**. Obligatory when scheduled_payment_id is set. Applicable only when **recurring.type = R** and **recurring.period** is set. Is used to authorize and perform the next recurring payment. **start_date** can't be less than the response date of the initial *sale/auth* request within which the recurring was registered" }, "description": { "type": "string", "description": "Description for recurring", "maxLength": 255 } }, "description": "Object that contains updating recurring payment details" }, "RefundPaymentInfo": { "required": [ "description" ], "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Refund amount in minor currency units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code in ISO-4217 alpha-3 format" }, "description": { "type": "string", "maxLength": 255, "description": "Refund description or comment" }, "merchant_refund_id": { "type": "string", "maxLength": 255, "description": "Identifier of the refund for representing the refund operation within the merchant’s service" } }, "description": "Object that contains refund processing details" }, "ReturnUrl": { "type": "object", "properties": { "success": { "type": "string", "description": "URL for redirecting the customer to the merchant's web service after the payment is completed" }, "decline": { "type": "string", "description": "URL for redirecting the customer to the merchant's web service after the payment is declined" }, "return": { "type": "string", "description": "URL for redirecting the customer to the merchant's web service when the customer decides not to complete the payment" } }, "description": "Object that contains the URLs to which customer is redirected while or after payment performing" }, "SavedAccount": { "required": [ "id", "number" ], "type": "object", "properties": { "id": { "type": "integer", "description": "Identifier of the payment instrument in the payment platform" }, "number": { "type": "string", "description": "Masked number or another identifier of the customer's payment instrument (for example, a payment card, an account, or a digital wallet). Example: `424242***4243`" }, "type": { "type": "string", "description": "Type of the saved payment instrument. Example: `card`" }, "additional": { "type": "object", "description": "Object intended to contain supplementary details related to the payment instrument and customer", "properties": { "country": { "type": "string", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "phone": { "type": "string", "description": "Customer's phone number, can be 4 to 24 digits long" }, "email": { "type": "string", "description": "Customer's email address" }, "card": { "type": "object", "description": "Card information", "properties": { "expiry": { "type": "string", "description": "Expiration date of the card intended to indicate the final valid month and year in the MM/YY format. Example: `02/24`" }, "holder": { "type": "string", "description": "Name of the cardholder on the payment card" }, "type": { "type": "string", "description": "Payment card brand that was used in the processing of the payment, for example, Mastercard, Visa, and others" }, "country": { "type": "string", "description": "Customer's country code in the ISO 3166-1 alpha-2 format. Example: `GB`", "pattern": "^[A-Z]{2}$" }, "product_name": { "type": "string", "description": "Name of the card product. Example: `PREPAID`" }, "bank_name": { "type": "string", "description": "Name of the financial institution that issued the card. Example: `CITIGROUP`" } } }, "recurring_enable": { "type": "boolean", "description": "Indicator showing whether credential-on-file purchase is created and active" } } }, "last_deposit_date": { "type": "string", "description": "Date indicating the most recent deposit operation using this payment instrument" }, "last_payout_date": { "type": "string", "description": "Date indicating the most recent payout operation using this payment instrument" }, "last_tokenize_date": { "type": "string", "description": "Date indicating when this payment instrument was most recently tokenized" }, "token": { "type": "string", "description": "Payment card token" }, "operation_type": { "type": "array", "description": "Indicator that specifies the type of the operation during which the payment instrument was saved. Example: `sale`" } }, "description": "Object that contains the customer's saved payment instrument details" }, "SenderInfo": { "type": "object", "properties": { "first_name": { "type": "string", "maxLength": 255, "description": "Sender's first name. Example: `Jane`" }, "middle_name": { "type": "string", "maxLength": 255, "description": "Sender's middle, second, or patronymic name. Example: `Mary`" }, "last_name": { "type": "string", "maxLength": 255, "description": "Sender's last name. Example: `Smith`" }, "day_of_birth": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Sender's date of birth. This parameter is specified in DD-MM-YYYY format. Example: `12-12-1990`" }, "birthplace": { "type": "string", "maxLength": 255, "description": "Name of the sender's birthplace (e.g., town, city, or other settlement type). Example: `London`" }, "phone": { "type": "string", "pattern": "^[0-9]{4,24}$", "description": "Sender's phone number, can be 4 to 24 digits long" }, "residence": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Code of the country in the sender's billing address, specified in ISO 3166-1 alpha-2" }, "citizenship": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Сode of the sender's country of citizenship in ISO 3166-1 alpha-2" }, "person_type": { "type": "string", "description": "Type of the customer as a legal person, for example, a company or an individual, used for compliance" }, "account_number": { "type": "string", "maxLength": 255, "description": "Account number of the sender. Can be used for payment processing and compliance check" }, "payment_purpose": { "type": "string", "maxLength": 255, "description": "Declared purpose of the payment provided for anti-money laundering (AML) compliance checks." }, "source_of_income": { "type": "string", "maxLength": 255, "description": "Declared source of income of the sender used for anti-money laundering (AML) compliance" }, "beneficiary_relationship": { "type": "string", "maxLength": 255, "description": "Relationship between the sender and the recipient such as `employee` or `buyer`" }, "identify": { "type": "object", "description": "Object that contains sender's identification details", "properties": { "doc_number": { "type": "string", "maxLength": 255, "description": "Identity document number" }, "doc_type": { "type": "string", "maxLength": 255, "description": "Type of identity document" }, "doc_issue_date": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date of issue of identity document" }, "doc_issue_by": { "type": "string", "maxLength": 255, "description": "Who issued the identity document" } } }, "billing": { "type": "object", "description": "Object contains billing address fields", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country code of the sender's billing address in ISO 3166-1 alpha-2 format" }, "city": { "type": "string", "maxLength": 256, "description": "City of the billing sender address" }, "state": { "type": "string", "maxLength": 256, "description": "State of the sender address" }, "address": { "type": "string", "maxLength": 512, "description": "Street account address of the sender" }, "postal": { "type": "string", "maxLength": 16, "description": "Postal code of the billing address of the sender" } } }, "pan": { "type": "string", "maxLength": 32, "description": "Number of the payment card used for payment. Specified as is, without masked characters, spaces, or other separators. Example:`4314220000000056`" }, "wallet_id": { "type": "string", "maxLength": 64, "pattern": "^[^!@&~№{}|<>\\[\\]]*$", "description": "Identifier of the digital wallet. Specified as is, without masked characters, spaces, or other separators. Example:`WID20071304`" }, "address": { "maxLength": 255, "type": "string", "description": "Name of the street and the house number (including any additional parts of the address such as building indicators and apartment numbers) in the address of the payment sender. Example: `Via Certado 18`" }, "zip": { "maxLength": 255, "type": "string", "description": "Sender's postal code. Example:`50142`" }, "city": { "maxLength": 256, "type": "string", "description": "Name of the place of residence (e.g., town, city, or other settlement type) in the address of the payment sender. Example:`Florence`" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Sender's country code in the ISO 3166-1 alpha-2 format. Example: `GB`" }, "state": { "type": "string", "maxLength": 256, "description": "Sender's state" } }, "description": "Object that contains information about the sender" }, "SenderInfoPayout": { "allOf": [ { "$ref": "#/components/schemas/SenderInfo" }, { "$ref": "#/components/schemas/Descriptor" }, { "type": "object", "properties": { "funding_ips_id": { "type": "string", "maxLength": 50, "description": "Transaction ID from from a preceding AFT" } } } ] }, "SenderInfoSale": { "allOf": [ { "$ref": "#/components/schemas/SenderInfo" }, { "$ref": "#/components/schemas/Descriptor" } ] }, "SessionGeneralInfo": { "required": [ "display_name", "domain_name", "project_id", "signature", "validation_url" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" }, "validation_url": { "type": "string", "description": "URL received during the integration through Apple Pay JS API. Example: `https://apple-pay-gateway.apple.com/paymentservices/startSession`" }, "domain_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Domain name of the merchant's web service. Example: `appay.eu.ngrok.io`" }, "display_name": { "type": "string", "minLength": 1, "maxLength": 64, "description": "Name of the merchant store to display. This parameter is provided in UTF-8 encoding. Example: `Cosmoshop`" } }, "description": "Object that contains parameters for initiating an Apple Pay session" }, "SessionResponse": { "required": [ "merchantSession" ], "type": "object", "properties": { "merchantSession": { "type": "object", "description": "Object that contains the merchant session information" } }, "description": "Object that contains Apple Pay session information" }, "ShippingInfo": { "type": "object", "properties": { "type": { "type": "string", "pattern": "^0[1-7]$", "description": "Delivery type" }, "delivery_time": { "type": "string", "pattern": "^0[1-4]$", "description": "Delivery time. Possible values: `01`—digital same day delivery, `02`—same day delivery, `03`—next day delivery, `04`—delivery more than one day after the purchase was made" }, "delivery_email": { "type": "string", "maxLength": 255, "description": "Email to deliver purchased digital content to if the customer chooses email delivery", "format": "email" }, "address_usage": { "type": "string", "pattern": "^\\d{2}-\\d{2}-\\d{4}$", "description": "Date when the specified shipping address was used for the first time in DD-MM-YYYY format" }, "name_indicator": { "type": "string", "pattern": "^0[1-2]$", "description": "Indicator whether the customer's name matches the recipient's name. Possible values: `01`—names match, `02`—names do not match" }, "city": { "type": "string", "maxLength": 50, "description": "City from delivery address" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country code from delivery address in ISO 3166-1 alpha-2 format" }, "address": { "type": "string", "maxLength": 150, "description": "Street from delivery address" }, "postal": { "type": "string", "maxLength": 16, "description": "Index from delivery address" }, "address_usage_indicator": { "type": "string", "pattern": "^0[1-4]$", "description": "Indicator whether the shipping address used for this transaction was first used with the 3DS Requestor" }, "region_code": { "type": "string", "pattern": "^[0-9A-Z]{1,3}$", "description": "The region or state code of the customer billing address in ISO 3166-2 format. For example, `CA` in US or `ON` for Canada" } }, "description": "An object that contains information about delivery" }, "SkrillCustomerInfo": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "properties": { "id": { "type": "string", "maxLength": 255, "description": "Customer identifier unique within the project" }, "subject": { "type": "string", "maxLength": 250, "description": "Subject line of the email notification sent to the customer" }, "note": { "type": "string", "maxLength": 2000, "description": "Textual comment included in the email notification sent to the customer. Can be used for providing additional information" } }, "required": [ "id" ] } ] }, "SourceInfo": { "type": "integer", "properties": { "id": { "type": "integer", "enum": [ 7 ], "description": "Interface type which is used for payment performing: 7 - Payment Page in iframe mode" }, "user": { "type": "string", "maxLength": 255, "format": "email", "description": "User's email from the source" } }, "required": [ "id" ] }, "StoredCardType": { "type": "integer", "minimum": 0, "maximum": 6, "description": "Indicator of a credential-on-file (COF) purchase type. For more information, see [COF purchases](https://developers.ecommpay.com/en/en_Gate__payments_on_saved_data.html)" }, "Sum": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 10000000000000, "description": "Amount in minor currency units" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency code in ISO 4217 alpha-3 format" } }, "description": "Object that contains the amount and currency" }, "TokenData": { "required": [ "token_type" ], "type": "object", "properties": { "token_type": { "type": "string", "enum": [ "network_token" ], "description": "Indicator specifying the type of the token" }, "cryptogram": { "type": "string", "minLength": 28, "maxLength": 28, "description": "Network token verification code, received when the token is collected from the card network" }, "eci": { "type": "string", "maxLength": 2, "enum": [ "01", "02", "05", "06", "07" ], "description": "The ECI that corresponds to the network token, received when the token is collected from the card network" }, "trid": { "type": "string", "minLength": 11, "maxLength": 11, "description": "Identifier of the merchant assigned when the merchant registers in the card network service for creating network tokens" } } }, "TokenizeCustomerInfo": { "description": "Object that contains the customer details", "allOf": [ { "$ref": "#/components/schemas/CustomerInfoBase" }, { "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of the project for managing the interactions of the web service with the payment platform. This identifier is assigned by Ecommpay during the integration. Example: `57123`", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature used for signing the request parameters. Should be generated using the appropriate algorithm after all relevant parameters have been specified. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } }, "required": [ "project_id", "signature" ] } ] }, "TransactionStatusResponse": { "required": [ "general", "status" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "$ref": "#/components/schemas/PaymentResultInfo" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "request_id": { "type": "string" }, "transaction": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "date": { "type": "string", "description": "Date and time when the operation status was most recently updated in the payment platform, in ISO 8601 format" } }, "description": "Object that contains information about processing of the payment in the payment platform" }, "status": { "type": "string" }, "sum_request": { "$ref": "#/components/schemas/Sum" }, "sum_real": { "$ref": "#/components/schemas/Sum" }, "sum_refund": { "$ref": "#/components/schemas/Sum" }, "description": { "type": "string", "description": "Description of the payment" }, "operations": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": "string" }, "status": { "type": "string" }, "date": { "type": "string" }, "sum": { "$ref": "#/components/schemas/Sum" } } } }, "acs": { "required": [ "acs_url", "md", "pa_req" ], "type": "object", "properties": { "pa_req": { "type": "string", "description": "Payer Authentication Request message received during the 3‑D Secure authentication" }, "md": { "type": "string", "description": "Merchant data received from a global card network during the 3‑D Secure authentication" }, "acs_url": { "type": "string", "description": "URL of the page to which the customer is redirected for the 3‑D Secure authentication (Access Control Server page)" } }, "description": "Object that contains data required to redirect to the 3-D Secure authentication page" }, "return_url": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/ErrorItem" } } } } } }, "tags": [ { "name": "Card payments" }, { "name": "Payment links" }, { "name": "Payment Page payouts" }, { "name": "Token operations" }, { "name": "Additional information submission" }, { "name": "Verification of Payee Service" }, { "name": "ADVCash" }, { "name": "Apple Pay" }, { "name": "ATM" }, { "name": "Bancontact" }, { "name": "Banks" }, { "name": "Bank Transfer" }, { "name": "Blik" }, { "name": "BNPL" }, { "name": "Cash in Kazakhstan" }, { "name": "China UnionPay" }, { "name": "Direct Debit" }, { "name": "EcoPayz" }, { "name": "Flutterwave" }, { "name": "Google Pay" }, { "name": "Interac E-Transfer" }, { "name": "M-Pesa" }, { "name": "Mobile" }, { "name": "Neosurf" }, { "name": "Neteller" }, { "name": "Online Banking" }, { "name": "Pix" }, { "name": "Skrill" }, { "name": "Turkey QR" }, { "name": "Wallet" }, { "name": "Requests for customer details" }, { "name": "Requests for information" }, { "name": "Requests for recurring" }, { "name": "Requests for refunding specific payments" } ] } --- # Dashboard {#ru_dbl_about} раздел с материалами о работе с интерфейсом для сотрудников мерчантов Dashboard и с программным интерфейсом для получения информации об операциях Data API ## Обзор и подготовка к работе {#section_lq3_ltt_15b .section} Материалы с вводными сведениями об интерфейсе Dashboard и о том, как начать работу с ним: - [Общая информация](ru_dbl_overview.md)— об интерфейсе Dashboard, его особенностях и порядке доступа к нему. - [Основные возможности и ролевая модель](ru_dbl_roles_overview.md)— о ключевых возможностях интерфейса, поддерживаемых ролях и распределении прав между этими ролями. - [Интерфейс](ru_dbl_interfaces.md)— о работе с основными элементами интерфейса: меню, разделами и реестрами. - [Управление проектами](ru_dbl_projects.md)— о свойствах проектов, которые можно настраивать через Dashboard, и о том, как настраивать правила отправки оповещений. ## Работа с интерфейсом {#section_qzq_wtt_15b .section} Материалы о разнообразных задачах, которые можно решать с помощью интерфейса Dashboard, с описанием необходимых действий: - [Контроль и проведение платежей](ru_dbl_payments.md)— о том, как контролировать проведение платежей и проводить оплаты, возвраты и выплаты разных типов, а также управлять регулярными оплатами через Dashboard. - [Ведение финансового учёта](ru_dbl_balances.md)— о балансах, их особенностях и о том, как контролировать балансы через Dashboard. - [Работа с рисками](ru_dbl_risks.md)— о процессах управления рисками и том, как контролировать выявленные факты мошенничества и настраивать «чёрные» списки через Dashboard. ## Связанные интерфейсы {#section_emt_n5t_15b .section} Материалы о возможностях и технических аспектах интерфейса Data API, который позволяет получать информацию об операциях, опротестованиях и балансах — [Использование Data API](ru_dbl_api_protocol.md). - **[Общая информация](ru_dbl_overview.md)** статья с вводной информацией об интерфейсе Dashboard, его особенностях и порядке доступа к нему - **[Основные возможности и ролевая модель](ru_dbl_roles_overview.md)** статья о ключевых возможностях интерфейса Dashboard, поддерживаемых пользовательских ролях и распределении прав между ними - **[Интерфейс](ru_dbl_interfaces.md)** статья о работе с основными элементами интерфейса Dashboard: меню, разделами и реестрами - **[Управление проектами](ru_dbl_projects.md)** Статья о том, как настраивать проекты в интерфейсе Dashboard. - **[Контроль и проведение платежей](ru_dbl_payments.md)** Статья о проведении платежей через интерфейс Dashboard. - **[Ведение финансового учёта](ru_dbl_balances.md)** статья о балансах для работы с платформой и особенностях работы с ними, а также о возможностях контроля балансов, контроля курсов конвертации валют и учёта информации о банковских счетах через интерфейс Dashboard - **[Работа с рисками](ru_dbl_risks.md)** статья о процессах управления рисками в электронной коммерции и возможностях контролировать выявленные факты мошенничества и настраивать «чёрные» списки через Dashboard - **[Работа с программными оповещениями об опротестованиях платежей](ru_dbl_chargeback_callbacks.md)** статья о возможностях работы с программными оповещениями о событиях, связанных с оформлением и рассмотрением опротестований финансовых операций - **[Использование Data API](ru_dbl_api_protocol.md)** статьи о возможностях и технических аспектах интерфейса Data API, который позволяет получать информацию об операциях, опротестованиях и балансах - **[Data API](data_api.md)** спецификация Data API с описанием моделей и структур данных для формирования запросов к различным конечным точкам --- # Общая информация {#ru_dbl_overview} статья с вводной информацией об интерфейсе Dashboard, его особенностях и порядке доступа к нему **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Назначение и особенности {#ru_dbl_overview_main_use} Dashboard представляет собой веб-интерфейс для мерчантов Ecommpay. Он доступен по адресу [dashboard.ecommpay.com](https://dashboard.ecommpay.com) и позволяет специалистам мерчантов решать разнообразные задачи по всем проектам своих организаций в платёжной платформе Ecommpay, в том числе: - анализировать данные о проведении платежей и о сводных финансовых результатах— в разных разрезах и с применением инструментов визуализации; - осуществлять оплатыразных типов, а также возвраты \(частичные и полные\) и выплаты средств пользователям своих веб-сервисов с поддержкой одиночной и пакетной отправки запросов; - контролировать и предотвращать попытки мошенничестваи работать с опротестованиями \(chargebacks\); - формировать различные отчёты со сводной информациейо проведении платежей и финансовых результатах; - просматривать и настраивать свойства доступных проектов; - настраивать оформление платёжной формы Payment Page\(при её использовании в рамках проектов взаимодействия с платёжной платформой Ecommpay\). И к этим возможностям регулярно добавляются новые. ![](images/ecommpay/dbl/ru_dbl_overview.svg) Dashboard изначально проектировался с учётом передовых подходов и технологий разработки, включая, в частности, элементы дизайн-мышления. Благодаря этому в интерфейсе используется множество решений, уже протестированных с участием потенциальных и реальных пользователей, и при желании любые клиенты Ecommpay могут обратиться к своему курирующему менеджеру и принять участие в дальнейшем развитии этого интерфейса. С вопросами по работе с интерфейсом Dashboard можно обращаться к данной документации и к специалистам Ecommpay. ## Порядок доступа {#ru_dbl_overview_access} Поскольку интерфейс Dashboard предоставляет возможности работы с финансовой информацией и финансовыми операциями, для работы с ним применяется ряд средств защиты от несанкционированных действий. Это: - разграничение доступа через учётные записи пользователей с распределением прав на основе ролевой модели \([подробнее](ru_dbl_roles_overview.md)\); - дополнительная аутентификация пользователей с применением «второго фактора» — через приложение Google Authenticator; - подтверждение выплат с использованием одноразовых кодов, отправляемых пользователям по зарегистрированным номерам телефонов\(с вопросами о подключении данной возможности можно обращаться к курирующему менеджеру Ecommpay\). Такие средства защиты соответствуют требованиям директивы Европейского союза об оказании платёжных услуг PSD 2 \(Revised Directive on Payment Services, Directive \(EU\) 2015/2366\) и позволяют обеспечивать комфортную и безопасную работу пользователей. Среди прав для работы с интерфейсом Dashboard выделяются права, использование которых не требует применения второго фактора аутентификации. Это относится к следующим разделам и правам для работы с этими разделами: - Мой профиль: редактирование профиляи управление API-токенами. - Платежи: просмотр реестра платежей, просмотр информации о платеже, использование конфигуратора, выполнение возвратов, подтверждение и отмена списаний по оплатам в две стадии. - Отчёты: управление отчётами. - Проекты: просмотр проектов. - Подписки: просмотр реестра регулярных оплат \(подписок\), просмотр информации о таких оплатах, изменение условий и отмена списаний. - Мануальные платежи: выполнение возвратов, подтверждение и отмена списаний. - Расчёты с партнёрами: создание и редактирование карточек партнёров и просмотр реестров карточек и выплат партнёрам. Для использования хотя бы одного права вне этого перечня пользователям следует указывать номер телефона и включать двухфакторную аутентификацию. **Прим.:** Доступом к информации о наличии прав пользователей и правом добавлять номера телефонов к учётным записям обладают пользователи с ролью `Merchant admin` \(через раздел **Моя команда**\). Новым пользователям с правами, требующими применение двухфакторной аутентификации, при первом обращении к интерфейсу следует: 1. Если требуется добавить номер телефона — обратиться к пользователю с учётной записью `Merchant admin`, чтобы этот пользователь добавил номер к требуемой учётной записи. 2. Указать в интерфейсе Dashboard имя и пароль учётной записи. 3. Включить в приложении Google Authenticator двухфакторную аутентификацию с использованием кода из SMS-сообщения. 4. Подтвердить в интерфейсе Dashboard свою подлинность с помощью одноразового кода из приложения Google Authenticator. Те, для кого двухфакторная аутентификация остаётся необязательной, могут включать её и добавлять номер телефона в профиле своей учётной записи при наличии права редактировать профиль. Чтобы указать номер телефона и включить двухфакторную аутентификацию через профиль учётной записи, следует: 1. Открыть профиль учётной записи. Для этого необходимо щёлкнуть имя или иконку учётной записи справа в главном меню и выбрать в выпадающем списке пункт **Мой профиль**. 2. Добавить номер телефона. Для этого следует: 1. Перейти в режим редактирования личной информации, щёлкнув **Редактировать** на панели **Профиль**. 2. Указать и подтвердить номер телефона. Номер телефона следует указывать в международном формате \(`+{международный код страны}{номер абонента}`\) в соответствующем поле ввода, а для подтверждения следует ввести код из SMS-сообщения в появившемся окне. 3. Сохранить изменения, щёлкнув кнопку **Сохранить**, расположенную в правой верхней части панели **Профиль**. 3. Включить двухфакторную аутентификацию. Для этого необходимо установить переключатель **Двухфакторная аутентификация**, расположенный на панели **Безопасность**, в активное положение и выполнить действия согласно инструкции в интерфейсе. 4. Убедиться, что все изменения сохранены. Об этом свидетельствуют активное положение переключателя двухфакторной аутентификации и отображение номера телефона в профиле. --- # Основные возможности и ролевая модель {#ru_dbl_roles_overview} статья о ключевых возможностях интерфейса Dashboard, поддерживаемых пользовательских ролях и распределении прав между ними **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Введение {#ru_dbl_roles_overview_info} Dashboard представляет собой единый интерфейс для специалистов мерчанта. В нём поддерживается полный набор требуемых функций, и для того, чтобы распределять доступ к разным функциям между разными специалистами\(с учётом организационной структуры и прочих факторов\), в Dashboard используется ролевая модель. В этом разделе описаны ключевые возможности, поддерживаемые роли инюансы их использования, а также распределение прав между ролями. ## Возможности {#ru_dbl_roles_overview_capabilities} Возможности Dashboard можно разбить на следующие группы: - Контроль и анализ проведения платежей— с поддержкой просмотра, фильтрации, поиска и визуализации информации о проводимых и проведённых платежах. - Выполнение финансовых операций— с поддержкой оплатразных типов, выплат и возвратов \(как полных, так и частичных\), а также с возможностями управления регулярными оплатами. - Расчёты с партнёрами— с поддержкой проведения одиночных и массовых выплат на счета юридических лиц \([подробнее](ru_b2bremit_about.md)\). - Настройка оформления платёжной формы Payment Page— с поддержкой просмотра, создания, изменения и удаления вариантов оформления платёжной формы \([подробнее](ru_PP__design_customisation.md)\). - Ведение финансового учёта— с поддержкой подготовки и просмотра различных отчётов и с доступом к информации о балансах. - Работа с рискамии опротестованиями по проведённым оплатам \(chargebacks\)— с контролем выявляемого мошенничества, включая формирование «белых» и «чёрных» списков, и с контролем информации об опротестованиях, включая возможность соглашаться с опротестованием отдельных оплат без передачи дел в арбитраж. - Администрирование работы с интерфейсом Dashboard— с поддержкой управления учётными записями пользователей, включая распределение ролей и контроль действий, и с поддержкой просмотра свойств доступных проектов, включая настройку отдельных свойств. Для доступа к одной или нескольким из этих групп возможностей используются заданные роли. ## Роли {#ru_dbl_roles_overview_roles} |Для распределения прав в Dashboard применяются роли со следующими возможностями:| | |**Designer**|**Support**|**Operations**|**Finance**|**Risks**|**Merchant admin**| |- Контроль и анализ проведения платежей |–|±|+|+|+|+| |- Выполнение финансовых операций |–|±|+|–|–|+| |- Ведение финансового учёта |–|–|–|+|–|+| |- Работа с рискамии опротестованиями по проведённым оплатам \(chargebacks\) |–|–|–|–|+|+| |- Администрирование работы с интерфейсом Dashboard |–|–|–|–|–|+| |- Стилизация Payment Page |+|–|–|–|–|+| |Эти роли могут подходить для специалистов следующих категорий:| | |- Product owner - UX/UI Designer - Marketing |- Support manager - Monitoring manager |- Finance manager - Product owner - Prоduct/project manager - Payments specialist |- Finance manager - Treasury specialist - Accountant |- Fraud Prevention Manager - Risk Manager - Fraud Team |- Chief Operation Officer - Product owner - Chief Executive Officer | Этот набор ролей фиксирован, и на стороне мерчанта нет возможности создавать другие роли. Но при этом для отдельных учётных записей можно корректировать набор прав, заданных через роль, а также соотносить учётную запись с несколькими ролями одновременно и тем самым сочетать права, изначально не входящие в один из базовых наборов. Например, если для учётной записи с ролью Operations требуется доступ к просмотру балансов, то дополнительно можно отнести эту учётную запись к роли Finance с правом просматривать балансы в разделе **Финансы**. Учётные записи с ролью Merchant Admin наделены полным набором прав и доступом ко все проектам мерчанта, и такие учётные записи могут создаваться только специалистами технической поддержки Ecommpay. Учётные записи с остальными ролями создаются и настраиваются \(в том числе в плане доступа к проектам\) сотрудниками мерчанта с ролью Merchant Admin. При этом все права, назначенные учётной записи, актуальны для всех проектов, к которым предоставлен доступ для этой учётной записи. Выборочное применение прав в зависимости от проектов в рамках одной учётной записи не используется. ## Права {#ru_dbl_roles_overview_rights} Основные права для работы с различными разделами интерфейса Dashboard распределяются по ролям в соответствии с представленной таблицей. В дополнение к этим правам через специалистов технической поддержки Ecommpay могут запрашиваться отдельные расширенные права— если они используются в платформе и допустимы для применения на стороне мерчанта. В частности, это может быть актуальным, чтобы обеспечить возможность редактирования сотрудниками мерчанта «белых» списков. | |Designer|Support|Operations|Finance|Risks|Merchant admin| |:-|--------|-------|----------|-------|-----|:-------------| |**Моя команда**| |Просмотр реестра учётных записей пользователей|–|–|–|–|–|+| |Управление учётными записями пользователей|–|–|–|–|–|+| |**Финансы**| |Просмотр информации о балансах|–|–|–|+|–|+| |Просмотр информации о банковских счетах|–|–|–|+|–|+| |Создание и редактирование карточек банковских счетов|–|–|–|+|–|+| |**Отчёты**| |Просмотр и формирование отчётов|–|+|+|+|+|+| |**Платежи**| |Просмотр реестра платежей|–|+|+|+|+|+| |Настройка отображения реестра платежей|–|+|+|+|+|+| |Просмотр детальной информации о платежах|–|+|+|+|+|+| |Выполнение возвратов|–|–|+|–|–|+| |Подтверждение списаний по оплатам в две стадии|–|–|+|–|–|+| |Отмена списаний по оплатам в две стадии|–|–|+|–|–|+| |**Расчеты с партнёрами**| |Просмотр информации о партнёрах и выплатах этих партнёров|–|–|+|+|–|+| |Создание и редактирование карточек партнёров|–|–|+|–|–|+| |Согласование и удаление карточек партнёров|–|–|+|–|–|+| |Создание заявок на выплаты|–|–|+|–|–|+| |**Ссылки на оплату**| |Просмотр реестра оплат по платёжным ссылкам|–|–|+|–|–|+| |Формирование платёжных ссылок|–|–|+|–|–|+| |Деактивация платёжных ссылок|–|–|+|–|–|+| |**Мануальные платежи**| |Просмотр реестров выплат и массовых запросов|–|–|+|–|–|+| |Настройка отображения реестров выплат и массовых запросов|–|–|+|–|–|+| |Просмотр детальной информации о платежах|–|–|+|–|–|+| |Проведение выплат|–|–|+|–|–|+| |Выполнение возвратов|–|–|+|–|–|+| |Подтверждение списаний по оплатам в две стадии|–|–|+|–|–|+| |Отмена списаний по оплатам в две стадии|–|–|+|–|–|+| |Проведение оплат MO/TO|–|–|+|–|–|+| |**Подписки**| |Просмотр реестра подписок|–|+|+|–|–|+| |Просмотр детальной информации о подписках|–|+|+|–|–|+| |Управление подписками|–|–|+|–|–|+| |**Риски**| |Просмотр информации о мошеннических операциях|–|–|–|–|+|+| |Просмотр «белых» и «чёрных» списков|–|–|–|–|+|+| |Редактирование «чёрных» списков|–|–|–|–|+|+| |**Чарджбэки**| |Просмотр реестра опротестований|–|–|–|+|+|+| |Просмотр детальной информации об опротестованиях|–|–|–|+|+|+| |Согласие с опротестованиями|–|–|–|+|+|+| |**Мой профиль**| |Редактирование общей информации в учётной записи|–|+|+|+|+|+| |Управление токенами для работы с Data API|–|+|+|+|+|+| |**Аналитика**| |Просмотр аналитических панелей|–|–|+|+|+|+| |Настройка отображения аналитических панелей|–|–|+|+|+|+| |**Проекты**| |Просмотр списка проектов|+|+|+|+|+|+| |Настройка свойств проектов|–|–|–|–|–|+| |Работа с инструментом Payment Page Designer|+|–|–|–|–|+| |**Помощь**| |Просмотр справки|+|+|+|+|+|+| --- # Интерфейс {#ru_dbl_interfaces} статья о работе с основными элементами интерфейса Dashboard: меню, разделами и реестрами **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Введение {#ru_dbl_interface_overview} Интерфейс Dashboard разбит на тематические разделы, в каждом из которых представлены свои срезы данных и инструменты для работы. Многие элементы в разделах являются типовыми, а большинство задач решается с использованием реестров. Для поиска данных и ряда общих операций используется главное меню в верхней части интерфейса, а для перехода между разделами — панель навигации в левой части интерфейса. В этом разделе представлены краткие сведения о работе с главным меню, разделами и реестрами. ## Главное меню {#ru_dbl_upper_panel} ### Обзор {#section_s42_rkl_hlb .section} Главное меню в верхней части интерфейса Dashboard содержит кнопки для управления видом интерфейса, перехода к вспомогательным разделам и завершения сеанса работы. ![](images/ecommpay/dbl/ru_dbl_main_menu.svg) *Главное меню с развёрнутой панелью навигации: 1 — кнопка отображения панели навигации; 2 — часы; 3 — кнопка перехода к разделу «‎Помощь»; 4 — переключатель языка; 5 — кнопки для отображения панели уведомлений и панели поиска; 6 — кнопка перехода к профилю учётной записи; 7 —.кнопка завершения сеанса работы с интерфейсом.* ### Панель навигации {#section_txz_15m_hlb .section} Панель навигации отображается в левой части интерфейса и содержит кнопки перехода к разделам, к которым имеется доступ у используемой учётной записи. Панель может отображаться как в развёрнутом виде \(с иконками и названиями разделов\), так и в свёрнутом \(только с иконками и всплывающими подсказками с названиями разделов\). Управлять видом панели можно с помощью кнопки ![](images/universal/dbl/icon_menu.svg) в левой части главного меню. ### Часы {#section_pzs_ztm_hlb .section} В центральной части главного меню отображаются часы с возможностью выбора часового пояса. Этот выбор влияет на отображение данных в реестрах платежей, но не применяется для отсчёта операционных дней. В отчётах всегда используется UTC + 00:00. ### Панель поиска {#section_r4t_f5m_hlb .section} Панель поиска содержит заданный набор полей, через которые можно оперативно находить требуемые платежи. Для удобства пользователей и оптимизации скорости поиска на панель выведены наиболее востребованные параметры, а поиск осуществляется только по полному совпадению атрибутов. Результаты поиска отображаются в реестре платежей в разделе **Платежи**. ![](images/ecommpay/dbl/ru_dbl_search_panel.svg "Главное меню с раскрытой панелью поиска") Для полей, которые выведены на панель, но пока неактивны, поиск находится в стадии разработки и оптимизации. ## Разделы {#ru_dbl_sections} В интерфейсе Dashboard используются следующие разделы: - **Моя команда**— с реестром всех учётных записей сотрудников мерчанта и с инструментами для управления этими учётными записями и просмотра истории действий пользователей. - **Финансы**— с информацией о текущих балансах мерчанта с разбиением по проектам. - **Отчёты**— с инструментами для формирования отчётов и срезов на основе заданных условий и для просмотра и экспорта сформированных отчётов. - **Платежи**— с реестром всех проведённых и проводимых платежей, инструментами для настройки отображения данных в реестре и возможностями просматривать детальную информацию о платежах и выполнять одиночные возвраты. - **Расчёты с партнёрами**— c реестром карточек партнёров и возможностями управлять этими карточками и создавать заявки на одиночные и массовые выплаты партнёрам, а также просматривать реестры и карточки проведённых и проводимых выплат. - **Ссылки на оплату**— с реестром всех проведённых и проводимых оплат по платёжным ссылкам и инструментами для работы с платёжными ссылками — их формирования, деактивации и автоматической отправки на адреса электронной почты пользователей. - **Мануальные платежи**— с реестрами всех проведённых и проводимых выплат и массовых запросов, инструментами для настройки отображения данных в реестрах и возможностью просматривать детальную информацию о выплатах, а также с инструментами для проведения одиночных и массовых выплат и массовых возвратов. - **Подписки**— с реестром зарегистрированных регулярных оплат \(подписок\), инструментами для настройки отображения данных в этом реестре и возможностями просматривать детальную информацию о регулярных оплатах, изменять их условия и отменять дальнейшие списания. - **Риски**— с реестрами платежей, к которым относятся мошеннические операции, и критериями «белых» и «чёрных» списков мерчанта, а также инструментами для настройки отображения данных в этих реестрах и с инструментами для редактирования «белых» и «чёрных» списков. - **Чарджбэки**— с реестром всех \(завершённых и находящихся на рассмотрении\) опротестований по проведённым платежам \(chargebacks\), инструментами для настройки отображения данных в реестре и возможностями просматривать детальную информацию о платежах и соглашаться с опротестованием отдельных оплат без передачи дел на арбитраж. - **Мой профиль**— с информацией о пользователе и набором инструментов для настройки учётной записи. - **Аналитика**— с предустановленным набором аналитических панелей для оперативного анализа проведения платежей и операций по проектам мерчанта \(к которым есть доступ у используемой учётной записи\). - **Проекты**— с информацией об отдельных свойствах проектов мерчанта \(к которым есть доступ у используемой учётной записи\) и инструментами для настройки этих свойств. - **Помощь**— с информацией о работе с основным меню и разделами интерфейса \(к которым есть доступ у используемой учётной записи\). ## Реестры {#ru_dbl_registry} Для отображения массивов записей, например о платежах или учётных записях, в интерфейсе Dashboard используются реестры. В одном разделе могут быть представлены как один, так и несколько реестров. И для переключения между ними используются вкладки с названиями соответствующих реестров. ![](images/ecommpay/dbl/ru_dbl_risks_switch_between_registries.svg "Переключение между реестрами") Все они устроены однотипно и при работе с ними можно настраивать состав и порядок столбцов, фильтровать записи и делать определённые действия, будь то переход к детальной информации о платеже или удаление учётной записи пользователя. В каждом разделе с реестром представлены два типа фильтров: - *Встроенные фильтры* — доступные через кнопки в области фильтрации в верхней части реестра.С помощью этих фильтров можно в одно действие применять и отменять фильтрацию записей по отдельным атрибутам, например, по валюте платежа. - *Настраиваемые фильтры* — доступные в отдельной панели, которую можно вызвать через кнопку в правой части области фильтрации.С помощью этих фильтров можно фильтровать записи по настроенной совокупности условий. И такие фильтры можно гибко конфигурировать и сохранять для последующего применения. Дополнительно, в зависимости от конкретного реестра, для работы с ним доступны дополнительные инструменты. Например, для реестров платежей можно настраивать состав и порядок столбцов с помощью конфигуратора, который вызывается через кнопку в правой части области фильтрации. |![](images/ecommpay/dbl/ru_dbl_payments_list.svg) *Реестр платежей в разделе **Платежи**: 1 — вкладка со списком всех платежей; 2 — встроенные фильтры; 3 — кнопки сброса всех фильтров, отображения настраиваемых фильтров и настройки отображения списка платежей.*| |![](images/ecommpay/dbl/ru_dbl_payouts_list.svg) *Реестр выплат в разделе **Мануальные платежи**: 1 — вкладки с реестрами; 2 — кнопка проведения платежей; 3 — встроенные фильтры; 4 — кнопки сброса всех фильтров, настройки отображения настраиваемых фильтров и настройки отображения списка платежей.*| |![](images/ecommpay/dbl/ru_dbl_user_list.svg) *Реестр учётных записей в разделе **Моя команда**: 1 — вкладки с реестрами; 2 — кнопка создания новой учётной записи; 3 — встроенные фильтры; 4 — кнопки сброса всех фильтров, настройки отображения настраиваемых фильтров и настройки отображения списка платежей; 5 — инструменты редактирования учётной записи.*| --- # Управление проектами {#ru_dbl_projects} статья о возможностях настройки проектов взаимодействия с платформой Ecommpay через Dashboard, включая настройку правил отправки программных оповещений и регистрацию доменов для работы с сервисом Apple Pay **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Общая информация {#ru_dbl_projects_overview} При работе с интерфейсом Dashboard можно просматривать и настраивать отдельные свойства проектов. Для этого выделен раздел **Проекты**, доступ к которому регулируется отдельным правоми по умолчанию доступен учётным записям с ролью `Merchant Admin`. Также право на просмотр информации в этом разделе может предоставляться и учётным записям с другими ролями \([подробнее](ru_dbl_roles_overview.md)\). ![](images/ecommpay/dbl/ru_dbl_projects.svg "Карточка проекта") В разделе **Проекты** доступны карточки с информацией об отдельных проектах. В каждой карточке используются следующие вкладки: - **Общие** — для просмотра основных сведений о проекте и управления секретным ключом проекта, который обязателен для проведения оплат MO/TO через интерфейс Dashboard; - **Платёжные методы** — для просмотра списка подключённых платёжных методовс возможностью запросить подключение ApplePay и PayPal; - **Ссылки для перенаправления** — для настройки адресов возвращения пользователей к веб-сервису при работе с Payment Page \([подробнее](ru_PP_redirect_modes.md)\); - **Оповещения** — для настройки правил отправки оповещений; - **Payment Page Designer** — для настройки индивидуального оформления Payment Page \([подробнее](ru_PP__design_customisation.md)\); **Прим.:** Вкладка **Payment Page Designer** не отображается при работе с мобильных устройств. - **Верификация доменов для Apple Pay** — для регистрации доменов в сервисе Apple Pay и управления ими; - **Настройки повторных попыток подписок** — для настройки отдельного графика повторных попыток списаний \(действительного для каждой регулярной оплаты в рамках конкретного проекта\). При этом стоит учитывать, что в интерфейсе Dashboard нельзя создавать и удалять проекты. Для этого следует обращаться к курирующему менеджеру Ecommpay. ## Работа с правилами отправки оповещений {#ru_dbl_projects_callbacks} ### Общая информация {#section_szn_y1c_nsb .section} При проведении платежей через платформу Ecommpay к веб-сервису мерчанта отправляются оповещения, например с информацией для перенаправления пользователей или с информацией о результатах выполнения операций. Структура этих оповещений и работа с ними описаны в статье [Работа с оповещениями](ru_platform_callbacks.md). Оповещения могут отправляться на адреса, предоставленные мерчантом при интеграции, и на иные, указываемые через Dashboard. С помощью инструментов в разделе **Проекты** можно создавать неограниченное количество правил, каждое из которых определяет, в каких случаях на какие адреса должны отправляться оповещения. Также в этом разделе можно просматривать реестр правил, заданных при интеграции и созданных через Dashboard, и управлять правилами с типовыми форматами оповещений: активировать, деактивировать и удалять их. ![](images/ecommpay/dbl/ru_dbl_projects_callbacks.svg "Инструменты для управления правилами") ### Структура правил и особенности их применения {#section_rns_lbc_nsb .section} Каждое правило определяет, при выполнении какого набора условий на какой адрес отправлять оповещения. В наборе условий задаются тип платежа, тип события \(**Тип результата** в интерфейсе Dashboard\)и платёжный метод. При этом для каждого из этих параметров допускается лишь одно значение. К возможным значениям относятся: - типы платежей `purchase, recurring, payout, account verification` и `all` \(для всех перечисленных типов\); - типы событий `success, decline, tokenize, refund, recurring, error` и `all` \(для всех перечисленных типов\); - коды платёжных методов, подключённых к проекту, или пустое значение \(для всех подключённых методов\). Вместе с тем при работе с правилами через Dashboard стоит учитывать ряд особенностей: - В реестре отображаются правила отправки оповещений для всех указанных типов платежей и событий, но управление некоторыми из этих правил осуществляется только через сотрудников технической поддержки Ecommpay. К таким правилам относятся правила для оповещений с нетиповыми форматами. - Каждое правило для платежей типа `purchase` действует как для одностадийных, так и для двухстадийных оплат, поэтому каждое такое правило в реестре разбивается на два — для типов платежей `purchase` и `purchase_dms`. При необходимости избыточные правила можно удалять. - Настройка отправки оповещений с типом события `error` поддерживается только для платежей всех типов \(`all`\). - Если одному набору условий соответствует несколько правил с разными адресами, то оповещения дублируются на все эти адреса — без какого-либо приоритета и независимо от способа указания адресов \(при интеграции или через Dashboard\).Так, для представленных на изображении правил `96071` и `96081` оповещения о выполнении очередного списания в рамках повторяемых оплат должны отправляться на оба адреса, так как этот набор условий соответствует обоим правилам. ![](images/ecommpay/dbl/ru_dbl_projects_callbacks_example.svg) - Если при деактивации или удалении правила есть действующие правила с аналогичными условиями, то оповещения отправляются на адреса, указанные в этих правилах, иначе — отправка оповещений для заданных условий прекращается. ### Управление правилами {#section_exb_wbc_nsb .section} Чтобы создать правило отправки оповещений, следует: 1. Выбрать целевой проект. Для этого необходимо открыть раздел **Проекты** и выбрать проект из выпадающего списка **Ваши проекты** на вкладке с настройками проекта. 2. Открыть вкладку **Оповещения** в левой части карточки проекта. 3. Задать правило с учётом условий, описанных вместе со структурой правил. Для этого необходимо щёлкнуть кнопку **Создать** и задать условия. 4. Сохранить правило, щёлкнув кнопку **Сохранить**. **Прим.:** Если кнопка **Сохранить** не активна, это может быть вызвано тем, что указаны не все обязательные данные либо задан некорректный URL. Чтобы активировать или деактивировать отдельное правило, следует использовать переключатель **Статус** в соответствующей строке реестра. Чтобы удалить отдельное правило, следует щёлкнуть кнопку ![](images/universal/dbl/icon_trashbin.svg) в соответствующей строке реестра и подтвердить действие. ## Работа с доменами для сервиса Apple Pay {#ru_dbl_projects_apple_pay_domain_verification} ### Общая информация {#section_szn_y1c_nsb .section} Если в рамках какого-либо из проектов мерчанта актуально открывать платёжную форму Payment Page непосредственно на страницах веб-сервиса \(в элементе iframe\) или в модальном окне и использовать при этом платёжный метод Apple Pay, то для обеспечения такой возможности необходимо предварительно зарегистрировать рабочие домены веб-сервиса в сервисе Apple Pay. Для этого в разделе **Проекты** интерфейса Dashboard выделена вкладка **Верификация доменов для Apple Pay**, инструменты которой позволяют управлять составом актуальных доменов веб-сервиса для работы с методом Apple Pay.Ограничения на количество зарегистрированных доменов для проекта нет. ![](images/ecommpay/dbl/ru_dbl_projects_domains.svg "Форма регистрации доменов") ### Ограничения {#section_c5n_j3d_3gc .section} При регистрации доменов для работы с методом Apple Pay через платёжную форму Payment Page \(с её открытием в элементе iframe или модальном окне\) необходимо учитывать следующие ограничения: - Должны регистрироваться все домены, в рамках которых предполагается использование платёжной формы с поддержкой платёжного метода Apple Pay.При этом под доменом подразумевается домен с полным доменным именем \(fully qualified domain name\), включающим имена доменов всех уровней, от нижнего до верхнего. Если какой-либо из доменов не зарегистрирован, то платёжный метод Apple Pay остаётся доступным в платёжной форме Payment Page, но попытки оплаты этим методом отклоняются. - Могут регистрироваться только те домены, которые учтены в договорных отношениях с Ecommpayили отдельно согласованы с курирующим менеджером Ecommpay. - Может использоваться только файл верификации от Ecommpay \(подробнее [далее](ru_dbl_projects.md#section_rns_lbc_nsb)\).Использование файлов верификации от третьих сторон для работы с платёжной формой Payment Page от Ecommpay недопустимо. - Файлы верификации должны располагаться строго по указанным адресам на зарегистрированных доменах, без изменений этих адресов и перенаправлений к другим ресурсам. ### Управление составом доменов {#section_rns_lbc_nsb .section} Чтобы зарегистрировать актуальные домены следует: 1. Выполнить подготовительные технические работы. Для этого следует: 1. Скачать файл верификации доменов `apple-developer-merchantid-domain-association` [из репозитория Ecommpay](https://paymentpage.ecommpay.com/.well-known/apple-developer-merchantid-domain-association). 2. Разместить скачанный файл верификации на каждом из актуальных доменов — в папке `.well-known`, размещённой в корневой папке домена \(таким образом, чтобы полный URL для этого файла выглядел как `https:///.well-known/apple-developer-merchantid-domain-association`\). 3. Внести в число доверенных IP-адресов для каждого домена адреса, используемые сервисом Apple Pay для верификации доменов и проведения платежей \([подробнее](https://developer.apple.com/documentation/apple_pay_on_the_web/setting_up_your_server)\). 2. Открыть интерфейс Dashboard. 3. Открыть форму регистрации доменов. Для этого следует перейти на вкладку **Верификация доменов для Apple Pay** и щёлкнуть кнопку **Добавить новый**. 4. Выбрать актуальное юридическое лицов выпадающем списке **Юридическое лицо**. 5. Указать актуальные доменные имена. Для этого необходимо указать для каждого домена его полное доменное имя \(fully qualified domain name, включая домены всех уровней, например `www.traveltowels.cosmoshop.vrg`\) в поле **Доменное имя** и подтвердить добавление, щёлкнув кнопку ![](images/ecommpay/dbl/icon_add.svg). При этом следует учитывать, что за один раз можно добавлять не более десяти доменных имён, а некорректно указанные имена можно удалять с помощью кнопки ![](images/universal/dbl/icon_trashbean2.svg). 6. Отправить запрос на регистрацию доменов, щёлкнув кнопку **Сохранить**. **Прим.:** Если кнопка **Сохранить** не активна, это может быть вызвано тем, что не выбрано **Юридическое лицо** либо не заполнено хотя бы одно **Доменное имя**. При отклонении запроса на регистрацию в интерфейсе Dashboard отображается соответствующее сообщение об ошибке, а также рекомендации по её устранению. В случаях, когда устранить неполадки не удаётся самостоятельно, можно обращаться к специалистам технической поддержки Ecommpay. 7. Убедиться, что домены зарегистрированы. Для этого можно проверить наличие соответствующих записей в реестре доменов на вкладке **Верификация доменов для Apple Pay**. Стоит учитывать, что после регистрации домены нельзя удалять из реестра, но при необходимости их можно деактивировать. Чтобы деактивировать зарегистрированный домен или повторно активировать деактивированный ранее, следует использовать переключатель **Статус** в соответствующей строке реестра. Вместе с тем стоит учитывать, что при активации доменов, как и при их регистрации, могут возникать ошибки, сопровождаемые соответствующими сообщениями в интерфейсе Dashboard. ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с методом Apple Pay при указанных вариантах открытия Payment Page также могут быть полезны следующие материалы: - [Apple Pay](pm_applepay.md)— о платёжном методе Apple Pay и особенностях работы с ним; - [Открытие в элементе iframe HTML-страницы](ru_PP_method_Embedded.md)— об открытии платёжной формы Payment Page в элементе iframe; - [Открытие в модальном окне](ru_PP_method_ModalWindow.md)— об открытии платёжной формы Payment Page в модальном окне. --- # Контроль и проведение платежей {#ru_dbl_payments} статья о возможностях контролировать проведение платежей и проводить оплаты, возвраты и выплаты разных типов, а также управлять регулярными оплатами при работе с интерфейсом Dashboard **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Общая информация {#ru_dbl_payments_overview} В интерфейсе Dashboard выделено несколько разделов для контроля и проведения платежей: - **Платежи** — для контроля проведения платежей всех типови выполнения отдельных операций, включая подтверждения и отмены списаний по двухстадийным оплатам, возвраты по оплатам любых типов и выплаты; - **Ссылки на оплату** — для работы с платёжными ссылками; - **Мануальные платежи** — для работы с одиночнымиоплатами MO/TO и выплатами, а также с групповыми подтверждениями и отменами списаний по двухстадийным оплатам и групповыми возвратами и выплатами; - **Подписки** — для работы с регулярными оплатами; - **Расчёты с партнёрами** — для работы c выплатами на счета юридических лиц \([подробнее](ru_b2bremit_about.md)\). Для контроля проведения платежей в разделах **Платежи**и **Мануальные платежи** доступны реестры с возможностью фильтрации данных, и в этих реестрах поддерживается возможность открывать карточки отдельных платежей. При этом карточки платежей открываются в отдельных внутренних вкладках раздела, что позволяет оперативно переключаться между ними и общим реестром. ![](images/ecommpay/dbl/ru_dbl_overview.svg "Реестр платежей в разделе «Платежи»") Для выполнения операций по платежам в интерфейсе Dashboard поддерживаются два подхода: - *одиночный* — с указанием параметров непосредственно в интерфейсе Dashboard и с отправкой и выполнением одного запроса на одну операцию; - *массовый* — с указанием параметров через загрузку файла заданного формата и с отправкой и выполнением пакета запросов \(из файла\) на произвольное количество операций. Доступ к разделам **Платежи**, **Ссылки на оплату**и **Мануальные платежи** и к отдельным возможностям по работе с ними регулируется соответствующими правами. Поэтому в случаях, когда какая-либо из описанных возможностей оказывается недоступной, следует проверять наличие требуемых прав у используемой учётной записи.Кроме того, для проведения оплат MO/TO ивыплат требуется использование двухфакторной аутентификации при доступе к интерфейсу Dashboard и может использоваться подтверждение выплат с использованием кодов из SMS-сообщений \([подробнее](ru_dbl_overview.md)\). Далее описан порядок действий, необходимых для контроля и проведения платежей, а также приведены основные сведения о работе с пакетами операций. ## Контроль проведения платежей {#ru_dbl_payments_control} Интерфейс Dashboard позволяет отслеживать информацию о суммах, статусах и других атрибутах проводимых платежей. Для этого можно использовать общий раздел **Платежи** \(с информацией обо всех типах платежей\) и специализированные разделы с информацией об отдельных типах платежей. В каждом из этих разделов используется реестр с типовыми инструментами фильтрации \([подробнее](ru_dbl_interfaces.md)\). Также в разделах **Платежи**, **Мануальные платежи** и **Подписки** доступны карточки с детальной информацией об отдельных платежах и относящихся к ним операциях. Для открытия отдельной карточки достаточно щёлкнуть соответствующую строку платежа в реестре. ![](images/ecommpay/dbl/ru_dbl_payment_details.svg "Карточка платежа в разделе «Платежи»") Фактически, для контроля информации об интересующих платежах достаточно следующих действий: 1. Перейти в подходящий раздел: **Платежи**, **Ссылки на оплату**, **Мануальные платежи** или **Подписки**. 2. Найти в реестре записи о целевых платежах, используя инструменты фильтрации, если это необходимо. 3. Проверить интересующую информацию непосредственно в реестре или в карточках платежей, если они доступны. Вместе с тем при работе с реестрами следует учитывать ряд особенностей: - Информация в реестрах и карточках отображается с задержкой, которая может составлять до нескольких минут. При этом автоматическое обновление информации не поддерживается, но поддерживается обновление информации в реестре платежей с помощью кнопки ![](images/ecommpay/dbl/ru_icon_refresh.svg), расположенной в левом углу над реестром. - Состав и порядок столбцов в реестрах могут настраиваться, поэтому при наличии соответствующих прав можно оформлять реестры в соответствии с индивидуальными предпочтениями. - Ключевые атрибуты платежей — идентификатор, тип, статус, сумма и валюта — по умолчанию выводятся в первых столбцах реестров, и для этих атрибутов поддерживаются встроенные фильтры на панели фильтрации. При этом состав атрибутов и фильтров различается в зависимости от реестра. - В поле **Сумма** отображается *базовая сумма* платежа, по отношению к которой применим статус этого платежа. Так, если по оплате в 100 EUR был выполнен частичный возврат в 20 EUR, то статус `partially refunded` будет относиться к сумме в 100 EUR, а сумма возврата и оставшиеся средства будут отображаться в полях **Возвращено** и **Доступно для возврата**. Другой пример — регулярная оплата с серией списаний в одном платеже. Для такой оплаты в поле **Сумма** отображается актуальная сумма всех поступивших средств. С любыми вопросами о работе с реестрами можно обращаться к курирующему менеджеру Ecommpay. ## Проведение оплат {#ru_dbl_payments_purchases} ### Общая информация {#ru_dbl_payments_purchases_overview} Интерфейс Dashboard позволяет: - Формировать и отправлять пользователям платёжные ссылки, а также управлять их действительностью — чтобы проводить по таким ссылкам разовые оплатыи регистрировать при этом регулярные \(когда это актуально\). Порядок проведения и возможные статусы оплат по платёжным ссылкам описаны [в модели](ru_platform_invoice_model.md). - Проводить оплаты MO/TO \(Mail Order / Telephone Order\) — с использованием платёжной формы и указанием реквизитов, предоставленных пользователями через электронную почту, телефон или иные средства связи.Такие оплаты проводятся как разовые в соответствии [с моделью](ru_platform_sms_model.md)и [с учётом ограничений](ru_Gate_moto.md). - Управлять списаниями по оплатам в две стадии — с возможностями применения единичной и пакетной отправки запросов для подтверждения списаний заблокированных средств и отмены их блокировки.Порядок проведения и возможные статусы оплат в две стадии описаны [в модели](ru_gate_payment_auth.md). ### Условия {#ru_dbl_payments_purchases_requirements} Для проведения оплат через Dashboard должны соблюдаться следующие условия: - для проведения оплат MO/TO должна применяться двухфакторная аутентификация при доступе к интерфейсу; - у используемой учётной записи должны быть права на выполнение необходимых действий — действия каждого типа, включая подтверждение и отмену списаний, регулируются отдельными правами; - необходимые действия должны поддерживаться дляиспользуемых проекта и платёжного метода. Вопросы, касающиеся распределения прав, можно решать на месте — через специалистов с правами администратора. ### Оплаты по ссылкам {#ru_dbl_payments_purchases_payment_link_purchases} При работе с платёжными ссылками можно проводить разовые оплатыи, если актуально, регистрировать при этом дальнейшие регулярные списания \(в рамках подписок\).Например, это может быть полезным, чтобы пользователь в удобное ему время, используя ссылку, мог оплатить билет на самолет или оформить подписку в онлайн-кинотеатре со списанием за первый месяц. ![](images/ecommpay/dbl/ru_dbl_payment_invoice.svg "Указание основных параметров для проведения оплаты") ![](images/ecommpay/dbl/ru_dbl_payment_invoice_booking_info.svg "Указание сведений о бронировании") ![](images/ecommpay/dbl/ru_dbl_payment_subscription_via_invoice.svg "Указание параметров для проведения оплаты с регистрацией подписки") ![](images/ecommpay/dbl/ru_dbl_payment_invoice_complete.svg "Уведомление о создании ссылки") ![](images/ecommpay/dbl/ru_dbl_payment_invoice_registry.svg "Контроль проведения оплаты через реестр ссылок") Чтобы провести разовую оплату с использованием платёжной ссылки\(и регистрацией регулярных списаний, если это актуально\), следует: 1. Открыть вкладку формирования ссылки. Для этого необходимо открыть раздел **Ссылки на оплату**, щёлкнуть кнопку **Новая ссылка на оплату** в левой части панели фильтрации и перейти на вкладку **Разовый платеж**, если актуально только провести оплату, или на вкладку **Подписка**, если актуально провести оплату и зарегистрировать при этом подписку. Также эту вкладку можно открыть в разделе **Подписки** с помощью кнопки **Создать подписку**. 2. Задать параметры оплаты и сформировать ссылку. Для этого необходимо заполнить поля и щёлкнуть кнопку **Создать ссылку на оплату**. При заполнении полей стоит учитывать ряд особенностей: - сумма указывается с отделением дробной части с помощью точки \(например, `314.15`\); - выбор платёжного метода становится доступным после указания идентификатора платежа и проекта; - срок действия ссылки на оплату не должен превышать 30 суток; - если включён переключатель **Отправить e-mail покупателю**, то при формировании платёжной ссылки она автоматически отправляется на указанный адрес электронной почты пользователя, если этот переключатель выключен — ссылку следует отправить пользователю самостоятельно; - если регистрируются дальнейшие регулярные списания, на вкладке **Подписка** необходимо корректно указывать идентификаторы первичного платежа \(в поле **ID платежа**\) и платежа, в рамках которого должны выполняться дальнейшие списания \(в поле **ID рекаррингового платежа**\), — это разные идентификаторы, каждый из которых должен быть уникальным в рамках проекта; - если регистрируются дальнейшие регулярные списания и при этом не указывается дата их окончания, то дата окончания определяется равной сроку действия указанной платёжной карты \(в случае с классической карточной оплатой\) или сроку в 10 лет с последнего дня месяца, в котором регистрируется эта повторяемая оплата \(в случае с любым из других платёжных методов\); - если выбран платёжный метод **Card payments**, **Apple Pay**, **Google Pay** или **Click to Pay** и для проекта настроена обязательность указания дат начала и окончания бронируемой услуги, необходимо указывать эти даты \(это может быть актуально для мерчантов [с кодами категорий](ru_glossary.md) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922; подробнее — у курирующего менеджера Ecommpay\) - если выбран платёжный метод **Card payments**,рекомендуется указать адрес электронной почты — в случае его отсутствия соответствующая информация запрашивается у пользователя на этапе указания им платёжных данных; - в случае некорректного заполнения полей отображаются уведомления об ошибках; - кнопка **Создать ссылку на оплату** становится активной, когда корректно указаны обязательные параметры \(к ним не относятся описание платежа и адрес электронной почты, но эти поля желательно заполнять для минимизации рисков при проведении платежа\). 3. При необходимости отправить пользователю платёжную ссылку. Это может быть актуально, например, если при заполнении формы не была включена автоматическая отправка. В таком случае, чтобы отправить ссылку, её необходимо скопировать в открывшемся окне с помощью кнопки ![](images/universal/dbl/icon_copy.svg) и отправить пользователю. 4. Убедиться, что разовая оплата проведенаи, если актуально, регулярная зарегистрирована. При проведении разовой оплаты можно проверять её статус в реестре платежей или реестре оплат по платёжным ссылкам — этот статус должен принять значение `success`. Полный список возможных статусов для оплат по платёжным ссылкам представлен [в отдельной статье](ru_platform_invoice_model.md). Если оплата дополнительно регистрируется в качестве регулярной, то её статус можно проверять в разных реестрах: в реестре платежей он должен принять значение `scheduled recurring processing`, в реестре оплат по ссылке — `success`, в реестре подписок — `active`. Полный список возможных статусов регулярных оплат представлен [в отдельной статье](ru_platform_sheduled_recurring_model.md). После регистрации регулярной оплаты можно управлять условиями списаний по ней — при наличии соответствующих прав в интерфейсе Dashboard и в соответствии с процедурами, описанными [далее](ru_dbl_payments.md). Если требуется деактивировать платёжную ссылку \(до того, как пользователь произвёл оплату\), следует включить переключатель **Деактивировать** в соответствующей строке реестра в разделе **Ссылки на оплату**.После этого ссылка становится недействительной и не может применяться для проведения оплаты, даже если она была отправлена пользователю. ### Оплаты MO/TO {#ru_dbl_payments_purchases_moto} Чтобы провести оплату MO/TO, следует: 1. Перейти на вкладку **Виртуальный терминал**. Для этого следует открыть раздел **Мануальные платежи**, щёлкнуть кнопку **Запрос** в левой части панели фильтрации и перейти на вкладку **Виртуальный терминал**. 2. Задать параметры оплаты и отправить запрос на открытие платёжной формы. Для этого необходимо заполнить поля и щёлкнуть кнопку **Оплатить**. При заполнении полей стоит учитывать ряд особенностей: - идентификатор платежа должен быть уникальным в рамках указанного проекта; - сумма указывается с отделением дробной части с помощью точки \(например, `314.15`\); - кнопка **Оплатить** становится активной, когда указаны все обязательные параметры. ![](images/ecommpay/dbl/ru_dbl_payment_moto_initiation.svg) 3. В платёжной форме указать необходимые данные и подтвердить готовность провести оплату. Для этого необходимо заполнить поля в открывшейся платёжной форме и щёлкнуть кнопку **Оплатить**. При использовании поля **Страна** необходимо указывать код страны в соответствии со стандартом ISO 3166-1 alpha-2; список таких кодов приведён в разделе [Коды стран](ru_country_codes.md)\). ![](images/ecommpay/dbl/ru_dbl_payment_moto_pp.svg) 4. Убедиться, что оплата проведена. Для этого можно проверить статус этой оплаты в реестре платежей — он должен принять значение `success`. ### Одиночные подтверждения и отмены списаний {#ru_dbl_payments_purchases_single_capture_cancel} Чтобы подтвердить \(отменить\) списание заблокированных средств для отдельной оплаты в две стадии, следует: 1. При необходимости, найти целевую оплату — ту, для которой необходимо подтвердить \(отменить\) списание. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) или перейти в раздел **Платежи** и использовать реестр и фильтры \(например, по типу операции — `auth` или по статусу платежа — `awaiting capture`\). 2. Открыть карточку целевой оплаты. Для этого следует щёлкнуть соответствующую строку в реестре раздела **Платежи**. 3. Отправить запрос на подтверждение \(отмену\) списания заблокированных средств. Для этого следует: 1. Щёлкнуть кнопку **Списание**, чтобы списать заблокированные средства \(**Отмена**, чтобы отменить блокировку средств\), на панели управления платежом \(в левой верхней части карточки платежа\). ![](images/ecommpay/dbl/ru_dbl_payment_capture_cancel.svg) 2. Указать в открывшемся окнетребуемую сумму, которая может составлять полную или частичную сумму заблокированных средств. При изменении суммы заблокированных средств следует учитывать, что такая возможность поддерживается не во всех случаях \(в соответствии с региональными и другими особенностями\) и с учётом ограничений со стороны платёжных систем \(подробнее — в разделе [Оплата в две стадии](ru_gate_payment_auth.md#section_flr_s1g_k3b)\). 3. Подтвердить отправку запроса, щёлкнув кнопку **Списание** \(**Отмена**\). **Прим.:** Если кнопки **Списание** и **Отмена** не активны, это может свидетельствовать о том, что одна из этих операций уже выполняется, а если отсутствуют — о том, что для платежа не поддерживается выполнение таких операций. 4. Убедиться, что операция списания \(отмены\) выполнена. Для этого можно проверить статус операции в карточке целевой оплаты или статус этой оплаты в реестре. Статус операции \(`capture` или `cancel`\) должен принять значение `success`, а статус оплаты — `success` в случае списания и `cancelled` в случае отмены. Если запрос на выполнение операции был отклонён, то статус такой операции принимает значение `decline`, а статус платежа не меняется — остаётся `awaiting capture`. ### Массовые подтверждения и отмены списаний {#ru_dbl_payments_purchases_mass_capture_cancel} Чтобы выполнить групповое списание средств или отмену списания средств с отправкой запросов одним пакетом, следует: 1. Подготовить файл заданного формата с информацией о подтверждениях \(отменах\) списаний по целевым оплатам. Требования к таким файлам представлены [далее](ru_dbl_payments.md). **Прим.:** При подготовке файла необходимо учесть, что в нём должны содержаться операции только одного типа — `capture` или `cancel`, а сумму подтверждения \(отмены\) может составлять как полная, так и частичная сумма заблокированных средств. При изменении суммы заблокированных средств следует учитывать, что такая возможность поддерживается не во всех случаях \(в соответствии с региональными и другими особенностями\) и с учётом ограничений со стороны платёжных систем \(подробнее — в разделе [Оплата в две стадии](ru_gate_payment_auth.md#section_flr_s1g_k3b)\). 2. Перейти на вкладку **Массовые списания** \(**Массовые отмены**\). Для этого следует открыть раздел **Мануальные платежи**, щёлкнуть кнопку **Запрос** в левой части панели фильтрации и перейти на вкладку массовых списаний \(отмен\). 3. Загрузить подготовленный файл со списком операций и убедиться, что он корректен. Для загрузки можно перетащить файл в область загрузки или использовать кнопку **Выберите файл**. Для проверки корректности стоит убедиться в том, что либо стала активной кнопка **Отправить запрос**, либо отобразилось уведомление об ошибках. Во втором случае можно изучить информацию об ошибках \(используя переключатель **Предварительный просмотр** и далее кнопку **Информация о файле**\), скорректировать файл и загрузить его повторно. ![](images/ecommpay/dbl/ru_dbl_payment_capture_batch.svg) 4. Отправить пакет запросов на выполнение. Для этого следует щёлкнуть кнопку **Отправить запрос**. 5. Убедиться в выполнении запросов. Для этого можно контролировать статусы и индикаторы выполнения пакетов и статусы отдельных операций. Состояние пакета можно контролировать через реестр массовых запросов — для этого следует щёлкнуть кнопку **Массовые запросы** на панели фильтрации в разделе **Мануальные платежи**, найти в реестре строку требуемого пакета и проверить статус и индикатор выполнения этого пакета. Стоит учитывать, что время, необходимое для выполнения операций и отображения информации об их статусах, может существенно варьироваться в зависимости от количества запросов в пакете. По итогам выполнения пакета его статус должен принять значение `Done`. Для проверки статусов отдельных операций можно проверять статусы целевых оплат в реестре платежей \(они должны принимать значения `success` при списании средств или `cancelled` при отмене блокировки средств\), а также проверять статусы операций в карточках целевых оплат \(эти статусы должны принимать значение `success` или `decline` в зависимости от результата операции\). ## Управление подписками {#ru_dbl_payments_subscriptions} ### Общая информация {#ru_dbl_payments_subscriptions_overview} Наряду с другими типами и категориями платежей платёжная платформа Ecommpay позволяет проводить *регулярные оплаты* — оплаты, в рамках каждой из которых со стороны мерчанта инициируется серия регулярных списаний с пользователя фиксированной суммы по заданному графику. Такие списания автоматически выполняются в платформе, а для пользователей обеспечивают возможность периодической оплаты *подписок* на определённые услуги со стороны мерчанта. Интерфейс Dashboard позволяетрегистрировать регулярные оплаты и управлять их проведением. При этом можно: - задавать и изменять условия серии списаний, - контролировать выполнение списаний, - управлять повторными попытками отдельных списаний при их отклонении, - прекращать списания, когда они становятся неактуальными. Для работы с этими возможностями в интерфейсе Dashboard выделен раздел **Подписки**, доступ к которому регулируется соответствующими правами \([подробнее](ru_dbl_roles_overview.md)\). В этом разделе доступны реестр и карточки платежей с информацией о регулярных оплатах. **Прим.:** В интерфейсе Dashboard для обозначения регулярной оплаты могут использоваться термины *подписка*, *рекарринговый платёж* и *регулярный платёж* — как синонимы. Информация о любой регулярной оплате отображается вреестре подписок после регистрации этой оплаты в платёжной платформе, при этом используются следующие статусы: - **Not set** — для регулярных оплат, по которым не заданы условия автоматических списаний и эти списания не выполняются\(в таких случаях в карточках этих оплат отображаются предупреждения о том, что необходимо задать условия списаний\). - **Active** — для действующих регулярных оплат, по которымзаданы условия автоматических списаний и эти списания выполняются по заданному расписанию. - **Cancelled** — для регулярных оплат, в рамках которых отменены дальнейшие списания. ![](images/ecommpay/dbl/ru_dbl_subscription.svg "Карточка подписки") Каждая карточка регулярной оплаты содержит группу панелей, в том числе общую панель управления платежом, панель **Регистрационный платёж**с информацией о платеже, в рамках которого была зарегистрирована регулярная оплата, и панель **Рекарринговый платёж**с информацией об операциях в рамках регулярной оплаты. Для перехода к информации о любой из операций, относящихся к регулярной оплате, достаточно щёлкнуть её строку на соответствующей панели. Также через карточку подписки можно управлять условиями регулярной оплаты, прекращать дальнейшие списания по ней и просматривать историю изменений— при наличии соответствующих прав на панели управления платежом становятся доступными кнопки для выполнения таких действий. Порядок таких действий описан далее. ### Регистрация подписок {#ru_dbl_payments_subscriptions_creating} Платёжная платформа Ecommpay позволяет регистрировать регулярные оплаты с автоматическими списаниями разными способами, в том числе при проведении платежей через Payment Page \([подробнее](ru_pp_recurring.md)\)и Gate \([подробнее](ru_gate_payment_recurring_registration.md)\), а также при переносе информации о повторяемых оплатах от других эквайеров \([подробнее](ru_gate_data_migration.md)\). При работе с интерфейсом Dashboardрегистрировать регулярные оплаты можнос помощью платёжных ссылок, указывая соответствующую информацию при их создании \([подробнее](ru_dbl_payments.md)\). ### Указание условий {#ru_dbl_payments_subscriptions_updating} Чтобы задать или изменить условия регулярной оплаты, следует: 1. Открыть карточку целевой регулярной оплаты. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) или перейти в раздел **Подписки** и использовать реестр и фильтры. 2. Перейти к редактированию свойств оплаты. Для этого необходимо щёлкнуть кнопку **Перейти в настройки** на панели управления платежом и затем кнопку **Редактировать** в нижней части открывшегося модального окна **Настройки подписки**. 3. Задать целевые параметры. Для этого необходимо заполнить соответствующие поля и щёлкнуть кнопку **Сохранить**. При заполнении полей стоит учитыватьряд особенностей: - Если при регистрации регулярной оплаты не был задан её идентификатор, поле **ID рекаррингового платежа** является обязательным для заполнения. Если идентификатор уже задан, это поле недоступно для редактирования. - Поля для указания суммы списания, периодичности регулярной оплаты и даты следующего списания являются обязательными для заполнения. Если хотя бы одно из этих полей не заполнено, при попытке сохранить внесённые в карточку изменения появляется сообщение об ошибке. - Дата следующего списания не может предшествовать текущей дате, а также быть позже даты окончания действия регулярной оплаты. - Поля **Валюта платежа** и **Дата окончания подписки** недоступны для редактирования. Валюта списаний всегда соответствует валюте регистрационного платежа, а дата завершения подписки, если она не была указана в запросе на проведение регистрационного платежа, устанавливается согласно используемым в платформе правилам. Прекратить списания по подписке до завершения её срока можно через карточку подписки \([подробнее](ru_dbl_payments.md)\). Изменить срок действия подписки можно через соответствующую конечную точку Gate API \([подробнее](ru_gate_payment_recurring_manage.md#section_lpp_df2_5jb)\). - Поля **Каждый\(е\)** \(для указания множителя к периоду списаний\) и **Описание** не являются обязательными. При необходимости можно отказаться от внесения изменений, используя кнопку **Отменить**. 4. Убедиться, что изменения были сохранены. Для этого можно проверить наличие соответствующей информации в реестре записей об изменениях условий подписки\(щёлкнув кнопку **История настроек** на панели управления платежом\). ![](images/ecommpay/dbl/ru_dbl_subscription_edit.svg) ### Управление повторными попытками списаний {#ru_dbl_payments_subscriptions_retry} #### Общая информация {#section_x3y_r1f_gzb .section} При выполнении очередного списания в рамках повторяемой оплаты, как правило, достаточно одной попытки. Но в некоторых случаях, например при недостатке средств на счёте пользователя, могут быть уместны дополнительные попытки спустя определённое время. Для работы с такими ситуациями в платёжной платформе Ecommpay предусмотрена возможность автоматически инициировать повторные попытки списаний в рамках повторяемых оплат \(общая схема работы с такими попытками списаний представлена [в отдельной статье](ru_gate_cof_retry_attempts.md)\). Такая возможность подключается по согласованию с курирующим менеджером Ecommpay и позволяетзадавать для каждого проекта отдельный график повторных попыток списаний \(действительный для каждой регулярной оплаты в рамках этого проекта\), а также контролировать и отменять выполнение отдельных повторных попыток. Если возможность работать с повторными попытками списаний подключена для используемого проекта, информация об этих попытках отображается в карточках подписок интерфейса Dashboard. Для этого в карточках предусмотрены два режима работы, которые переключаются с помощью кнопки **Показать повторные попытки** \(**Вернуться к основной операции**\). ![](images/ecommpay/dbl/ru_dbl_temp_operation.svg "Работа со списанием") ![](images/ecommpay/dbl/ru_dbl_temp_retry.svg "Работа с повторной попыткой") Наполнение панелей в этих режимах варьируется следующим образом. |Панель|для списаний|для повторных попыток| |------|------------|---------------------| |1. Панель со списком всех действий|содержит список списаний и возвратов по отдельной регулярной оплате \(при этом для каждого списания отображается его статус и может отображаться статус выполнения повторных попыток этого списания\) |содержит список повторных попыток отдельного списания \(при этом для каждой попытки отображаются её статус и признак `retry operation`\) | |2. Панель управления отдельным действием|содержит информацию об отдельном списании\(включая расширенный комментарий к статусу выполнения его повторных попыток\) и кнопкидля перехода к списку повторных попыток, для управления условиями их выполнения и для их отмены |содержит информацию об отдельной повторной попытке \(включая признак `retry operation`\) и кнопку для возвращения к списку остальных операцийповторяемой оплаты | |3. Панель с информацией об отдельном действии|содержит детализированную информацию об отдельной повторной попытке|содержит детализированную информацию об отдельной повторной попытке| Статусы повторных попыток списаний могут принимать следующие значения: - `retries active` — в платформе запланирована повторная попытка\(при отклонении очередного списания на стороне платёжной системы или эмитента\); - `retry in progress` — повторная попытка выполняется; - `retries successful` — одна из повторных попыток привела к переводу средствот пользователя к мерчанту; - `retries unsuccessful` — все доступные повторные попытки были отклонены; - `retries cancelled` — дальнейшие повторные попытки отменены\(по запросу мерчанта или автоматически, с учётом изменения свойств повторяемой оплаты или иных факторов\). #### Настройка графика попыток {#section_qbr_422_phc .section} Платёжная платформа позволяет использоватьдля всех регулярных оплат в рамках одного проекта один общий график повторных попыток списаний. Это может быть базовый графикот Ecommpay, используемый в платёжной платформе по умолчанию, или индивидуальныйграфик, настроенный со стороны мерчантас учётом специфики конкретного проекта. График любого проекта можно менять, настраивая индивидуальные параметры или сбрасывая их значения к базовым. При этом стоит учитывать, что каждая повторная попытка, которая относится к целевому проекту ибыла запланирована при отклонении исходной или очередной попытки списаниядо изменения графика, выполняется согласно запланированным дате и времени\(по предыдущему графику\), но если какая-либо из таких попыток отклоняется уже после изменения графика и в платёжной платформе подтверждается возможность выполнить следующую попытку этого списания, то новая попытка планируется и выполняется по обновлённому графику.И в любом случае информация о каждой последующей попытке направляется к веб-сервису в оповещении об отклонении очередной попытки списания \([подробнее](ru_gate_cof_retry_attempts.md)\). Чтобы внести изменения в график повторных попыток списаний по подпискам конкретного проекта, следует: 1. Открыть в карточке целевого проекта вкладку с параметрами повторных попыток списаний по подпискам. Для этого можно перейти в раздел **Проекты**, выбрать в выпадающем списке **Ваши проекты** целевой проект и перейти на вкладку **Настройки повторных попыток подписок**. \(Также можно перейти к этой вкладке непосредственно из раздела **Подписки** с помощью кнопки **Настроить параметры повторных попыток** и проверить, что в выпадающем списке выбран необходимый проект.\) 2. Задать целевой график выполнения попыток. Для использования графика по умолчанию необходимо выбрать вариант **Стандартный график повторных попыток подписок**. Для использования индивидуального графика необходимо выбрать вариант **Индивидуальный график повторных попыток по подпискам** и указать дни выполнения повторных попыток для каждого отклонённого списания, активировав кнопки с порядковыми номерами соответствующих дней. При этом можно задать от одной до десяти повторных попыток с минимальным интервалом между ними в 24 часа. 3. Сохранить изменения, щёлкнув кнопку **Сохранить**. **Прим.:** Стоит учитывать, что изменения применяются в платформе по щелчку кнопки **Сохранить** — без подтверждения этого действия. 4. Убедиться, что обновлённый график сохранён. Для этого можно повторно открыть вкладку со свойствами целевого проекта и проверить график списаний, используемый для этого проекта. ![](images/ecommpay/dbl/ru_dbl_payments_custom_subscription_schedule.svg "Настройка графика повторных попыток") #### Контроль попыток {#section_dny_w1f_gzb .section} Интерфейс Dashboard позволяет контролировать информацию о выполнении повторных попыток в рамках регулярных списаний. Для этогов реестрах платежей доступны карточки повторяемых оплат с информацией об относящихся к ним списаниям и повторным попыткам конкретных списаний\([подробнее](ru_dbl_payments.md#section_x3y_r1f_gzb)\). Чтобы получить информацию о повторных попытках конкретного списания, следует: 1. Открыть карточку целевой регулярной оплаты. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) либо перейти в раздел **Подписки** или **Платежи** и использовать реестр и фильтры. 2. Перейти к информации о целевом списании. Для этого необходимо выбрать соответствующий элемент на панели со списком операций в левой части карточки подписки. 3. Открыть список повторных попыток целевого списания. Для этого необходимо щёлкнуть кнопку **Показать повторные попытки** на панели управления отдельным списанием. 4. Перейти к детальной информации о целевой повторной попытке. Для этого необходимо выбрать соответствующий элемент на панели со списком повторных попыток в левой части карточки подписки. 5. При необходимости, вернуться к списку остальных списаний. Для этого следует щёлкнуть кнопку **Вернуться к основной операции** на панели управления отдельной повторной попыткой или щёлкнуть кнопку ![](images/universal/dbl/icon_back.svg) в верхнем правом углу панели со списком повторных попыток. #### Отмена дальнейших попыток {#section_tcz_fbf_gzb .section} При необходимости можно отменять выполнение дальнейших повторных попыток в рамках отдельного списания. Для этогоследует: 1. Открыть карточку целевой регулярной оплаты. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) либо перейти в раздел **Подписки** или **Платежи** и использовать реестр и фильтры. 2. Перейти к информации о целевом списании. Для этого необходимо выбрать соответствующий элемент на панели со списком операций в левой части карточки подписки. 3. Отменить выполнение повторных попыток. Для этого необходимо щёлкнуть кнопку **Отменить повторные попытки** на панели управления списанием и подтвердить отмену. 4. Убедиться, что выполнение дальнейших попыток отменено. Для этого необходимо проверить их статус в строке списания на панели с операциями повторяемой оплаты — он должен измениться с `active` на `retries cancelled`. ### Прекращение списаний {#ru_dbl_payments_subscriptions_cancelling} Чтобы прекратить дальнейшее выполнение списаний в рамках действующей регулярной оплаты, следует: 1. Открыть карточку целевой регулярной оплаты. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) или перейти в раздел **Подписки** и использовать реестр и фильтры. 2. Перейти к свойствам оплаты и инициировать прекращение списаний. Для этого необходимо щёлкнуть кнопку **Перейти в настройки** на панели управления платежом и затем кнопку **Отменить подписку** в левой верхней части открывшегося модального окна **Настройки подписки**. 3. Подтвердить прекращение списаний в появившемся модальном окне. 4. Убедиться в отмене дальнейших списаний. Для этого можно проверить наличие соответствующей информации в реестре записей об изменениях условий подписки \(щёлкнув кнопку **История настроек** на панели управления платежом\), а также изменение статуса на `Cancelled` в реестре подписок. ![](images/ecommpay/dbl/ru_dbl_subscription_history.svg) ## Выполнение возвратов {#ru_dbl_payments_refunds} ### Условия {#section_vvh_kdx_31c .section} Dashboard позволяет выполнять возвраты на полную и частичную сумму оплат любого типа, в том числе по отдельным списаниям в рамках повторяемых оплат. При этом может использоваться единичная и пакетная отправка запросов и в любом случае должны соблюдаться следующие условия: - у используемой учётной записи должно быть право на выполнение возвратов; - оплата \(отдельное списание повторяемой оплаты\), по которой требуется выполнить возврат, должна быть проведена; - для платёжного метода, с использованием которого была проведена оплата, должны поддерживаться возвраты требуемого типа; - на балансе, по которому была проведена оплата, должно быть достаточно средств для выполнения возврата. Вопросы, касающиеся соблюдения этих условий, можно решать на месте — со специалистами, отвечающими за распределение прав и работу с балансами. ### Одиночные возвраты {#section_cs1_ldx_31c .section} В интерфейсе Dashboard одиночные возвраты \(полные и частичные, для оплат любого типа\) можно выполнять как из реестра платежей, так и из карточек отдельных оплат \(например, если требуется выполнить возврат по конкретной операции повторяемой оплаты\). ![](images/ecommpay/dbl/ru_dbl_refund_in_registry.svg "Инициирование возврата из реестра платежей") ![](images/ecommpay/dbl/ru_dbl_payment_refund.svg "Инициирование возврата из карточки оплаты") Чтобы выполнить одиночный возврат, следует: 1. При необходимости, найти целевую оплату— ту, для которой требуется выполнить возврат. Для этого можно воспользоваться поиском \(например, по идентификатору платежа\) или перейти в раздел **Платежи** и использовать реестр и фильтры \(например, по типу платежа — `purchase`, `recurring`, `invoice` или `account verification`\). 2. Открыть окно инициирования возврата. Для этого можно щёлкнуть кнопку ![](images/universal/dbl/icon_refund.svg) в соответствующей строке реестра платежей или открыть карточку платежа и щёлкнуть кнопку **Возврат**, расположенную на панели управления платежом или на панели информации об отдельной операции повторяемой оплаты. **Прим.:** Если кнопка **Возврат** не активна, это может свидетельствовать о том, что оплата ещё не проведена, а если отсутствует — о том, что для используемого платёжного метода не поддерживается выполнение возвратов \(в таких случаях можно обращаться за консультацией к курирующему менеджеру Ecommpay\). 3. Инициировать выполнение возврата. Для этого необходимо указать в открывшемся окне требуемую сумму возврата — полную доступную или её часть \(сумма, доступная для возврата, отображается в этом же окне\) и щёлкнуть кнопку **Возврат**. **Прим.:** Стоит учитывать, что по щелчку кнопки **Возврат** в платформе инициируется выполнение возврата — без подтверждения этого действия. 4. Убедиться, что возврат выполнен. Статус операции возврата \(`refund`\) можно проверить в карточке платежа \(он должен принять значение `success`\) или через статус платежа в реестре платежей \(при возврате полной суммы он должен принять значение `refunded` или `reversed`, а при возврате частичной суммы — `partially refunded`\). Если возврат был отклонён, то статус операции принимает значение `decline`, а статус платежа не меняется. Это может быть вызвано разными причинами. И, например, в случае отклонения операции из-за того, что на балансе оказалось недостаточно средств, можно пополнить баланс и повторить попытку возврата. ### Массовые возвраты {#section_uyq_ldx_31c .section} Чтобы выполнить группу возвратов с отправкой запросов одним пакетом \(массовый возврат\), следует: 1. Подготовить файл заданного формата с информацией о целевых возвратах. Требования к таким файлам представлены [далее](ru_dbl_payments.md), вместе с шаблоном и примером заполнения. **Прим.:** При подготовке файла необходимо учитывать, что для выполнения возврата на оплату в поле `general.payment_id` должен быть указан её идентификатор, а для возврата на отдельную операцию в рамках повторяемой оплаты дополнительно в поле `general.operation_id` должен быть указан идентификатор этой операции. 2. Перейти на вкладку **Массовые возвраты**. Для этого следует открыть раздел **Мануальные платежи**, щёлкнуть кнопку **Запрос** в левой части панели фильтрации и перейти на вкладку массовых возвратов. 3. Загрузить подготовленный файл и убедиться, что он корректен. Для загрузки можно перетащить файл в область загрузки или использовать кнопку **Выберите файл**. Для проверки корректности стоит убедиться в том, что либо стала активной кнопка **Отправить запрос**, либо отобразилось уведомление об ошибках. Во втором случае можно изучить информацию об ошибках \(используя переключатель **Предварительный просмотр** и далее кнопку **Информация о файле\)**, скорректировать файл и загрузить его повторно. ![](images/ecommpay/dbl/ru_dbl_mass_refund.svg) 4. Отправить пакет запросов на выполнение, щёлкнув кнопку **Отправить запрос**. 5. Убедиться в выполнении запросов. При отправке запросов в интерфейсе отображается сообщение об их приёме, после чего можно убедиться в выполнении возвратов, проверив статус пакета в реестре массовых запросов — он должен принять значение `Done` \(для этого следует щёлкнуть кнопку **Массовые запросы** на панели фильтрации в разделе **Мануальные платежи** и найти в реестре строку требуемого пакета\). В этом реестре дополнительно можно ориентироваться на статусы отдельных возвратов с помощью элементов **Indicator**. Стоит учитывать, что время, необходимое для выполнения возвратов и отображения информации об их статусах, может существенно варьироваться в зависимости от количества запросов в пакете. Для проверки статусов отдельных возвратов можно проверять статусы целевых оплат в реестре платежей \(они должны принимать значения `refunded` или `reversed` при возврате полной суммы и `partially refunded` при возврате частичной суммы\), а также проверять статусы возвратов в карточках целевых оплат \(эти статусы должны принимать значение `success` или `decline` в зависимости от результата операции\). ![](images/ecommpay/dbl/ru_dbl_payment_mass_refund.svg) С любыми вопросами о выполнении возвратов можно обращаться к специалистам технической поддержки Ecommpay. ## Проведение выплат {#ru_dbl_payments_payouts} ### Условия {#ru_dbl_payments_payouts_overview} Dashboard позволяет проводить выплаты с использованием единичной и пакетной отправки запросов, и в любом из этих случаев должны соблюдаться следующие условия: - доступ к интерфейсу Dashboard для используемой учётной записи должен осуществляться с применением двухфакторной аутентификации; - у используемой учётной записи должно быть право на проведение выплат; - для выбранного платёжного метода должно поддерживаться проведение выплат; - на балансе, с использованием которого необходимо провести выплаты, должно быть достаточно средств; - если для проведения выплаты требуются дополнительные данные, они могут быть предоставлены не более чем в течение 22 часов. Вопросы, касающиеся соблюдения этих условий, можно решать на месте — со специалистами, отвечающими за распределение прав и работу с балансами. ### Одиночные выплаты {#ru_dbl_payments_payouts_single} Чтобы провести одиночную выплату, следует: 1. Перейти на вкладку **Одиночная выплата**. Для этого необходимо открыть раздел **Мануальные платежи**, щёлкнуть кнопку **Запрос** в левой части панели фильтрации. 2. Задать параметры выплаты и отправить запрос. Для этого необходимо заполнить поля, щёлкнуть кнопку **Отправить запрос**и в отдельных случаях подтвердить отправку запроса, введя в появившемся окне код из SMS-сообщения. При заполнении полей стоит учитывать ряд особенностей: - сумма указывается с отделением дробной части с помощью точки \(например, `314.15`\); - поля для специфических параметров разных платёжных методов отображаются после указания проекта, суммы, валюты и платёжного метода; - в числе специфических полей отображаются только обязательные для заполнения; - в случае некорректного заполнения полей отображаются уведомления об ошибках; - кнопка **Отправить запрос** становится активной, когда корректно указаны все параметры. ![](images/ecommpay/dbl/ru_dbl_payment_payout.svg) 3. Если требуется дополнить информацию о платеже — указать дополнительные параметры \(также можно отклонить платёж\). При проведении выплаты выполняются проверки её параметров, при этом в интерфейсе, на вкладке **Одиночная выплата**, отображается соответствующее сообщение. Если по итогам таких проверок параметры удовлетворяют предъявляемым условиям, то в интерфейсе отображается сообщение об успешной обработке запроса; если же выявляется, что отсутствуют какие-либо параметры, которые не обязательны в общем случае, но необходимы в конкретной ситуации, в интерфейсе отображаются поля для указания этих параметров. В таком случае можно продолжить платёж, указав необходимые данные и щёлкнув кнопку **Продолжить**, либо отклонить проведение платежа, щёлкнув кнопку **Отклонить выплату**. Если по каким-либо причинам \(например, для уточнения информации\) требуется прервать работу и вернуться к выплате позже, найти эту выплату можно в реестре выплат, отфильтровав записи с помощью фильтра **Clarification** и щёлкнув соответствующую строку. **Прим.:** По умолчанию время для дополнения информации составляет 22 часа с момента выявления необходимости дополнить данные, но для некоторых платёжных систем это время может быть меньшим. За уточнениями о работе с конкретными методами можно обращаться к сотрудникам технической поддержки Ecommpay. ![](images/ecommpay/dbl/ru_dbl_payment_payout_clarification.svg) 4. Убедиться, что выплата проведена. Для этого можно проверить статус этой выплаты в реестре выплат или платежей — он должен принять значение `success`. Если выплата была отклонена, её статус принимает значение `decline`. Это может быть вызвано разными причинами. И, например, в случае отказа из-за того, что на балансе оказалось недостаточно средств, можно пополнить баланс и повторить попытку выплаты. ### Массовые выплаты {#ru_dbl_payments_payouts_mass} #### Основная процедура {#section_xjl_fy3_vnb .section} Чтобы провести группу выплат с отправкой запросов одним пакетом \(массовую выплату\), следует: 1. Подготовить файл заданного формата с информацией о целевых выплатах. Требования к таким файлам представлены [далее](ru_dbl_payments.md), вместе с шаблоном и примером заполнения. 2. Перейти на вкладку **Массовые выплаты**. Для этого необходимо открыть раздел **Мануальные платежи**, щёлкнуть кнопку **Запрос** в левой части панели фильтрации и перейти на вкладку массовых выплат. 3. Загрузить подготовленный файл со списком выплат и отправить пакет запросов на выполнение. Для загрузки можно перетащить файл в область загрузки или использовать кнопку **Выберите файл**.После загрузки файла необходимо убедиться в том, что кнопка **Отправить запрос** стала активной, щёлкнуть еёи в отдельных случаях подтвердить отправку, введя в появившемся окне код из SMS-сообщения. Если файл некорректен, кнопка **Отправить запрос** не становится активной и отображается сообщение об ошибках. В такой ситуации можно изучить информацию о них \(используя переключатель **Предварительный просмотр** и далее кнопку **Информация о файле\)**, скорректировать файл и загрузить его повторно. ![](images/ecommpay/dbl/ru_dbl_mass_payout.svg) 4. Убедиться в достаточности данных и проведении выплат. При отправке запросов в интерфейсе отображается сообщение об их приёме, после чего важно убедиться в проведении выплат, проверив статус пакета в реестре массовых запросов — он должен принять значение `Done`. Стоит учитывать, что время, необходимое для проведения выплат и отображения информации об их статусах, может существенно варьироваться в зависимости от количества выплат в пакетеи используемых платёжных методов. Если в результате обработки запросов хотя бы для одной из выплат пакета требуется дополнительная информация, то статус пакета принимает значение `Clarification`. В такой ситуации можно указать для отдельных выплат дополнительные параметры либо отклонить их проведение. Информация об этих действиях описана далее. Также при работе с реестром массовых запросов дополнительно можно ориентироваться на статусы отдельных выплат с помощью элементов **Indicator**. ![](images/ecommpay/dbl/ru_dbl_payment_mass_refund.svg) #### Дополнение информации {#section_opk_mwj_zsb .section} При проведении пакета выплат выполняются проверки параметров каждой выплаты. По итогам таких проверок для выплат, параметры которых удовлетворяют предъявляемым условиям, не требуется никаких дополнительных действий, а для выплат с параметрами, которые не обязательны в общем случае, но необходимы и отсутствуют в конкретной ситуации, ожидается дополнение информации, о чём свидетельствует статус `Clarification` для отдельных выплат и всего пакета в реестре массовых запросов. Если для каких-либо выплат в пакете ожидается дополнение информации, можно выборочно указать дополнительные параметры или отклонить выплаты. При этом в таких случаях можно работать с отдельными выплатами \(что может быть удобным, например, когда требуется предоставить данные только об одной из выплат пакета\) или одновременно с несколькими \(например, если необходимо дополнить информацию сразу по нескольким выплатам\) — дополняя информацию непосредственно в интерфейсе Dashboard или в файле. *Для дополнения информации об отдельной выплате* следует: 1. Открыть карточку целевой выплаты. Для этого можно отфильтровать записи в реестре **Все запросы** с помощью фильтра **Clarification** и щёлкнуть нужную строку. 2. Указать запрашиваемые данные и продолжить платёж, щёлкнув кнопку **Продолжить**. Также через карточку выплаты можно отклонить её проведение, используя кнопку **Reject Payout**. *Для дополнения информации о группе выплат* следует: 1. Найти и открыть пакет, к которому относятся целевые выплаты — те, значения параметров которых необходимо указать. Для этого можно отфильтровать записи в реестре **Массовые запросы** с помощью фильтра **Clarification** и щёлкнуть нужную строку. 2. Активировать режим редактирования данных, щёлкнув кнопку **Manage** в левой части панели фильтрации. 3. Указать требуемые параметры. Это можно сделать непосредственно через интерфейс Dashboard, введя данные в ячейки со значком ![](images/universal/dbl/icon_pencil.svg), либо через обновление файла. Во втором случае необходимо выгрузить файл, используя кнопку ![](images/universal/dbl/icon_file_download.svg), указать в этом файле требуемые параметры в ячейках со значением `*required*` и загрузить дополненный файл, используя кнопку ![](images/universal/dbl/icon_file_upload.svg). В каждом из этих случаев можно дополнять данные не по всем выплатам, а только по необходимым. Остальные в таком случае будут отклонены по истечении времени ожидания данных. **Прим.:** По умолчанию время для дополнения информации составляет 22 часа с момента выявления необходимости дополнить данные, но для некоторых платёжных систем это время может быть меньшим.За уточнениями о работе с конкретными системами можно обратиться к сотрудникам технической поддержки Ecommpay. ![](images/ecommpay/dbl/ru_dbl_masspayouts_clarification.svg) 4. Сохранить изменения и отправить данные, щёлкнув кнопку **Продолжить**. Также в режиме редактирования можно отклонить проведение отдельных выплат, установив флажки в соответствующих строках \(в первом столбце таблицы\) и щёлкнув кнопку **Отклонить**. С любыми вопросами о проведении выплат можно обращаться к специалистам технической поддержки Ecommpay. ## Сведения о массовых платежах {#ru_dbl_payments_mass_info} ### Требования к файлам {#ru_dbl_payments_mass_info_requirements} Для подготовки файла массовых платежей можно использовать шаблон, доступный для скачивания в интерфейсе Dashboard на вкладке массового добавления или [по ссылке](files_for_downloads/dashboard/TemplateMassPayments.csv).После загрузки шаблона его можно заполнить в любом редакторе файлов формата CSV, например, MS Excel. При этом каждый файл должен удовлетворять следующим требованиям: - Должен использоваться формат CSV с кодировкой символов UTF-8 без использования маркеров очерёдности \(Byte Order Mark, BOM\). - Размер файла не должен превышать 128 MБ. - Первая строка должна содержать названия параметров, при этом названия могут указываться в любой последовательности. - Последующие строки должны содержать значения целевых параметров, при этом для необязательных параметров значения могут не указываться. - Все указываемые значения параметров в файле должны удовлетворять требованиям, представленным далее [в таблице](ru_dbl_payments.md#table_hjc_x41_xlb). - В случае, если названия и значения параметров операций задаются текстовыми строками \(не в формате таблицы\), в качестве разделителя значений параметров используется «;» \(точка с запятой\), при этом поля без значений разделяются точкой с запятой так же, как и поля со значениями и допускаются ситуации с идущими подряд двумя и более знаками «;», например: ![](images/universal/dbl/ru_dbl_file_data_as_string.png) В случае подготовки файла с разделителем «;» в программе Microsoft Excel рекомендуется выполнять проверку в другом редакторе, например в «Блокноте». ### Используемые параметры {#ru_dbl_payments_mass_info_parameters} При заполнении данных в файлах массовых платежей могут использоваться следующие параметры. |Параметр|Описание| |:-------|--------| |operation\_type string, required |Тип операции: `capture`  \(подтверждение списания заблокированных средств\), `cancel` \(отмена блокировки средств\), `refund` \(возврат\) и `payout` \(выплата\). Пример: `refund` | |general.project\_id integer, required |Идентификатор проекта, полученный от Ecommpay при интеграции. Пример: `35` | |method string, required |Код платёжного метода для проведения платежа.Список этих кодов представлен в разделе [Коды платёжных методов](ru_pm_codes.md). Пример: `card` | |general.payment\_id string, required \* |Идентификатор платежа, уникальный в рамках проекта. Представляет собой строку длиной от 1 до 255 символов из любых букв, цифр или символов в кодировке UTF-8. Пример: `payment_536231`. \* Для возврата необходимо указывать идентификатор той оплаты, по которой требуется выполнить этот возврат | |general.operation\_id string, required \* |Идентификатор операции, полученный от Ecommpay. Представляет собой строку длиной от 1 до 255 символов из любых цифр в кодировке UTF-8. Пример: `54214536231`. \* Для возврата на конкретную операцию повторяемой оплаты, необходимо указывать идентификатор этой операции | |payment.amount integer, required |Сумма платежа в дробных единицах валюты. Представляет собой число в диапазоне от `1` до `10000000000000` без разделителя между целой и дробной частями. Пример: `1905` для суммы 19,05 и `190500` для суммы 1905 | |payment.currency string, required |Код валюты платежа в формате ISO 4217 alpha-3. Пример: `EUR` | |payment.description string, optional \* |Описание платежа. Представляет собой строку длиной не более 255 символов. Пример: `Deposit 12456`. \* Этот параметр обязателен для возвратов | |account.number string, optional |Номер счёта пользователя веб-сервиса мерчанта. Представляет собой строку длиной от 1 до 100 символов. Пример: `1670033323` | |account.bank\_id integer, optional |Идентификатор банка, заданный в платёжной платформе Ecommpay. Информацию о банках и их идентификаторах можно получить в описании платёжных методов в технической документации и у специалистов технической поддержки Ecommpay. Представляет собой число не менее `1`. Пример: `421` | |account.customer\_name string, optional |Полное имя владельца банковского счёта. Представляет собой строку длиной не менее 1 символа. Пример: `John Johnson` | |account.branch string, optional |Наименование филиала банка, в котором открыт счёт пользователя веб-сервиса мерчанта. Представляет собой строку длиной не более 255 символов Пример: `Bank branch` | |account.city string, optional |Название города, в котором расположен филиал. Представляет собой строку длиной не более 255 символов. Пример: `London` | |account.region\_id integer, optional |Идентификатор региона или штата расположения филиала банка, заданный в платёжной платформе Ecommpay.Информацию о регионах и их идентификаторах можно получить в описании платёжных методов в технической документации и у специалистов технической поддержки Ecommpay. Представляет собой число не менее `1`. Пример: `3` | |card.pan integer, optional \* |Номер карты пользователя веб-сервиса мерчанта. Представляет собой число длиной не более 32 цифр. Пример: `2333776109871312`. \* Этот параметр обязателен для выплат по номеру карты | |card.year integer, optional \* |Год истечения действия карты пользователя веб-сервиса. Представляет собой число в диапазоне от `2020` до `9999`. Пример: `2024`. \* Этот параметр является обязательным для выплат | |card.month integer, optional \* |Порядковый номер месяца, в котором истекает срок действия карты пользователя веб-сервиса. Представляет собой число в диапазоне от `1` до `12`. Пример: `12`. \* Этот параметр является обязательным для выплат | |card.card\_holder string, optional \* |Имя держателя карты. Представляет собой строку длиной не более 255 символов. Пример: `John Johnson`. \* Этот параметр является обязательным для выплат | |token string, optional \* |Токен платежного инструмента, полученный от Ecommpay. Пример: `Z0yTL5shY8ddhpxdQyplRPJYmGV7Kv`. \* Этот параметр обязателен для выплат по токену | |customer.id string, optional \* |Идентификатор пользователя веб-сервиса в рамках проекта мерчанта. Представляет собой строку длиной не более 255 символов. Пример: `customer313`. \* Этот параметр является обязательным для выплат | |customer.country string, optional \* |Код страны проживания пользователя веб-сервиса в формате ISO 3166-1 alpha-2. Пример: `GB`. \* Этот параметр является обязательным для выплат | |customer.city string, optional \* |Название города проживания пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `London`. \* Этот параметр является обязательным для выплат | |customer.state string, optional |Название региона \(штата\) расчётного адреса пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `West Midlands` | |customer.zip string, optional |Почтовый индекс расчётного адреса пользователя веб-сервиса. Представляет собой строку длиной не более 10 символов. Пример: `B152SA` | |customer.street string, optional |Название улицы расчётного адреса пользователя веб-сервиса. Пример: `Edgbaston` | |customer.first\_name string, optional \* |Имя пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `John`. \* Этот параметр является обязательным для выплат | |customer.last\_name string, optional \* |Фамилия пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `Johnson`. \* Этот параметр является обязательным для выплат | |customer.day\_of\_birth string, optional \* |Дата рождения пользователя веб-сервиса, в формате `ДД-ММ-ГГГГ`. Пример: `21-12-1989`. \* Этот параметр является обязательным для выплат | |customer.phone string, optional |Номер телефона пользователя веб-сервиса. Представляет собой строку, состоящую из цифр, длиной от 4 до 24 символов и допускает использование символа «+» в начале строки. Пример: `79105216601` | |customer.email string, optional |Адрес электронной почты пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `test@mail.com` | |customer.ip\_address string, optional \* |Используемый IP-адрес пользователя веб-сервиса. Представляет собой строку длиной не более 255 символов. Пример: `127.0.0.1`. \* Этот параметр является обязательным для выплат | ### Возможные ошибки {#ru_dbl_payments_mass_info_errors} При проверке файлов, загружаемых через Dashboard, используются следующие сообщения об ошибках. |Сообщение|Причина| |---------|-------| |File is empty|Файл пуст| |Columns are duplicated|Параметр указан более одного раза| |File does not contain required columns|Пропущены обязательные параметры| |Incorrect file format|Некорректное расширение или формат файла| |File is broken|Некорректная кодировка или структура данных| |Payment method is not available \(line\# number\)|Указан недоступный платёжный метод| |Specified project\_id does not belong to specified merchant account|Указан некорректный идентификатор проекта| |Project\_id is not numeric \(line\# number\)|Указан нечисловой идентификатор проекта| |Project\_id does not exist \(line\# number\)|Указан несуществующий идентификатор проекта| |Payment\_id is empty \(line\# number\)|Не указан идентификатор платежа| |Payment with payment\_id already exists \(line\# number\)|Указан уже зарегистрированный идентификатор платежа| |Amount is empty \(line\# number\)|Не указана сумма платежа| |Incorrect Amount \(line\# number\)|Сумма платежа указана некорректно| |Currency is empty \(line\# number\)|Не указана валюта платежа| |Incorrect Currency \(line\# number\)|Валюта платежа указана некорректно| |Invalid date|Срок действия карты не указан или указан некорректно| |Card.year is in past \(line\# number\)|Указанный год действия карты истёк| |Card.month is in past \(line\# number\)|Указанный месяц действия карты истёк| --- # Ведение финансового учёта {#ru_dbl_balances} статья о балансах для работы с платформой и особенностях работы с ними, а также о возможностях контроля балансов, контроля курсов конвертации валют и учёта информации о банковских счетах через интерфейс Dashboard **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Общая информация {#ru_dbl_balances_overview} При работе с интерфейсом Dashboard можно контролировать текущее состояние балансов, получать информацию о применённых курсах конвертации валют и вести учёт актуальных банковских счетов для перевода средств с балансов. Для этого в интерфейсе выделен раздел **Финансы**, доступ к которому регулируется отдельным правом и по умолчанию доступен учётным записям, отнесённым к ролям `Finance` и `Merchant Admin`. При работе с разделом **Финансы** важно учитывать ряд особенностей, касающихся приводимой в нём информации. - *Полнота.* Также важно учитывать, что по умолчанию в интерфейсе доступна информация только о балансах **IN/OUT** и **OUT**, а отображение информации о балансах **IN** следует согласовать с курирующим менеджером Ecommpay. - *Применимость.* Информацию в разделе **Финансы** можно считать ориентировочной и использовать в ознакомительных целях, но её не следует применять для итогового анализа и сверок.Это связано с тем, что при обработке информации о зачислениях и списаниях неизбежно возникают технические и организационные задержки, связанные с взаимодействием между провайдерами платёжных решений, определением итоговых комиссий и прочими процедурами, а в Dashboard отображается вся имеющаяся на конкретный момент информация. И эта информация может отличаться от итоговой. - *Актуальность.* Информация о балансах отображается с задержкой, которая может составлять до 30 минут. Это связано с техническими процедурами, включающими в себя различные вычисления, проверки и перенос информации в долговременное хранение. При необходимости получения оперативной информации по конкретным операциям можно использовать карточки платежей, программные оповещения \([подробнее](ru_platform_callbacks.md)\) и специализированные запросы Gate API \([подробнее](ru_Gate_payment_status_request.md)\). - *Обновление.* Автоматическое обновление информации в разделе **Финансы** не поддерживается, при этом можно пользоваться обновлением вкладки браузера. Далее в этом разделе представлена информация о балансах и описан порядок действий, необходимых для контроля балансов, получения информации о применяемых курсах конвертации валют и вести учёт актуальных банковских счетов. ## Контроль балансов {#ru_dbl_working_with_balance} ### Балансы и особенности их использования {#ru_dbl_balances_aspects} Как и в платёжной платформе в целом, в интерфейсе Dashboard *баланс* — это сальдо в определённой валюте, которое может быть доступным для оперирования со стороны мерчанта, в том числе для вывода на его расчётные счета.Исходя из возможностей работы с ними балансы делятся на следующие типы: - IN — для зачислений денежных средств при проведении оплат и списаний при выполнении возвратов; - OUT — для списаний денежных средств при проведении выплат; - IN/OUT — для любых видов операционных зачислений и списаний денежных средств, при проведении оплат, возвратов и выплат. В работе с балансами следует учитывать ряд особенностей и ограничений: - Один баланс может вестись только в одной валюте. - Валюты, в которых могут вестись балансы, определяются со стороны Ecommpay. К базовым валютам относятся USD, GBP и EUR, в то время как доступность других следует уточнять у курирующего менеджера. В случаях, когда операционные валюты отличаются от валюты баланса, применяется конвертация. - Операции по *карточным* платежам \(с прямым использованием платёжных карт\) и по *альтернативным* \(с использованием альтернативных платёжных методов\) всегда разводятся по разным балансам. - Операции по различным альтернативным методам с одной балансовой валютой могут разводиться по разным балансам и сводиться в один. Так, при подключении в определённом регионе нескольких платёжных методов от одного провайдера с местными валютами расчётов и одной балансовой валютой \(например, EUR\), все операции по этим методам можно сводить в один баланс. - Операции по платёжным методам, по которым доступны оплаты и выплаты, сводятся в один баланс IN/OUT и не разводятся по балансам разного типа \(IN,OUT, IN/OUT\). Балансы типа IN иOUT могут использоваться, если по отдельному платёжному методу доступны только оплаты иливыплаты. - Все процедуры, связанные с формированием балансов и настройкой их связей с контрактамии платёжными методами, выполняются специалистами Ecommpay только по заявкам от мерчантов к курирующим менеджерам. И все вопросы по работе с балансами следует адресовать курирующим менеджерам. ### Контроль текущего состояния {#ru_dbl_balances_real_time} Информация о текущем состоянии балансов включает в себя суммарные показатели по каждой используемой валюте и реестр балансов. \(При этом стоит учитывать, что балансовый учёт операций может занимать до 30 минут и информация о состоянии балансов может отображаться с соответствующей задержкой.\) Для просмотра информации о балансах следует: 1. Перейти на вкладку **Текущий** в разделе **Финансы**. 2. Развернуть нужную вкладку \(**IN**,**OUT**, **IN/OUT**\)и убедиться, что отображается требуемая информация: сверху — итоговые суммы по балансам в доступных валютах, а под ними — перечень балансов с информацией о них. Если в разделе **Финансы** отсутствует вкладка **IN**, следует обратиться к курирующему менеджеру Ecommpay. 3. При необходимости, отфильтровать информацию по связи с контрактами. Для этого можно использовать выпадающий список с наименованиями контрактов, заключённых с Ecommpay ![](images/ecommpay/dbl/ru_dbl_balances.svg "Раздел «Финансы»") Для обновления информации о балансах можно обновлять вкладку браузера. Автоматическое обновление информации в этом разделе не поддерживается. ## Контроль информации о курсах конвертации валют {#ru_dbl_balances_currency_rates} В интерфейсе Dashboard поддерживается возможность получать информацию о применённых курсах конвертации валют по отношению к доллару США \(USD\), применяемых к операционным и неоперационным списаниям и зачислениям. Эти курсы приводятся с разбивкой за каждый час на выбранную дату. Чтобы ознакомиться с курсами конвертации требуемой валюты на определённую дату, достаточно перейти на вкладку **Курсы конвертации** в разделе **Финансы** и выбрать дату и валюту. ![](images/ecommpay/dbl/ru_dbl_balance_currency_rates.svg "Раздел «Финансы»") ## Работа с банковскими счетами {#ru_dbl_bank_accounts} ### Общая информация {#section_yk3_vth_42c .section} Интерфейс Dashboard позволяет вести учёт актуальных банковских счетов и использовать их для перевода средств с балансов в платформе Ecommpay. При этом должны соблюдаться следующие условия: - Для работы со счетами должна применяться двухфакторная аутентификация при доступе к интерфейсу Dashboard. - У используемой учётной записи должны быть соответствующая роль и права на выполнение необходимых действий в разделе **Финансы**. С информацией о порядке доступа к этому разделу в интерфейсе Dashboard можно ознакомиться в статье [Основные возможности и ролевая модель](ru_dbl_roles_overview.md). Для отображения информации о счетах используются соответствующие карточки, доступные на вкладке **Банковские счета** раздела **Финансы**. Информация обо всех созданных карточках сводится в реестр, а в составе отдельной карточки доступны панель управления и панель с реквизитами счёта и информации о получателе.Помимо карточек, создаваемых пользователями интерфейса Dashboard, в реестре доступны также карточки, создаваемые специалистами Ecommpay. ![](images/ecommpay/dbl/ru_dbl_bank_account_registry.svg "Реестр счетов") ![](images/ecommpay/dbl/ru_dbl_bank_account_card.svg "Карточка счёта") Для организации работы с карточками применяется следующий набор статусов: - `Draft` — карточка сохранена как черновик и доступна для редактирования\(без ограничений по времени\); - `Waiting for approval` — карточка отправлена на рассмотрение в Ecommpay; - `Correction is needed` — карточка проверена и требует корректировки\(в соответствии с подсказками на панели управления карточкой\); - `Active` — карточка согласована и может использоваться для выполнения финансовых операций; - `Blocked` — карточка заблокирована специалистами Ecommpay\(без возможностей её восстановления и повторной регистрации того же счёта\); - `Archived` — карточка деактивирована пользователем Dashboard\(без возможности её восстановления, но с возможностью повторной регистрации того же счёта\). ### Регистрация счёта {#section_rvg_wth_42c .section} Чтобы зарегистрировать счёт, следует: 1. Открыть вкладку регистрации счёта. Для этого необходимо открыть раздел **Финансы**, перейти на вкладку **Банковские счета** и щёлкнуть кнопку **Добавить новый счет** в левом верхнем углу над реестром, после чего выбрать в открывшемся окне юридическое лицо и подтвердить выбор, щёлкнув кнопку **Продолжить**. 2. Задать реквизиты для переводов, включая сведения о банковском счёте и получателе переводов. Для этого должны быть указаны следующие сведения: - **Компания мерчанта** — наименование юридического лица мерчанта\(в соответствии с выбранным на шаге 1; без возможности редактирования\). - **Номер договора** — номера договоров\(одного или более\), которые ассоциированы с указанным юридическим лицоми могут использоваться для переводов средств на регистрируемый счёт. - **Мультивалютный счет** — индикатор поддержки мультивалютных операций \(со стороны банка\)для регистрируемого счёта: `Yes`, `No`. Стоит учитывать, что если для регистрируемого счёта не доступны платежи ни в одной из базовых валют Ecommpay \(USD, GBP или EUR, с учётом используемых способов взаимодействия с Ecommpay\), то при переводе средств на такой счёт применяется конвертация. При этом допустимо регистрировать дополнительный счёт, выступающий в качестве промежуточного, на панели **Банк посредник**. - **Желаемая валюта сеттлмента** — коды базовых валют Ecommpay, в которых предпочтительно выполнять переводы на регистрируемый мультивалютный счёт. - **Валюта счета** — код валюты регистрируемого моновалютного счёта. - **Банковский БИК/SWIFT** — международный идентификационный код\(БИК или SWIFT\) банка, в котором открыт счёт. При заполнении этого поля можно использовать варианты из выпадающего списка, которые становятся доступными при указании по крайней мере трёх символов. - **Название банка** — наименование банка, в котором открыт счёт\(в соответствии с указанным SWIFT-кодом; без возможности редактирования\). - **Страна банка** — наименование страны, в которой зарегистрирован банк\(в соответствии с указанным SWIFT-кодом; без возможности редактирования\). - **IBAN \(Номер счета\)** — номер счёта \(International Bank Account Number\)для зачисления средств с балансов мерчанта в платформе Ecommpay. - **Тип бенифициара** — категория получателя перевода, являющегося владельцем счёта для зачисления средств: юридическое лицо мерчанта, указанное на шаге 1 \(`Merchant Company`\), или иное лицо \(`Other Company`\). - **Название бенифициара** — наименование получателя из банковских реквизитов счёта\(при выборе типа бенифициара `Merchant Company` заполняется автоматически, в соответствии с выбранным на шаге 1 юридическим лицом; при выборе типа бенифициара `Other Company` должно заполняться самостоятельно\). - **Регистрационный адрес бенифициара** — адрес регистрации получателя\(при выборе типа бенифициара `Merchant Company` заполняется автоматически, в соответствии с выбранным на шаге 1 юридическим лицом, и может быть отредактировано, но только по отношению к регистрируемому счёту; при выборе типа бенифициара `Other Company` должно заполняться самостоятельно\). - **Регистрационный номер бенифициара** — идентификационный номер получателя из национального реестра бенифициаров\(при выборе типа бенифициара `Merchant Company` заполняется автоматически, в соответствии с выбранным на шаге 1 юридическим лицом, и может быть отредактировано, но только по отношению к регистрируемому счёту; при выборе типа бенифициара `Other Company` должно заполняться самостоятельно\). - **Дополнительная информация** — сведения для подтверждения допустимости переводов средств иному лицу, указанному в качестве получателя при выборе типа бенифициара `Other Company` \(например, это могут быть файлы договоров между мерчантом и этим лицом\). **Прим.:** Если сохранить карточку как черновик, к её заполнению можно вернуться позже \(открыв карточку и щёлкнув кнопку **Редактировать** на панели управления\). 3. Отправить информацию о регистрируемом счёте на рассмотрение в Ecommpay. Для этого необходимо щёлкнуть кнопку **Создать банковский счет** и убедиться, что статус карточки сменился на `Waiting for approval`. Стоит учитывать, что после отправки карточки на рассмотрение изменять информацию в ней можно только в случае смены статуса на `Correction is needed`. 4. Убедиться, что счёт зарегистрирован, либо, если это актуально, вернуться к шагу 2. Для этого можно ориентироваться на статус его карточки в реестре счетов — в течение 5 рабочих дней с момента отправки информации он должен измениться с `Waiting for approval` на `Active` \(если карточка согласована и счётом можно пользоваться\) или на `Correction is needed` \(если карточка требует корректировки и следует вернуться на шаг 2 для внесения уточнений, в соответствии с подсказками на панели управления карточкой\). Карточки мультивалютного счёта, принадлежащего иному лицу, и моновалютного счёта, принадлежащего юридическому лицу мерчанта, могут выглядеть \(при их заполнении\) следующим образом. ![](images/ecommpay/dbl/ru_dbl_bank_account_multycurrency.svg "Регистрация мультивалютного счёта") ![](images/ecommpay/dbl/ru_dbl_bank_account_singlecurrency.svg "Регистрация моновалютного счёта") ### Архивирование счёта {#section_s5f_5gn_42c .section} В реестре банковских счетов поддерживается возможность исключать счета из числа используемых для выполнения финансовых операций. При этом стоит учитывать, что для восстановления исключённого счёта его необходимо зарегистрировать повторно. Чтобы исключить счётиз числа используемых для работы с платформой, следует: 1. Найти карточку счёта в реестре и открыть её. Для этого следует перейти в реестр счетов и при необходимости воспользоваться фильтром по принадлежности счёта к юридическому лицу мерчанта. 2. Исключить счёт, щёлкнув кнопку **Архивировать** на панели управления. 3. Подтвердить действие в появившемся модальном окне. 4. Убедиться, что счёт исключён из числа используемых. Для этого можно проверить статус его карточки — он должен принять значение `Archived`. --- # Работа с рисками {#ru_dbl_risks} статья о процессах управления рисками в электронной коммерции и возможностях контролировать выявленные факты мошенничества и настраивать «чёрные» списки через Dashboard **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Введение {#ru_risks_intro} Развитию любых видов коммерции традиционно сопутствует и развитие разных видов финансового мошенничества. Электронная коммерция — не исключение. Одной из наиболее распространённых форм мошенничества в этой сфере является компрометация данных платёжной карты и попытка выдать себя за её держателя. При этом, конечно, развиваются и другие формы мошеннических действий, как с картами, так и с другими платёжными инструментами. Для борьбы с мошенничеством, как правило, применяется комплекс мер со стороны платёжных систем и других сторон, участвующих в проведении платежей: эмитентов, провайдеров и мерчантов. Прежде всего, за счёт таких мер обеспечиваются проверки двух видов: - *Проверка подлинности* пользователей и их платёжных инструментов, для чего применяются протоколы аутентификации 3‑D Secure, проверка адреса пользователя \(Address Verification Service; AVS\) и прочие подобные решения. - *Проверка допустимости* платежей с учётом их параметров, для чего применяются проверки параметров на соответствие так называемым «белым» и «чёрным» спискам и различным правилам, а также разные виды анализа и оценки рисков. При работе с платёжной платформой Ecommpay можно в полной мере пользоваться проверками обоих этих видов и минимизировать риски проведения мошеннических операций. Для этого следует: - Настроить и поддерживать со стороны веб-сервиса эффективную работу с решениями для проверки подлинности пользователей. Так, например, при работе с протоколом аутентификации 3‑D Secure 2 можно указывать предпочтения мерчанта по использованию варианта аутентификации challenge flow для каждого проводимого платежа, а при работе с AVS можно передавать данные об адресах в исходных запросах и обеспечивать возможность проверки без дополнительных действий со стороны пользователей.Также стоит учитывать, что при использовании протоколов 3‑D Secure финансовая ответственность за проведение мошеннических платежей возлагается на эмитента\(и снимается с остальных сторон, что в том числе обеспечивает отсутствие опротестований с причиной fraud\). Грамотное применение таких возможностей помогает обеспечивать на высоком уровне и защиту от мошенничества, и уровень проходимости платежей. С вопросами о таких возможностях можно обращаться к курирующему менеджеру и специалистам технической поддержки Ecommpay. - Настроить и поддерживать правила для проверки платежей — чтобы они применялись наряду с правилами других сторон \(Ecommpay, платёжных систем и эмитентов\) и позволяли эффективно фильтровать платежи. Для этого совместно со специалистами Ecommpay определяются специфичные для конкретных проектов ограничения и правила, которые далее применяются на стороне платёжной платформы и могут актуализироваться по мере необходимости. И в дополнение к таким правилам можно использовать собственные «белые» и «чёрные» списки, которые также учитываются в платёжной платформе при проведении платежей. С вопросами об этих возможностях можно обращаться к курирующему менеджеру и специалистам Ecommpay по работе с рисками. - Контролировать выявляемые случаи мошенничества и отказы в проведении платежей и, когда это необходимо, обеспечивать реагирование, а также разбирать особые случаи со специалистами Ecommpay и корректировать применяемые настройки. Для этого можно использовать возможности Dashboard и обращаться с вопросами к курирующему менеджеру и специалистам Ecommpay. Интерфейс Dashboard позволяет формировать собственные «белые» и «чёрные» списки, а также отслеживать информацию о попытках и фактах мошенничества, выявленных на стороне Ecommpay и платёжных систем. В рамках данного раздела вместе с кратким описанием общего процесса работы с рисками представлена информация о тех процедурах, которые можно выполнять через Dashboard. ## Общий процесс {#ru_risks_process} ### Обзор {#ru_risks_process_overview} Чтобы описать процесс противодействия финансовому мошенничеству, можно выделить несколько его свойств. Во-первых, этот процесс можно назвать многоуровневым. В нём принимают участие разные стороны, включая мерчантов, провайдеров, платёжные системы и эмитентов, и каждая из этих сторон обеспечивает противодействие на своём уровне: применительно к потоку платежей, который её затрагивает. При этом могут использоваться разные инструменты, некоторые из которых могут быть общими для нескольких сторон \(как в случае с аутентификацией 3‑D Secure\), а другие — частными, специфичными для каждой из сторон \(как в случае с «белыми» и «чёрными» списками\). И за счёт последовательного применения таких инструментов обеспечивается многоступенчатая фильтрация операций и достигается действенный уровень общей эффективности. Во-вторых, для этого процесса характерны как прямые, так и обратные связи между разными уровнями. Так, если для некоторой операции было установлено, что её следует считать мошеннической, уже после того, как её провели, информация об этом доводится до всех причастных сторон и позволяет корректировать работу по противодействию подобным операциям на разных уровнях. В-третьих, на каждом из уровней этот процесс можно представить как непрерывный цикл с четырьмя стадиями: настройкой, контролем, реагированием и анализом. ![](images/universal/dbl/ru_dbl_risks_circle.svg) Таким образом, процесс противодействия финансовому мошенничеству можно представить как систему связных действий, циклически повторяемых на разных уровнях. Далее описаны основные стадии этого процесса — настройка, контроль, реагирование и анализ — с фокусировкой на тех аспектах, которые могут быть актуальными в работе мерчантов. ### Настройка {#ru_risks_process_setup} #### Проверка подлинности {#section_tmd_gtd_rnb .section} Для проверки подлинности пользователей в платформе поддерживаются различные вспомогательные процедуры, такие как аутентификация 3‑D Secure, аутентификация по инициативе мерчанта и проверка адреса \(Address Verification Service\). Кроме того, для эффективной проверки подлинности могут быть полезны некоторые дополнительные возможности, такие как сбор и передача дополнительных сведений о пользователях. Как правило, при работе через Gate для поддержки таких процедур и возможностей необходимы доработки на стороне веб-сервиса, в то время как при работе через Payment Page всё выполняется на стороне платёжной платформы и не требует задействования веб-сервиса. Подробную информацию о вспомогательных процедурах можно найти в разделе [Gate](ru_gate_procedures.md), а о дополнительных возможностях — в разделах [Gate](ru_Gate_Additional_capabilities.md) и [Payment Page](ru_PP_Additional.md). В целом для эффективной работы с этими инструментами со стороны мерчанта следует: 1. Определять возможности и процедуры, которые необходимо поддерживать для конкретных проектов. 2. Если это необходимо, обеспечивать поддержку целевых возможностей и процедур со стороны веб-сервиса. С вопросами о комбинировании процедур и возможностей, а также об их подключении и настройке можно обращаться к курирующему менеджеру и сотрудникам технической поддержки Ecommpay. #### Проверка допустимости {#section_dxx_nsj_zsb .section} Для проверки допустимости платежей их параметры проверяются в платформе на соответствие различным правилам, которые могут быть общими для всех платежей и частными для платежей отдельных мерчантов и их проектов. Это касается, прежде всего, «белых» и «чёрных» списков, которые могут применяться и со стороны мерчанта, и со стороны Ecommpay. В целом для эффективной работы с этими инструментами со стороны мерчанта следует: 1. Совместно со специалистами Ecommpay определять правила и ограничения, которые должны применяться для конкретных проектов. 2. Вести свои частные «белые» и «чёрные» списки, которые доступны для просмотра и редактирования в интерфейсе Dashboard и применяются в платформе наряду с остальными правилами. С вопросами о настройке правил проверки и о работе с «белыми» и «чёрными» списками, в том числе о переносе этих списков из других систем, можно обращаться к курирующему менеджеру и специалистам Ecommpay по работе с рисками. ### Контроль {#ru_risks_process_monitoring} Перед выполнением операций в платёжной платформе Ecommpay проверяется их допустимость. В рамках такой проверки параметры каждой операции проверяются на соответствие заданным правилам и операция автоматически относится к одной из следующих категорий: - Мошенническая — если хотя бы один из параметров операции присутствует в «чёрном» списке или риск в выполнении операции \(по совокупности её параметров\) оценивается как высокий. В этом случае операция отклоняется и от Ecommpay к веб-сервису отправляется итоговое оповещение со статусом операции `decline` и кодом ошибки \(полный список таких кодов ошибок и пояснений к ним представлен [в блоке коды RCS](ru_platform_payment_info_codes.md)\). - Подозрительная — если по заданным алгоритмам не удаётся однозначно оценить риск в выполнении операции и требуются уточнения. В этом случае операция отправляется на выполнение, а специалисты Ecommpay дополнительно анализируют, можно ли считать её благонадёжной или мошеннической, и при необходимости передают информацию для согласований сотрудникам мерчанта. И уже по итогам оценки специалистами могут применяться различные меры, в том числе выполнение возврата и дополнение «чёрного» списка. - Благонадёжная — если хотя бы один из параметров операции присутствует в «белом» списке или риск в выполнении операции \(по совокупности её параметров\) оценивается как несущественный. В этом случае операция отправляется на выполнение. **Прим.:** Важным моментом при таком анализе является приоритет одних списков перед другими. Как правило, если хотя бы один параметр операции относится к «чёрному» списку, то приоритет отдаётся «чёрному» списку и операция признаётся мошеннической, но в отдельных случаях приоритет отдаётся «белому» списку и операция признаётся благонадёжной \([подробнее](ru_dbl_risks.md)\). Поэтому работать с «белыми» и «чёрными» списками следует максимально предусмотрительно. После начальной оценки рисков со стороны мерчанта и Ecommpay контроль не заканчивается: одобрение операции на стороне Ecommpay не исключает признания этой же операции неблагонадёжной со стороны других участников проведения платежа, а одобрение операции всеми участниками не исключает выявления мошенничества постфактум. В таких случаях информация о попытках и фактах мошенничества, выявленных другими участниками, передаётся в Ecommpay и далее, специалистами Ecommpay, сотрудникам мерчанта. Кроме того, со стороны мерчанта можно контролировать выполнение операций и получать информацию об отклонённых и мошеннических операциях через интерфейс Dashboard или электронную почту \(подробнее об этом далее\), а в любой нестандартной ситуации можно обращаться через электронную почту к специалистам Ecommpay по работе с рисками. ### Реагирование {#ru_risks_process_response} В зависимости от того, как оценивается риск операции при её выполнении, а также от того, признаётся ли операция мошеннической уже после её выполнения, на стороне мерчанта могут быть актуальны те или иные действия.И эффективность таких действий может существенно влиять на успешность борьбы с мошенничеством и ведения бизнеса в целом. Основными ситуациями для реагирования со стороны мерчанта являются следующие: - *Операция отклонена как неблагонадёжная на стороне Ecommpay.* В этом случае рекомендуется уточнить причину отклонения \(через разбор программного оповещения или интерфейс Dashboard\) и при необходимости отреагировать следующим образом: - дополнить «чёрный» список — если операция действительно мошенническая и можно выделить критерий для блокировки последующих подобных операций \(например, номер телефона пользователя\); - дополнить «белый» список — если есть уверенность, что операция благонадёжная, но с нетипичным поведением пользователя, и при этом можно выделить критерий для подтверждения благонадёжности последующих подобных операций; - связаться со специалистами Ecommpay — если есть вопросы по выполнению операции; - повторно инициировать операцию — если это актуально в работе с пользователем и \(за счёт обновления «белого» списка или договорённостей со специалистами Ecommpay\) есть готовность к выполнению операции без её повторного отклонения. - *Операция признана подозрительной на стороне Ecommpay.* В этом случае следует проанализировать причину и характер подозрений в мошенничестве и при необходимости связаться с пользователем для уточнения деталей и со специалистами Ecommpay для согласования необходимых действий, после чего предпринять эти действия. К таким действиям могут относиться, например, выполнение возвратов и дополнение «белых» и «чёрных» списков. - *Операция одобрена на стороне Ecommpay, но отклонена как неблагонадёжная на стороне другого участника.* В этом случае рекомендуется уточнить причину отклонения \(через Dashboard или специалистов Ecommpay\) и при необходимости отреагировать следующим образом: - дополнить «чёрный» список — если операция действительно мошенническая и можно выделить критерий для блокировки последующих подобных операций; - повторно инициировать операцию — если причина отклонения допускает повторную попытку и есть уверенность в благонадёжности операции и понимание того, что она была отклонена из-за некорректно или неполно указанных данных. - *Операция выполнена, но признана мошеннической постфактум.* В этом случае рекомендуется уточнить критерии, характеризующие операцию как мошенническую \(через Dashboard или специалистов Ecommpay\), проанализировать остальные операции с участием пользователя, инициировавшего мошенническую операцию, по всем проектам мерчанта и при необходимости дополнить «чёрные» списки. В случае, если мошенническая операция была выполнена без использования протокола 3‑D Secure, рекомендуется выполнить возврат средств пользователю, пострадавшему от мошенничества \(в том числе для предотвращения опротестований и связанных с ними дополнительных комиссий и репутационного урона\). Кроме того, в любой нестандартной ситуации рекомендуется обращаться к специалистам Ecommpay по работе с рисками. ### Анализ {#ru_risks_process_analysis} Чтобы обеспечивать эффективное проведение платежей — с высоким уровнем конверсии и надёжной защитой от мошенничества — необходимо регулярно анализировать общую ситуацию. Оценивать количество корректных и некорректных отклонений, выявлять дополнительные критерии для использования в «белых» и «чёрных» списках, определять необходимость изменений в работе с процедурами подтверждения подлинности пользователей и правилами оценки допустимости операций на стороне Ecommpay и так далее. Все аспекты борьбы с мошенничеством требуют регулярного внимания, в том числе потому что схемы мошенничества в электронной коммерции постоянно развиваются в попытках обойти действующие средства защиты. С вопросами о том, как можно выстроить анализ эффективности в работе с рисками, можно обращаться к курирующему менеджеру Ecommpay. ## Контроль мошеннических операций {#ru_dbl_fraud_operations_control} ### Введение {#ru_dbl_fraud_operations_control_overview} Платёжная платформа позволяет отслеживать информацию о попытках и фактах мошенничества, выявленных на стороне Ecommpay и платёжных систем. Для этого можно использовать инструменты Dashboard и автоматическую рассылку на электронную почту. ### Использование инструментов Dashboard {#ru_dbl_fraud_operations_control_dashboard} В интерфейсе Dashboard для этого можно использовать различные инструменты: - реестр платежей в разделе **Платежи** \(с информацией обо всех платежах\); - реестр мошеннических операций в разделе **Риски** \(с информацией об операциях, признанных мошенническими на стороне платёжных систем\); - отчёты по мошенническим операциям, формируемые через раздел **Отчёты**. В работе с указанными реестрами доступны типовые инструменты фильтрации \([подробнее](ru_dbl_interfaces.md)\), а также карточки с детальной информацией об отдельных платежах и относящихся к ним операциях \(для открытия карточки достаточно щёлкнуть строку платежа в реестре\). Для работы с детальной информацией о мошенничестве в разделе **Риски** и карточках платежей требуется право на управление рисками, по умолчанию доступное учётным записям с ролями `Risks` и `Merchant Admin`, кроме того для работы с отчётами требуется отдельное право на управление отчётами. ![](images/ecommpay/dbl/ru_dbl_risks_payment_registry.svg "Реестр платежей") ![](images/ecommpay/dbl/ru_dbl_risks_fraud_registry.svg "Реестр мошеннических действий") При работе с реестрами платежей и мошеннических действий следует учитывать ряд особенностей: - Информация в реестрах и карточках отображается с задержкой, которая может составлять до нескольких минут, а автоматическое обновление информации не поддерживается. - Информация о мошенничестве, выявленном платёжными системами, поступает в платформу два раза в день — до 07:00 и 15:00 UTC+0, поэтому рекомендуется отслеживать эту информацию после указанного времени. - В реестре мошеннических действий может отображаться несколько записей об одной и той же операции с разными датами обновления — в случаях, когда информация об этой операции включается в несколько отчётов от платёжных систем. - Состав и порядок столбцов в реестрах могут настраиваться, поэтому при наличии соответствующих прав можно оформить реестры в соответствии с индивидуальными предпочтениями. Например, базовый состав столбцов в реестре мошеннических действий можно дополнить столбцом **Дата покупки** с датой выполнения операции, признанной мошеннической. Для контроля информации об интересующих операциях достаточно следующих действий: 1. Перейти в нужный раздел: **Платежи** или **Риски**. 2. Найти в реестре записи о требуемых операциях, используя инструменты фильтрации, если это необходимо. В реестре платежей операции, отклонённые на стороне Ecommpay из-за их высокого риска, можно найти по статусу платежа `decline` и служебному коду \(к таким кодам относятся код `402` и коды блока [RCS](ru_platform_payment_info_codes.md)\), а операции, признанные мошенническими другими сторонами, можно найти по индикатору `fraud` \(в том числе с помощью фильтрации ![](images/universal/dbl/icon_filter.svg)\). 3. Проверить интересующую информацию, непосредственно в реестре или в карточках платежей. В реестре мошеннических действий и в блоке **Мошеннические платежи**, расположенном в детальной карточке платежа, отображается информация о мошенничестве в рамках конкретной операции. ![](images/ecommpay/dbl/ru_dbl_risks_payment_card.svg) ### Использование автоматической рассылки {#ru_dbl_fraud_operations_control_mail} Отслеживать информацию об операциях, признанных мошенническими на стороне платёжных систем, можно не только с помощью инструментов Dashboard, но и с помощью автоматической рассылки на адрес электронной почты, привязанный к учётной записи Dashboard. Уведомления в рамках такой рассылки отправляются в 14:00и в 17:00 UTC+0 при наличии в платформе новой информации о фактах мошенничества. По умолчанию эта рассылка включена для всех учётных записей. Её можно отключить самостоятельно или с помощью сотрудника с ролью `Merchant admin`. Чтобы отключить рассылку самостоятельно, следует: 1. Открыть профиль учётной записи. Для этого необходимо щёлкнуть имя или иконку учётной записи справа в главном меню и выбрать в выпадающем списке пункт **Мой профиль**. 2. Перевести выключатель **Получать письма о мошеннических транзакциях** в неактивное положение. Для этого необходимо перейти в режим редактирования личной информации, щёлкнув ![](images/universal/dbl/icon_pencil.svg) на панели **Профиль**, перевести соответствующий выключатель в нужное положение и сохранить изменения, щёлкнув кнопку **Сохранить**, расположенную в правой верхней части панели **Профиль**. 3. Убедиться, что все изменения сохранены. Об этом свидетельствуют неактивное положение переключателя. ## Работа с «белыми» и «чёрными» списками {#ru_dbl_risks_bwlist} ### Общая информация {#ru_dbl_risks_bwlist_overview} Для проверки допустимости выполнения операций их параметры проверяются в платформе на соответствие различным правилам, в том числе на соответствие «белым» и «чёрным» спискам. Такие списки могут быть общими для всех мерчантов и частными для отдельных проектов мерчанта. - «Белый» список — это перечень критериев, при соответствии любому из которых операция признаётся заведомо благонадёжной. - «Чёрный» список — перечень критериев, при соответствии любому из которых операция признаётся заведомо мошеннической. При работе с конкретными операциями используется ряд правил: 1. Если хотя бы один из параметров операции присутствует в «чёрном» списке **ID покупателя**, **Номер аккаунта** или **E-mail**, то приоритет отдаётся «чёрному» спискуи операция признаётся мошеннической. 2. Если не выполняется первое условие и, вместе с тем, среди параметров операции присутствуют те, которые входят в списки **IP** и **BIN** как взаимоисключающие\(один в «белый», другой в «чёрный», в любой комбинации\), то приоритет отдаётся «белому списку»и операция признаётся заведомо благонадёжной. 3. Если по результатам таких проверок, как AML\(Anti-Money Laundering; на включение имени в санкционные списки\) и Compliance\(на допустимость выполнения операции из конкретной страны\), операция признаётся неблагонадёжной, то она отклоняется даже при наличии параметров, присутствующих в «белых» списках. ### Возможности интерфейса {#ru_dbl_risks_bwlist_interface_capabilities} В интерфейсе Dashboard поддерживается возможность работать с критериями «белых» и «чёрных» списков по отдельным проектам и совокупности проектов мерчанта. Для этогов разделе **Риски** выделен подраздел **Черные/белые списки**, который позволяет: - просматривать список критериев, с использованием инструментов поиска и фильтрации, если это необходимо; - добавлять критерии, поштучно или пакетами; - удалять критерии, только поштучно. Поиск критериев «белых» и «чёрных» списков осуществляется с помощью фильтров на верхней панели, в том числе с возможностью указывать несколько значений одной категории \(например, `customer_id`\) через запятую или пробел. Вместе с тем, добавлять критерии оценки риска можно и из карточек платежей.Такая возможность поддерживается для любых операций: без ограничения на типы платежейи платёжные методы и без обязательного выявления мошенничества на стороне платёжных систем. Доступ к возможностям работы с критериями оценки риска регулируется отдельными правами. По умолчанию учётным записям, отнесённым к ролям `Risks` и `Merchant Admin`, доступны просмотр «белых» и «чёрных» списков и добавление критериев в «чёрные» списки.В дополнение к этому через обращения к специалистам технической поддержки можно регулировать для отдельных учётных записей право добавления критериев в «белые» списки. Такой подход в отношении «белых» списков обоснован их приоритетом, в том числе при автоматическом анализе рисков в некоторых случаях, и позволяет уменьшать риски выполнения мошеннических операций. ![](images/ecommpay/dbl/ru_dbl_risks_bwlist_registry.svg "Подраздел Черные/белые списки") ### Добавление записей через карточку платежа {#ru_dbl_risks_bwlist_payment_card} При работе с карточками платежей можно добавлять в «чёрные» списки \(и при наличии соответствующего права — в «белые»\) критерии отдельных операций — по любым платежам без каких-либо ограничений. Это может быть удобным при разборе отдельных случаев признания операции подозрительной или мошеннической, и для такого оперативного добавления следует: 1. Найти платёж, к которому относится целевая операция — та, значения параметров которой необходимо добавить в «чёрный» \(«белый»\) список. Для этого можно воспользоваться поиском \([подробнее](ru_dbl_interfaces.md#section_r4t_f5m_hlb)\) или реестрами и фильтрами в разделах **Платежи** и **Риски**. 2. Открыть карточку платежа. Для этого следует щёлкнуть соответствующую строку в реестре выбранного раздела. 3. Добавить критерии в «чёрный» \(«белый»\) список. Для этого необходимо: 1. Щёлкнуть кнопку **Добавить в список**, расположенную на панели **Операция**. 2. Выбрать в открывшемся окне: тип списка \(«белый» или «чёрный»\), доступные для конкретной операции категории \(по которым необходимо добавить критерии в список\) и идентификаторы проектов \(для которых необходимо применить изменения\). При необходимости можно добавить комментарий, общий для всех добавляемых критериев. **Прим.:** В отдельных случаях в окне **Добавить в список** для выбора могут быть доступны те категории, которые не использовались для выполнения выбранной операции — например, категория `email` для операции, в запросе на выполнение которой не указывался этот параметр. В таких случаях при попытке добавить запись в «белый» или «чёрный» список, список не пополняется. 3. Подтвердить добавление критериев в «чёрный» \(«белый»\) список, щёлкнув кнопку **Применить**. ![](images/ecommpay/dbl/ru_dbl_risks_bwlist_add_from_payment_card.svg) 4. Убедиться, что критерии добавлены в «чёрный» \(«белый»\) список. Для этого можно проверить, что записи добавлены в реестр со списком критериев в подразделе **Черные/белые списки**. ### Добавление записей через форму {#ru_dbl_risks_bwlist_form} При работе с разделом **Риски** можно добавлять различные критерии в «чёрные» списки \(и при наличии соответствующего права — в «белые»\) через форму в подразделе **Черные/белые списки**.Это может быть удобным при анализе разных случаев и выявлении дополнительных критериев оценки риска, в том числе когда необходимо внести записи в «белый» или «чёрный» список без привязки к конкретным операциям. Для такого добавления записей следует: 1. Открыть форму одиночного добавления критериев. Для этого следует открыть раздел **Риски**, перейти в подраздел **Черные/белые списки** и щёлкнуть кнопку **Добавить в список** слева на панели фильтрации. 2. Добавить критерии. Для этого необходимо выбрать тип списка \(«белый» или «чёрный»\), указать в целевых полях необходимые критерии и щёлкнуть кнопку **Применить**. При некорректном заполнении хотя бы одного из полей отображаются соответствующие уведомления об ошибках. В таком случае следует скорректировать значения \(либо отказаться от их ввода\) и повторно щёлкнуть кнопку **Применить**. 3. Убедиться, что критерии добавлены, дождавшись. Об этом свидетельствует появление окна с уведомлением об успешной отправке запросов на добавление. Также можно проверить, что записи добавлены в реестр со списком критериев в подразделе **Черные/белые списки**. ![](images/ecommpay/dbl/ru_dbl_risks_bwlist_add_from_form.svg "Добавление записей в «чёрный» список") ### Добавление записей через файл {#ru_dbl_risks_bwlist_file} #### Порядок работы {#section_fxd_rcr_qnb .section} При работе с дополнительными источниками данных о рисках можно добавлять различные критерии в «чёрные» списки \(и при наличии соответствующего права — в «белые»\) через файлы. Это может быть удобным, например, когда необходимо внести записи и в «белые», и в «чёрные» списки без привязки к конкретным операциям и ограничений на количество добавляемых записей. Для такого добавления записей следует: 1. Подготовить файл заданного формата с информацией о критериях. Следует учитывать, что в одном файле можно указывать критерии и для «белых», и для «чёрных» списков и для каждой операции должен указываться идентификатор мерчанта, полученный от Ecommpay при интеграции \(при необходимости этот идентификатор можно получить в реестре Платежей, добавив через конфигуратор столбец **Мерчант**\). Полные требования к таким файлам представлены далее, вместе с шаблоном и примером заполнения. 2. Открыть форму массового добавления критериев. Для этого следует: 1. Открыть раздел **Риски** и перейти в подраздел **Черные/белые списки**. 2. Щёлкнуть кнопку **Добавить в список** слева на панели фильтрации. 3. Перейти на вкладку массового добавления. 3. Загрузить подготовленный файл со списком записей и добавить их. Для загрузки можно перетащить файл в область загрузки или использовать кнопку **Выберите файл**. После загрузки следует щёлкнуть кнопку **Применить**, чтобы добавить записи. При некорректном заполнении хотя бы одного из полей отображаются уведомления об ошибках. В таком случае необходимо скорректировать файл, загрузить его повторно и повторно щёлкнуть кнопку **Применить**. 4. Убедиться в добавлении всех записей. Об этом свидетельствует появление окна с уведомлением об успешной отправке запросов на добавление. Также можно проверить, что записи добавлены в реестр со списком критериев в подразделе **Черные/белые списки**. ![](images/ecommpay/dbl/ru_dbl_risks_bwlist_add_from_file.svg "Добавление записей через файл") #### Требования к файлам {#section_z5c_xyr_1tb .section} Для подготовки файла можно использовать шаблон, доступный для скачивания в интерфейсе Dashboard на вкладке массового добавления или [по ссылке](files_for_downloads/dashboard/TemplateRisks.csv).После загрузки шаблона его можно заполнить в любом редакторе файлов формата CSV, например, MS Excel. При этом каждый файл должен удовлетворять следующим требованиям: - Должен использоваться формат CSV с кодировкой символов UTF-8 без использования маркеров очерёдности \(Byte Order Mark, BOM\). - Размер файла не должен превышать 128 MБ. - Первая строка должна содержать названия параметров, при этом названия могут указываться в любой последовательности. - Последующие строки должны содержать значения целевых параметров, при этом для необязательных параметров значения могут не указываться. - В случае, если названия и значения параметров операций задаются текстовыми строками \(не в формате таблицы\), в качестве разделителя значений параметров используется «;» \(точка с запятой\), при этом поля без значений разделяются точкой с запятой так же, как и поля со значениями и допускаются ситуации с идущими подряд двумя и более знаками «;», например: ![](images/universal/dbl/ru_dbl_risks_bwlist_add_from_file_example.png) В случае подготовки файла с разделителем «;» в программе Microsoft Excel рекомендуется выполнять проверку в другом редакторе, например в «Блокноте». #### Используемые параметры {#section_tgq_xyr_1tb .section} При заполнении данных о критериях в файлах могут использоваться следующие параметры. |merchant\_id integer, required |Идентификатор мерчанта, полученный от Ecommpay при интеграции. Пример: `644` | |project\_id integer, required |Идентификатор проекта \(полученный от Ecommpay при интеграции\), к которому относится добавляемый критерий. При добавлении IP-адреса пользователя может указываться идентификатор любого из проектов мерчанта. Пример: `1020` | |list\_type string, required |Тип списка: `whitelist` или `blacklist`. В одном файле можно указывать критерии и для «белых», и для «чёрных» списков. Пример: `whitelist` для «белого» списка | |category string, required |Категория критерия: - `email` — адрес электронной почты пользователя, - `customer_id` — идентификатор пользователя, - `pan` — номер карты пользователя, - `ip` — IP-адрес пользователя, - `bin` — банковский идентификационный номер. При использовании категории `ip` критерий добавляется в списки всех проектов мерчанта, вне зависимости от указанного идентификатора проекта. Пример: `email` | |value string, required |Значение критерия. Пример: `joe.doe12@sunmail.com` для адреса электронной почты | |reason string, optional |Причина добавления в список. Пример: `Пользователь делает возврат на каждую оплату` | ### Удаление записей {#ru_dbl_risks_bwlist_delete} Удалять критерии «белых» и «чёрных» списков можно в разделе **Риски**, при этом стоит учитывать, что удалять их можно только поштучно. Для этого необходимо: 1. Перейти в подраздел критериев, щёлкнув кнопку **Черные/белые списки** в разделе **Риски**. 2. Найти в реестре необходимую запись, используя инструменты фильтрации, если это необходимо. 3. Удалить запись, щёлкнув кнопку ![](images/universal/dbl/icon_trashbin.svg) в соответствующей строке. 4. Проверить , что запись удалена из реестра. --- # Работа с программными оповещениями об опротестованиях платежей {#ru_dbl_chargeback_callbacks} статья о возможностях работы с программными оповещениями о событиях, связанных с оформлением и рассмотрением опротестований финансовых операций **На уровень выше:**[Dashboard](ru_dbl_about.md) ## Общая информация {#ru_dbl_chargeback_callbacks_overview} При работе с платёжной платформой можно подключить и использовать ежедневные программные оповещения о событиях, связанных с оформлением и рассмотрением опротестований финансовых операций.Это актуально в тех случаях, когда Ecommpay выступает как эквайери взаимодействует со стороны мерчантас эмитентами и платёжными системами \([подробнее](ru_faq_chargebacks.md)\), и может быть полезным наряду с использованием других интерфейсов, позволяющих получать информацию об опротестованиях \(таких, как Data API и Dashboard\). Оповещения об опротестованиях, как и основные оповещения от платёжной платформы, технически представляют собой HTTP-POST-запросы с вложенной в них информацией в формате JSON для приёма и обработки на стороне веб-сервиса мерчанта. При этом в работе с оповещениями об опротестованиях есть ряд особенностей: - Передаваемые данные не подкрепляются цифровыми подписями. - Оповещения отправляются раз в сутки: в 12:00 UTC либо, если по каким-либо причинам отправка не может быть выполнена в это время, в 15:00 UTC. - Оповещения отправляются не больше чем на один URL для одного проекта мерчанта. - Оповещения отправляются однократно. Повторная отправка не применяется, даже если получение какого-либо оповещения не было подтверждено ответным сообщением \(с кодом ответа `200 ОК`\) или если был передан ответ с ошибкой \(например, с кодом ответа `400 Bad Request`\). - Оповещения профилируются по стадиям работы с опротестованиями и делятся на два вида: со сводной и детализированной информацией \(подробнее [далее](ru_dbl_chargeback_callbacks.md)\). - Оповещения отправляются только при наличии новой профильной информации\(относительно предыдущей отправленной\). Если профильных обновлений нет, оповещения об этом не отправляются. Подключение программных оповещений об опротестованиях финансовых операций осуществляется по согласованию с курирующим менеджером Ecommpay. ## Виды оповещений {#ru_dbl_chargeback_callbacks_types} ### Оповещения со сводной информацией {#section_yg2_qfq_tgc .section} Сводные оповещения содержат информацию о количестве опротестований, по которым за отчётное время в платформе были зарегистрированы профильные события. Эти события делятся на следующие категории: - `new_chargebacks_summary` — оформление опротестований финансовых операций; - `new_pre_arbitration_summary` — перевод опротестований на этап Pre-Arbitration \(„Преарбитраж“\); - `new_arbitration_summary` — перевод опротестований на этап Arbitration \(„Арбитраж“\). По каждой из этих категорий формируются отдельные оповещения, включающие в себя следующий набор параметров: - `event` — категория отчётных событий\(в соответствии с указанными вариантами\); - `event_date` — дата отправки информацииоб отчётных событиях, в формате `YYYY-MM-DD`; - `project_id` — идентификатор проекта, к которому относятся отчётные события; - `merchant_id` — идентификатор мерчанта, к которому относятся отчётные события; - `chargeback_count` — количество опротестований, к которым относятся отчётные события. ``` {#codeblock_pns_p3q_tgc .language-json} { "event": "new_chargebacks_summary", "event_date": "2025-03-15", "project_id": "456", "merchant_id": "123", "chargeback_count": 5 } ``` При получении таких оповещений можно фиксировать полученную информацию и знакомиться с детальными сведениями через детализированные оповещения, через запросы к Data API \(такие, как `/chargeback/list` и `/chargeback/get`; [подробнее](ru_dbl_using_api.md)\) или через раздел **Чарджбэки** интерфейса Dashboard. ### Оповещения с детализированной информацией {#section_rzs_djq_tgc .section} Детализированные оповещения содержат информацию об опротестованиях, по которым за отчётное время в платформе были зарегистрированы профильные события. Эти события делятся на следующие категории: - `new_chargeback_details` — оформление опротестований финансовых операций; - `new_pre_arbitration_details` — перевод опротестований на этап Pre-Arbitration \(„Преарбитраж“\); - `new_arbitration_details` — перевод опротестований на этап Arbitration \(„Арбитраж“\); - `chargeback_cancelled_by_issuer` — отзыв опротестований эмитентом, с завершением рассмотрений в пользу мерчанта; - `chargeback_lost` — завершение работы с опротестованиями в пользу эмитента; - `chargeback_won` — завершение работы с опротестованиями в пользу мерчанта. По каждой из этих категорий формируются отдельные оповещения, включающие в себя следующий набор параметров: - `event` — категория отчётных событий\(в соответствии с указанными вариантами\); - `event_date` — дата отправки информацииоб отчётных событиях, в формате `YYYY-MM-DD`; - `project_id` — идентификатор проекта, к которому относятся отчётные события; - `merchant_id` — идентификатор мерчанта, к которому относятся отчётные события; - `total_chargebacks_count` — количество опротестований, к которым относятся отчётные события; - `chargebacks` — массив объектов с информацией о каждом из опротестований, к которому относятся отчётные события. **Прим.:** Параметры объектов массива `chargebacks` соответствуют параметрам объекта `Chargeback` Data API \([подробнее](https://api-data.ecommpay.com/)\) с разницей в названиях двух параметров: `chargeback_finalization_date` вместо `chb_completed_at` и `chargeback_status` вместо `status`. ``` {#codeblock_i4p_mxn_lgc .language-json} { "event": "chargeback_won", "event_date": "2025-03-13", "project_id": "12345", "merchant_id": "123", "total_chargebacks_count": 1, "chargebacks": [ { "chargeback_id": "82256", "case_id": "11384", "operation_id": "5033683310337533", "arn": "1", "card_type": "MC", "chargeback_status": "WON", "reason_code": "13.1", "report_date": "2025-03-07", "pre_arbitration_report_date": null, "arbitration_report_date": "2025-03-10", "chargeback_finalization_date": "2025-03-13 00:00:00", "respond_by": "2025-03-10 23:59:59", "charged_amount": -1, "charged_currency": "EUR", "credited_amount": 1, "credited_currency": "EUR" } ] } ``` При получении таких оповещений можно фиксировать полученную информацию и, когда это актуально, выполнять необходимые действия по работе с конкретными опротестованиями. ## Подключение {#ru_dbl_chargeback_callbacks_setup} Чтобы подключить программные оповещения об опротестованиях финансовых операций, со стороны мерчанта следует: 1. Согласовать с курирующим менеджером Ecommpay подключение этой возможностидля конкретных проектов, актуальные виды оповещений и адрес для приёма данных на стороне веб-сервиса \(следует учитывать, что может использоваться лишь один URL на один проект мерчанта\). 2. Получить от специалистов Ecommpay уведомление о подключениизапрошенной функциональности. 3. По возможности\(при наличии целевых событий по опротестованиям\) проверить получение согласованной информации. ## Использование {#ru_dbl_chargeback_callbacks_use} Порядок реагирования на каждое поступающее оповещение об опротестованиях со стороны веб-сервиса сводится к следующим шагам: 1. Принять оповещение и подтвердить его получение. Чтобы подтверждать получение оповещений, необходимо отправлять к платёжной платформе синхронные HTTP-сообщения: при приёме оповещений без ошибок — с кодом ответа `200 ОК`, в остальных случаях — с кодами ответов, соответствующими ошибкам, например `HTTP 500 Internal Server Error`, если оповещение поступило на некорректный URL веб-сервиса. Следует учитывать, что повторная отправка оповещений не предусмотренаи независимо от ответа, даже если он содержит информацию об ошибке, в следующую рассылку отправленная ранее информация не включается. 2. Выполнить необходимые действия в соответствии с порядком работы с опротестованиями \([подробнее](ru_faq_chargebacks.md#section_plz_g54_p5b)\) и спецификой работы веб-сервиса. ## Дополнительные материалы {#ru_dbl_chargeback_callbacks_useful_links} При работе с программными оповещениями об опротестованиях финансовых операций могут быть полезны следующие материалы: - [Работа с опротестованиями](ru_faq_chargebacks.md)— раздел о работе с опротестованиями финансовых операций, включая общую информацию, описание порядка работы и ответы на различные вопросы; - [Использование Data API](ru_dbl_api_protocol.md)— раздел о работе с программным интерфейсом получения информации о платежах и балансах, включая общую информацию, описание порядка работы и сведения о работе с каждой из конечных точек. --- # Использование Data API {#ru_dbl_api_protocol} статьи о возможностях и технических аспектах интерфейса Data API, который позволяет получать информацию об операциях, опротестованиях и балансах В этом разделе представлена информация о работе с Data API — программным интерфейсом платёжной платформы Ecommpay, который позволяет получать информацию об операциях, опротестованиях и балансах по используемым проектам. В состав раздела входят следующие статьи: - [Общая информация](ru_dbl_api_overview.md)— с вводными сведениями об интерфейсе Data API, его возможностях и порядке работы с ним. - [Организация взаимодействия](ru_dbl_api_interaction.md)— о том, как строится работа с платформой через Data API и как организовать получение необходимых данных. - [Получение данных](ru_dbl_using_api.md)— о том, как работать с отдельными конечными точками Data API, с описаниями и примерами структур данных в запросах и ответах. Спецификация интерфейса доступна по адресу [https://api-data.ecommpay.com](https://api-data.ecommpay.com/). - **[Общая информация](ru_dbl_api_overview.md)** статья с вводной информацией об интерфейсе Data API, его возможностях и порядке работы с ним - **[Организация взаимодействия](ru_dbl_api_interaction.md)** статья о том, как строится работа с платформой через Data API и как можно организовывать получение необходимых данных - **[Получение данных](ru_dbl_using_api.md)** статья о порядке работы с отдельными конечными точками Data API, с описаниями и примерами структур данных в запросах и ответах **На уровень выше:**[Dashboard](ru_dbl_about.md) --- # Общая информация {#ru_dbl_api_overview} статья с вводной информацией об интерфейсе Data API, его возможностях и порядке работы с ним Data API представляет собой программный интерфейс \(API\) платёжной платформы Ecommpay, позволяющий получать информацию о балансах, опротестованиях операций и самихоперациях, в том числе отдельно о мошеннических, с учётом прав доступа к конкретным проектам мерчанта. При этом права доступа определяются через специализированные токены учётных записей Dashboard, а условия для выборки данных задаются непосредственно в запросах к программному интерфейсу. Data API доступен по адресу `https://data.ecommpay.com/v1` и обеспечивает приём запросов в заданных конечных точках с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2. Спецификация интерфейса доступна по адресу [https://api-data.ecommpay.com](https://api-data.ecommpay.com/). Для работы с платёжной платформой Ecommpay через Data API на стороне мерчанта необходимо: 1. Обеспечить возможность отправки запросов и приёма ответов в соответствии со спецификацией Data API. 2. Предоставить пользователям, которым необходим доступ к Data API, возможность формировать токены и секретные ключи через интерфейс Dashboard. 3. Протестировать и запустить в работу подготовленные технические решения. **На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md) --- # Организация взаимодействия {#ru_dbl_api_interaction} статья о том, как строится работа с платформой через Data API и как можно организовывать получение необходимых данных **На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md) ## Схема работы {#ru_dbl_api_info} При использовании Data API взаимодействие между сервисом мерчанта и платёжной платформой Ecommpay строится на обмене сообщениями HTTP по принципу «запрос-ответ» — с запросами от сервиса и ответами от платформы. При этом применяется синхронная схема взаимодействия, в рамках которой в ходе одного сеанса HTTP обрабатывается один запрос и отправляется однократный ответ на него, с запрошенной информацией или с информацией об ошибке. ![](images/universal/dbl/ru_dbl_uml.svg) Такая схема работы обусловлена тем, что все запросы, принимаемые через Data API \(например, о балансах по проектам мерчанта\), подразумевают выполнение на стороне платёжной платформы, без задействования других сервисов и систем. Вместе с тем, с учётом сложности запросов и объёма подготавливаемых данных, время выполнения одного запроса на стороне платформы может существенно варьироваться: от десятков миллисекунд до нескольких минут \(как правило, не более пяти\). ## Порядок доступа к данным {#ru_dbl_api_token} ### Общая информация {#section_nlt_2nb_tmb .section} Для разграничения прав доступа при работе с Data API применяются специализированные токены. Каждый такой токен формируется через интерфейс Dashboard и ассоциируется с конкретной учётной записью и правами доступа этой записи к проектам мерчанта. Также в связке с токеном формируется секретный ключ, который должен применяться при подписывании запросов с использованием этого токена и проверке ответов, получаемых по таким запросам \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). ![](images/ecommpay/dbl/ru_dbl_api_token.svg "Сформированные токен и секретный ключ") На стороне платёжной платформы при работе с токенами учётных записей Dashboard обеспечивается соблюдение следующих правил: - каждый токен представляет собой строку из 30 символов в кодировке UTF-8; - каждый токен признаётся действительным с момента его формирования и до момента, пока не сформирован новый токен или не выполнена деактивация этого токена, при этом повторно активировать деактивированный токен нельзя; - для одной учётной записи может быть сформировано произвольное количество токенов, но при этом действительным всегда признаётся только один — сформированный последним; - любой действительный токен может использоваться произвольное количество раз без ограничений по времени действия; - в платформе обеспечивается синхронизация информации о правах доступа через учётную запись и ассоциированный с ней токен, благодаря чему при внесении изменений в права учётной записи не требуется формирование нового токена; - пользователи с правами управления токенами могут формировать и деактивировать токены для своих учётных записей без каких-либо технических ограничений; - удаление учётной записи пользователя не приводит к автоматической деактивации токена, но все права доступа к данным по этому токену отзываются, поэтому в ответ на запрос с таким токеном от платформы отправляется ответ с отказом в доступе \(`401 Authorization Required`\). На стороне мерчанта для работы с токенами и ключами могут определяться и обеспечиваться собственные дополнительные правила, в соответствии с применяемыми политиками безопасности. ### Предоставление права управления токенами {#section_xp4_y5l_5mb .section} Как и в случае с другими правами для работы с Dashboard, предоставить и отозвать право управления токенами может только тот пользователь, который обладает учётной записью с ролью Merchant admin. Чтобы предоставить право управления токенами, со стороны такого пользователя необходимо: 1. Перейти в раздел **Моя команда**. 2. Открыть карточку требуемой учётной записи, щёлкнув кнопку ![](images/universal/dbl/icon_pencil.svg) в соответствующей строке реестра. 3. Установить флажок **Управление API токенами**, щёлкнуть кнопку **Сохранить изменения** и подтвердить внесение изменений. ![](images/ecommpay/dbl/ru_dbl_user_api.svg) 4. Убедиться, что право предоставлено, проверив, что в карточке учётной записи установлен флажок **Управление API токенами**. Чтобы отозвать право управления токенами, необходимо перейти в раздел **Моя команда**, открыть карточку требуемой учётной записи, снять флажок **Управление API токенами**, сохранить изменения и убедиться, что они вступили в силу. В этом случае блокируется возможность формировать новый и деактивировать действительный токен для данной учётной записи, но остаётся возможность использовать действительный токен. ### Формирование и деактивация токена {#section_r3q_gnb_tmb .section} Формировать и деактивировать токены можно только для тех учётных записей, которым предоставлено право управления токенами. Чтобы сформировать и подготовить к работе токен и секретный ключ, пользователю с такой учётной записью необходимо: 1. Перейти в раздел **Мой профиль**, справа в главном меню интерфейса щёлкнув имя учётной записи и выбрав пункт **Мой профиль**. 2. Щёлкнуть кнопку **Новый токен** на панели **API-токены**. Кнопка **Новый токен** может отсутствовать, когда у используемой учётной записи нет права управления токенами. 3. Скопировать и сохранить значения токена и секретного ключа, с соблюдением внутренних правил информационной безопасности, действующих на стороне мерчанта. **Прим.:** Секретный ключ отображается в явном виде только до первого обновления страницы, после чего скрывается и более не является доступным. При необходимости, например если ключ был утерян или скомпрометирован, следует сформировать новую пару токен-ключ. Чтобы деактивировать токен, в профиле учётной записи на панели **API-токены** следует щёлкнуть кнопку **Удалить**. После этого токен становится недействительным и не может применяться для работы с Data API. ## Формат запросов {#ru_dbl_request_format} ### Общая информация {#section_tw5_bf1_xmb .section} В рамках взаимодействия с платёжной платформой через Data API все данные от сервиса мерчанта должны передаваться в *запросах* — сообщениях HTTP заданной структуры — с использованием метода POST. Описание общей структуры таких запросов представлено далее, а описание структур данных для конкретных запросов — [в спецификации интерфейса](https://api-data.ecommpay.com/). ### Структура {#section_oyr_nmh_smb .section} В каждом запросе к платёжной платформе должны передаваться следующие элементы в указанном порядке: - стартовая строка с указанием метода передачи запроса \(`POST`\) и конечной точки в интерфейсе Data API \(например, `v1/operations/get`\), протокола и его версии \(`HTTP/1.1`\); - заголовок с полем `Host`, содержащим доменное имя для запросов через Data API \(`data.ecommpay.com/v1`\); - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним. В дополнение к обязательному полю `Host` в заголовке можно использовать любые другие поля из числа допустимых [в HTTP версии 1.1](https://tools.ietf.org/html/rfc2616#page-31). Далее представлен пример запроса с рекомендуемым набором полей заголовка и обязательными параметрами.Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения. ``` POST v1/balance/get HTTP/1.1 User-Agent: curl/7.29.0 Host: data.ecommpay.com/v1 Accept: */* Content-Length: 179 Content-Type: application/x-www-form-urlencoded { "token":"ZOyTL5shY8...dQyplRPJYmGV7Kv", "signature":"...dQcIbv94Z0nPTYX9s2XqYrY9bzkfcBGQ==..." } ``` ### Параметры адресации {#section_b3q_bsx_thb .section} При формировании запросов необходимо указывать базовый и относительный адреса отправки. В качестве базового адреса для запросов через Data API используется доменное имя `data.ecommpay.com/v1`, а в качестве относительного — указатель конечной точки в интерфейсе в соответствии со спецификацией. **Прим.:** Полный адрес в этом случае представляет собой строку вида `https://{доменное имя платформы для запросов через Data API}/{указатель конечной точки}`. Например, адрес для запроса на получение балансов по проектам мерчанта выглядит как `https://data.ecommpay.com/v1/v1/balance/get`, но в таком виде при работе с POST-запросами полные адреса не используются. ### Тело {#section_kdx_ptx_thb .section} В теле сообщения должна содержаться JSON-строка с набором данных в формате `"<название параметра>": <значение параметра>`. Чтобы предотвратить утечку и подмену данных во время их передачи в платёжную платформу, в составе JSON-строки используются токен и подпись, а на транспортном уровне передачи — протокол TLS 1.2, обеспечивающий шифрование. Подробная информация о формировании токена представлена в пункте [Порядок доступа к данным](ru_dbl_api_interaction.md), а о формировании подписи — в разделе [Работа с подписью к данным](ru_platform_signature.md). ## Формат ответов {#ru_dbl_response_format} ### Общая информация {#section_e4m_cg1_xmb .section} Со стороны платёжной платформы получение запроса подтверждается отправкой *ответа* — HTTP-сообщения заданной структуры — в рамках того же сеанса. Передаваемые в ответе данные включают в себя: - запрошенную информацию, если запрос был выполнен; - сведения об ошибке, если запрос не может быть выполнен. Далее представлена информация об общей структуре ответов, а также о кодах, используемых для передачи информации о состоянии запроса. Описание структур данных для ответов на конкретные запросы представлено [в спецификации интерфейса](https://api-data.ecommpay.com/). ### Структура {#section_c2t_tbm_xhb .section} В каждом ответе от платформы содержатся следующие элементы в порядке перечисления: - стартовая строка с указанием протокола и его версии \(`HTTP/1.1`\), кода ответа и поясняющей фразы к коду \(например, `200 OK`\); - поля заголовка; - пустая строка — разделитель, отделяющая служебную информацию от тела сообщения; - тело сообщения, содержащее JSON-строку в кодировке UTF-8 в с набором данных. ### Коды ответа {#section_aj3_knq_13b .section} HTTP-код ответа используется в стартовой строке каждого ответа для передачи информации о результате выполнения запроса либо о причине обнаруженной ошибки. В работе с Data API применяются следующие коды ответов и пояснительные фразы. |Код с пояснением|Описание| |----------------|--------| |200 OK|Запрос успешно выполнен. В теле ответа передана запрошенная информация| |400 Bad Request|Запрос не может быть принят из-за синтаксической ошибки, обнаруженной при извлечении данных из JSON-строки, или из-за отсутствия в наборе извлечённых данных обязательных параметров \(кроме токена и подписи\)| |401 Authorization Required|Запрос не может быть принят из-за отказа в доступе, например если в запросе некорректно переданы токен или подпись либо указан идентификатор проекта, к которому нет доступа через используемый токен| |429 Too Many Requests|Запрос не может быть принят из-за превышения допустимой частоты запросов от одной учётной записи Dashboard. В таком случае следует выдержать паузу не менее трёх секунд перед повторной отправкой запроса. Также для предотвращения таких ситуаций следует учитывать и не превышать рекомендуемое ограничение в 60 запросов в минуту для одной учётной записи Dashboard| |500 Internal Error|Запрос не может быть выполнен из-за сбоя в платёжной платформе| ### Информация об ошибках {#section_gxv_5mh_smb .section} Если в запросе обнаружена ошибка, то в стартовой строке ответа указывается код ответа с причиной ошибки \(в примере далее — `401 Authorization Required`\), а в теле может указываться расширенная информация об этой ошибке: - поясняющая фраза к коду из заголовка ответа в параметре `name` \(в примере — `Authorization Required`\); - описание ошибки в параметре `message` \(если ошибка была обработана в платформе; в примере — `You have no access to project_id = 22`\); - служебный код в параметре `code` с фиксированным значением `0`; - код из заголовка ответа в параметре `status` \(в примере —`400`\). ``` POST /v1/balance/get HTTP/1.1 // Запрос от веб-сервиса на получение балансов HTTP/1.1 400 Bad Request // Ответ от платёжной платформы Server: nginx/1.14.2 Date: Thu, 17 August 2020 10:21:45 GMT Content-Type: application/json; charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive X-Powered-By: PHP/7.0.33 Expires: Thu, 17 August 2020 10:21:45 GMT Cache-Control: no-cache Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, POST, OPTIONS Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive, User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type { "name":"Bad Request", "message":"You have no access to project_id = 22", "code":"0", "status":"400" } ``` --- # Получение данных {#ru_dbl_using_api} статья о порядке работы с отдельными конечными точками Data API, с описаниями и примерами структур данных в запросах и ответах **На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md) ## Общая информация {#ru_dbl_using_api_overview} В структуре Data API используются разные конечные точки для получения разной информации: - `[/balance/get](ru_dbl_using_api.md)`— для получения информации о балансах по проектам мерчанта \(в настоящее время поддерживается получение информации только о балансах типа OUT\); - `[/chargeback/list](ru_dbl_using_api.md)` — для получения информации об опротестованиях, соответствующих заданным условиям; - `[/chargeback/get](ru_dbl_using_api.md)` — для получения информации по конкретному опротестованию; - `[/fraud/list](ru_dbl_using_api.md)` — для получения информации об операциях, признанных мошенническими; - `[/financial-reporting/operations](ru_dbl_using_api.md)` — для получения информации о финансовых результатах по операциям за заданный период \(включая информацию о начисленных комиссиях\); - `[/operations/get](ru_dbl_using_api.md)` — для получения информации о выполнении операций за заданный период; - `[/operations/get-by-payment](ru_dbl_using_api.md)` — для получения информации об операциях конкретного платежа. Общий порядок работы с каждой из этих конечных точек соответствует описанному в предыдущих статьях этого раздела. В этой статье представлена информация об особенностях работы с этими точками, дополняющая описания структур данных в спецификации интерфейса. ## Контроль балансов {#ru_dbl_using_api_balances} Для получения информации о балансах по проектам мерчанта следует отправлять запросы к конечной точке [/balance/get](https://api-data.ecommpay.com/balance/post-balance-get). В этих запросах должны указываться параметры `token` \(токен учётной записи Dashboard\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). В ответах на такие запросы содержатся сведения о текущем состоянии балансов типа OUT. Сведения о каждом балансе включают в себя наименование баланса и доступную сумму в валюте этого баланса, причём валюта указывается в качестве названия параметра, а сумма — в качестве значения параметра \(`"<валюта>": "<сумма>"`\). ```language-json // Тело запроса { "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature":"dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ==" } // Тело ответа { "balance": [ { "name": "Project_Cosmo1_balance_AUD", "AUD": "1010750" }, { "name": "Project_Cosmo1_balance_USD", "USD": "310099" }, { "name": "Project_Cosmo1_balance_EUR", "EUR": "113128" } ], "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w==" } ``` ## Общий контроль опротестований {#ru_dbl_using_api_chargeback_list} Для получения информации об опротестованиях \(chargebacks\), которые относятся к проектам мерчанта и соответствуют заданным условиям, следует отправлять запросы к конечной точке [/chargeback/list](https://api-data.ecommpay.com/chargeback/post-chargeback-list). В работе с этими запросами необходимо учитывать следующее: 1. В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). 2. Для фильтрации данных об опротестованиях могут использоваться любые из параметров в объекте `filter`. В этом объекте каждый из периодов задаётся как объект с двумя параметрами строкового типа `from` \(начало\) и `to` \(окончание\). Остальные параметры могут содержать как одно, так и несколько значений, заданных в виде массива или строки с разделением через запятую с пробелом. Исключением является параметр `provider_id`, который может быть задан только в виде массива. Параметры фильтрации можно указывать в произвольном порядке. Если они не указываются вовсе, в ответе от платёжной платформы отправляются данные обо всех опротестованиях по проектам, к которым есть доступ у используемой учётной записи. В объекте `filter` могут указываться следующие объекты и параметры: - `report_date` — период, в котором информация об опротестовании впервые поступила в платформу \(формат каждой границы периода — `ГГГГ-ММ-ДД`\); - `respond_by` — период, к которому относится последний день срока предоставления ответа по опротестованию \(формат каждой границы периода — `ГГГГ-ММ-ДД чч:мм:сс` с возможностью не указывать время\); - `chb_completed_at` — период, в котором опротестованию присвоен итоговый статус \(формат каждой границы периода — `ГГГГ-ММ-ДД чч:мм:сс` с возможностью не указывать время\); - `project_id` — идентификатор проекта; - `chargeback_id` — идентификатор опротестования, полученный от Ecommpay; - `chargeback_stage` — этап работы с опротестованием \(`Chargeback`, `Representment`, `Pre-Arbitration attempt`, `Pre-Arbitration response` и `Arbitration`; [подробнее об этапах](ru_faq_chargebacks.md#section_plz_g54_p5b)\); - `arn` — acquirer reference number \(идентификатор операции, присвоенный эквайером\); - `card` — номер платёжной карты, использованной при проведении платежа; - `card_type` — код платёжной системы \(`visa` для Visa и `mc` для Mastercard\); - `reason_code` — числовой код причины опротестования, полученный от платёжной системы; - `operation_id` — идентификатор оспариваемой операции; - `status` — статус опротестования. 3. Для ограничения количества записей с информацией об опротестованиях, возвращаемых в одном ответе, можно использовать объект `pagination` с двумя параметрами: `limit` — максимальное количество возвращаемых записей \(не меньше `1`\) и `offset` — величина сдвига для отбора записей \(с отсчётом с `0`\). Например, если необходимо получить информацию о 5 опротестованиях, пропустив первые 20, то в запросе можно указать `"limit": 5` и `"offset": 20`. При отсутствии этих параметров используются значения по умолчанию: `limit` — `20`, `offset` — `0`. В ответе на каждый из таких запросов содержатся данные об опротестованиях с учётом условий, заданных в запросе. ```language-json // Тело запроса { "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv", "filter": { "report_date": { "from": "2024-01-01", "to": "2024-02-01" }, "status": [ "WON", "PARTIALLY WON" ] }, "signature": "DNqOZOCxNlXu3bENrDPuEE8fSJLWDNM/...UqhiEUoC5VcNFw==" } // Тело ответа { "operations": [ { "chargeback_id": "11201", "charged_amount": "5000", "channel_amount": "5000", "case_id": "142", "project_id": "1234", "operation_id": "12330123485431", "report_date": "2024-01-31", "respond_by": "2024-02-04 23:59:59", "rev_date": null, "tr_date_time": "2024-01-13 17:00:56", "chb_completed_at": "2024-02-21 00:00:00", "chb_amount": "50.00", "chb_settlement_amount": "50.00", "rev_indicator": null, "chb_ccy": "USD", "chb_settlement_ccy": "USD", "charged_currency": "USD", "channel_currency": "USD", "eci_sli": "7", "reason_code": "10.4", "card_type": "VISA", "merchant_id": "10000123", "card": "431422******0056", "arn": "74312342013012340041234", "status": "WON", "chb_amount_in_usd": "50.0000", "merchant_name": "Cosmoshop_on_Mars", "order_id": "1234123412345", "operation_type": "sale", "auth_code": "061230", "card_holder": "JANE DOE", "issuer_country": "UK", "chargeback_stage": "Arbitration", "pre_arbitration_report_date": "2024-02-06", "pre_arbitration_amount": "50.00", "pre_arbitration_ccy": "USD", "arbitration_report_date": "2024-03-06", "arbitration_amount": "50.00", "arbitration_ccy": "USD", "representment_amount": "50.00", "representment_ccy": "USD" }, ... ], "signature": "k4iXC84dfwevT+...dS056fssBGIw==" } ``` ## Контроль отдельных опротестований {#ru_dbl_using_api_chargeback_get} Для получения информации об отдельных опротестованиях \(chargebacks\) следует использовать запросы к конечной точке [/chargeback/get](https://api-data.ecommpay.com/chargeback/post-chargeback-get). В работе с этими запросами необходимо учитывать следующее: 1. В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). 2. Дополнительно должен указываться по крайней мере один из следующих идентификаторов в объекте `filter`: - `chargeback_id` — идентификатор опротестования, полученный от Ecommpay; - `arn` — идентификатор операции, присвоенный эквайером \(acquirer reference number\); - `operation_id` — идентификатор операции в платёжной платформе. Если в запросе не указан ни один из этих идентификаторов или указаны противоречащие друг другу, то в ответ выдаётся ошибка. В ответе на корректный запрос содержатся данные о конкретном опротестовании. ```language-json // Тело запроса { "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv", "filter": { "operation_id": 87980010093051 }, "signature": "VoOJxpMge0uBN22gZxf3BhE+5wlCaU...y+KM1lQ==" } // Тело ответа { "chargeback": { "chargeback_id": "11201", "charged_amount": "5000", "channel_amount": "5000", "case_id": "142", "project_id": "1234", "operation_id": "12330123485431", "report_date": "2024-01-31", "respond_by": "2024-02-04 23:59:59", "rev_date": null, "tr_date_time": "2024-01-13 17:00:56", "chb_completed_at": "2024-02-21 00:00:00", "chb_amount": "50.00", "chb_settlement_amount": "50.00", "rev_indicator": null, "chb_ccy": "USD", "chb_settlement_ccy": "USD", "charged_currency": "USD", "channel_currency": "USD", "eci_sli": "7", "reason_code": "10.4", "card_type": "VISA", "merchant_id": "10000123", "card": "431422******0056", "arn": "74312342013012340041234", "status": "WON", "chb_amount_in_usd": "50.00", "merchant_name": "Cosmoshop_on_Mars", "order_id": "1234123412345", "operation_type": "sale", "auth_code": "061230", "card_holder": "JANE DOE", "issuer_country": "UK", "chargeback_stage": "Arbitration", "pre_arbitration_report_date": "2024-02-06", "pre_arbitration_amount": "50.00", "pre_arbitration_ccy": "USD", "arbitration_report_date": "2024-03-06", "arbitration_amount": "50.00", "arbitration_ccy": "USD", "representment_amount": "50.00", "representment_ccy": "USD" }, "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhDr...gtmmKfB2g==" } ``` ## Контроль мошеннических операций {#ru_dbl_using_api_fraud} Для получения информации об операциях, признанных мошенническими на стороне платёжных систем, следует отправлять запросы к конечной точке [/fraud/list](https://api-data.ecommpay.com/fraud/post-fraud-list). Стоит учитывать, что с помощью таких запросов нельзя получать данные об операциях, признанными подозрительными на стороне Ecommpay, а в работе с этими запросами необходимо учитывать следующее: 1. В каждом запросе должны указываться параметры `token` \(токен учётной записи Dashboard с ролью `Risks` или `Merchant admin` и правами доступа ко всем целевым проектам\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). 2. Для фильтрации данных об операциях могут использоваться любые из параметров в объекте `filter`: - `received_on` — период, в который в платёжной платформе зарегистрирована информация о признании операции мошеннической на стороне платёжной системы; - `purchase_date` — период, в котором операции присвоен итоговый статус; - `fraud_report_date` — период, в котором эмитент был уведомлён о признании операции мошеннической; - `issuer_country` — код страны эмитента, выпустившего карту \(массив из одного или нескольких кодов в формате ISO 3166-1 alpha-2\); - `has_chargebacks` — указатель наличия по крайней мере одного зарегистрированного в платёжной платформе опротестования по операции, признанной мошеннической; - `customer_id` — идентификатор пользователя в рамках проекта; - `card_type` — код платёжной системы \(`mc` для Mastercard и `visa` для Visa\). В этом объекте любой период должен задаваться через массив строк с границами временного интервала, например `"purchase_date": [ "2025-12-31 00:00:00", "2026-01-07 23:59:59" ]`. 3. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, можно использовать объект `pagination` с двумя параметрами: `limit` — максимальное количество возвращаемых записей \(не меньше `1`\) и `offset` — величина сдвига для отбора записей \(с отсчётом с `0`\). Например, если необходимо получить информацию о 5 операциях, пропустив первые 20, то в запросе можно указать `"limit": 5` и `"offset": 20`. При отсутствии этих параметров используются значения по умолчанию: `limit` — `20`, `offset` — `0`. В ответе на каждый из таких запросов содержатся данные об операциях с учётом условий, заданных в запросе. ```language-json // Тело запроса { "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv", "signature": "dfsder34fuk7sJ...grdfht5gJg==", "filter": { "received_on": [ "2026-01-01 00:00:00", "2026-02-01 23:59:59" ], "issuer_country": [ "GB" ] }, "pagination": { "limit": 5, "offset": 20 } } // Тело ответа { "operations": [ { "payment_id": "cosmopayment78", "operation_id": 6435212169999, "tr_amount": "580.00", "tr_ccy": "USD", "account_number": "431422******0056", "payment_method_type": "visa", "row_updated_at": "2026-01-01 05:30:30", "customer_id": "earthling1232400", "project_name": "cosmoshop.earth", "project_id": "123", "arn": "40216364365007272011473", "fraud_type": "6", "fraud_report_date": "2026-02-10", "issuer_country": "GB", "received_on": "2026-02-11", "purchase_date": "2026-02-01", "channel_amount_in_usd": "580.00", "issuer_bank_name": "Intergalactic Bank", "bin": "123456", "country_by_ip": "GB", "customer_email": "earthling@earth.earth", "report_and_purchase_date_difference": 9 } ], "signature": "k4iXC84dfwevT+...dS056fssBGIw==" } ``` ## Общий контроль финансовых результатов операций {#ru_dbl_using_api_financial-statements} Для получения информации о финансовых результатах по операциям за заданный период \(включая информацию о начисленных комиссиях\) следует отправлять запросы к конечной точке [/financial-reporting/operations](https://api-data.ecommpay.com/operations/post-financial-reporting-operations). Эта информация может дополнять информацию о выполнении операций \([подробнее](ru_dbl_using_api.md)\) и использоваться для итогового анализа и сверок. В работе с запросами на получение информации о финансовых результатах по операциям необходимо учитывать следующее: 1. В каждом запросе должны использоваться следующие объекты и параметры: - `token` — токен учётной записи Dashboard; - `signature` — подпись запроса, составленная после указания целевых параметров \([подробнее](ru_platform_signature.md)\); - `operation_completed_at` — объект с информацией о границах временно́го интервала, в который было закончено выполнение целевых операций \(с учётом последних действий и обновлений информации по ним\): - `from` — дата и время начала интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`; - `to` — дата и время окончания интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`; **Прим.:** Можно запрашивать информацию только об операциях, завершённых за последние 30 дней. - `tz` — указатель часового пояса, задаваемый через время смещения в формате UTC \(например, +10:30\) или через название пояса в соответствии с базой данных IANA Time Zone Database \(например, Asia/Singapore\). 2. Для фильтрации операций по проектам и \(или\) провайдерам используются массивы `project_id` и `provider_id`, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указаны эти массивы, в ответе от платёжной платформы отправляются данные об операциях по всем проектам \(к которым есть права доступа через используемый токен\) и всем провайдерам, задействованным при выполнении этих операций. Если необходимо получить данные по конкретным проектам и провайдерам, в массивах `project_id` и `provider_id` следует указать их идентификаторы \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `4, 12`\). 3. Для получения информации о конкретных операциях используется массив `operation_id`. По умолчанию, если в запросе не указан этот массив, в ответе от платёжной платформы отправляются данные обо всех операциях, соответствующих заданным условиям. Если необходимо получить данные по конкретным операциям \(одной или нескольким\), в массиве `operation_id` следует указать идентификаторы этих операций \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `6435212162442, 6435212162443`\). 4. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр `limit`. Этот параметр может принимать значения в диапазоне `0`–`1000` и по умолчанию равен `1000`, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения. При необходимости получить информацию более чем о тысяче операций, следует отправлять группу запросов и в каждом из этих запросов использовать параметр `offset`. Этот параметр определяет величину сдвига для отбора операций. Если в запросе указываются оба параметра — и `limit`, и `offset`, — то сначала пропускаются записи об операциях в количестве, заданном значением `offset`, а затем в ответ включаются записи о следующих операциях в количестве, не превышающем значения `limit`. Например, если необходимо получить информацию о `1125` операциях, то в первом запросе можно указать `"limit": 1000` и `"offset": 0`, а во втором — `"limit": 125` и `"offset": 1000`. В ответе на каждый из таких запросов содержатся данные об операциях за указанный период с учётом заданных условий. ```language-json // Тело запроса на получение данных о 1000 операциях (с отсчётом от 0) { "project_id": [11], "operation_completed_at": { "from": "2024-09-01 00:00:00", "to": "2024-09-30 23:59:59" }, "tz": "Indian/Mauritius", "limit": 1000, "offset": 0, "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature": "YsrkgdBr5peXJgJ...glVmsd0f==" } // Тело ответа на запрос { "data": [ { "operation_completed_at": "2024-09-29T22:08:19+0000", "transaction_id": "81194009089601", "operation_id": "81194009122865", "provider_payment_id": "0040000028207224", "payment_id": "1994-1312", "arn": "70114165164100000032105", "rrn": "451912040334", "auth_appr_code": "611887", "operation_type": "sale", "operation_status": "success", "tran_region": "domestic", "tariff_region": "EU", "proc_region": "Visa Europe", "security_level": "SEC", "operation_amount": 2098.00, "operation_currency": "GBP", "billing_conversion_rate": 0.00, "billing_amount": 2098.00, "billing_currency": "GBP", "total_interchange_fee": -4.20, "total_scheme_fee": -0.64, "auth_msc_fee": 0.000000, "clearing_msc_fee": -3.785649, "total_msc_fee": -3.78, "hold_amount": 0.00, "project_id": 11, "project_url": "https://www.company.com", "merchant_name": "COMPANY NAME", "mid": "70000000", "terminal_id": "70000000", "mcc_code": "4722", "legal_country": "GB", "payment_method_name": "visa", "product_type": "Consumer", "account_funding_source": "debit", "account_number": "475144******1111", "card_product": "Visa classic", "issuer_country": "GB", "customer_id": "1436462", "card_holder": "CARD HOLDER" }, // сведения об остальных операциях... ], "signature": "sncpEB75H...3jTS==" } ``` ## Общий контроль выполнения операций {#ru_dbl_using_api_operations} Для получения информации о выполнении операций за заданный период следует отправлять запросы к конечной точке [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get). Эту информацию можно использовать в ознакомительных целях и для развёрнутого анализа выполнения операций, в то время как для итогового анализа и сверок можно использовать информацию о финансовых результатах по операциям \(с учётом начисленных комиссий; [подробнее](ru_dbl_using_api.md)\). В работе с запросами на получение информации о выполнении операций необходимо учитывать следующее: 1. В каждом запросе должны использоваться следующие объекты и параметры: - `token` — токен учётной записи Dashboard; - `signature` — подпись запроса, составленная после указания целевых параметров \([подробнее](ru_platform_signature.md)\); - `interval` — объект с информацией о границах временно́го интервала, к которому относятся целевые операции \(с учётом последних действий и обновлений информации по ним\): - `from` — дата и время начала интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`; - `to` — дата и время окончания интервала, в формате `ГГГГ-ММ-ДД чч:мм:сс`. **Прим.:** Если от имени одной учётной записи Dashboard в течение 10 секунд в платформу поступает более одного запроса на информацию за период, превышающий 180 дней, то эти запросы обрабатываются поэтапно, с тайм-аутом в 10 секунд. 2. Для фильтрации операций по проектам используется массив `project_id`, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указан этот массив, в ответе от платёжной платформы отправляются данные об операциях по всем проектам, к которым есть права доступа через используемый токен. Если необходимо получить данные по конкретным проектам, в массиве `project_id` следует указать идентификаторы этих проектов \(через запятую с пробелом, если необходимо указать более одного идентификатора; например, `4, 12`\). 3. Для указания часового пояса используется параметр `tz`. По умолчанию, если в запросе не указан этот параметр, используется часовой пояс учётной записи Dashboard, ассоциированной с токеном из параметра `token`. Выбор часового пояса с помощью этого параметра влияет на то, какие операции попадают в заданный интервал времени в объекте `interval`, и на значения параметров в ответе, связанных с датой и временем, например `operation_created_at` и `operation_completed_at`. Часовой пояс в параметре `tz` указывается через время смещения в формате UTC \(например, `+10:30`\) или через название в соответствии с базой данных часовых поясов IANA Time Zone Database \(например, `Asia/Singapore`\). 4. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр `limit`. Этот параметр может принимать значения в диапазоне `0`–`1000` и по умолчанию равен `1000`, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения. При необходимости получить информацию более чем о тысяче операций, следует отправлять группу запросов и в каждом из этих запросов использовать параметр `offset`. Этот параметр определяет величину сдвига для отбора операций. Если в запросе указываются оба параметра — и `limit`, и `offset`, — то сначала пропускаются записи об операциях в количестве, заданном значением `offset`, а затем в ответ включаются записи о следующих операциях в количестве, не превышающем значения `limit`. Например, если необходимо получить информацию о `1125` операциях, то в первом запросе можно указать `"limit": 1000` и `"offset": 0`, а во втором — `"limit": 125` и `"offset": 1000`. 5. Для указания состава возвращаемых данных об операциях используется массив `fields`. По умолчанию, если в запросе не указан этот массив, в ответе от платёжной платформы отправляется типовой набор параметров по каждой операции. Если же необходимо получить нетиповой набор параметров, то в качестве элементов массива `fields` следует указать названия этих параметров. Названия целевых параметров указываются в массиве через запятую с пробелом, при этом их можно указывать в произвольном порядке, но в ответах используется фиксированный порядок, заданный в спецификации. Полный перечень параметров, которые могут выдаваться в ответах на запросы этого типа, также представлен в спецификации — в виде параметров объекта `operations` в описании формата ответа на запрос к конечной точке [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get). В этом описании параметры приводятся в фиксированном порядке, который не может изменяться, при этом параметры, используемые по умолчанию, отмечены как обязательные. 6. Для получения данных об операциях по конкретным типам и \(или\) статусам используются параметры `operation_type` и `operation_status`.По умолчанию, если в запросе не указаны эти параметры, в ответе отправляются данные об операциях всех допустимых типов и статусов. Если указывать эти параметры, то в качестве их значений следует использовать названия конкретных типов и статусов операций, через запятую с пробелом при указании более чем одного названия. Актуальный перечень типов и статусов операций представлен [в модели проведения платежей](ru_platform_payment_model.md). Каждый из параметров `operation_type` и `operation_status` может задаваться как строка \(если необходимо указать одно значение\) и как массив строк \(если необходимо указать одно или множество значений\). 7. Для фильтрации данных об операциях с учётом идентификаторов и \(или\) адресов электронной почты пользователей используются параметры `customer_id` и `customer_email`. По умолчанию, если в запросе не указаны эти параметры, в ответе отправляются данные об операциях с любыми идентификаторами и адресами электронной почты пользователей. Если указывать эти параметры, то следует учитывать, что параметр `customer_id` может задаваться как строка \(если необходимо указать одно значение\) и как массив строк \(если необходимо указать одно или множество значений\), а параметр `customer_email` может задаваться только как строка. В ответе на каждый из таких запросов содержатся данные об операциях за указанный период с учётом заданных условий. Если состав параметров, используемый в ответах по умолчанию, подходит для решения целевых задач, можно использовать этот состав и не указывать в запросах массив `fields`. ```language-json // Тело запроса на получение данных о 1000 операциях (с отсчётом от 0) { "project_id":[ 0, 11 ], "interval": { "from":"2024-04-04 00:00:00", "to":"2024-04-28 23:59:59" }, "limit": 1000, "offset": 0, "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature":"yPu0wYr2BoV5...MzQtRkvdC0y==" } // Тело запроса на получение данных о следующих 125 операциях (с отсчётом от 1000) { "project_id":[ 0, 11 ], "interval": { "from":"2024-04-04 00:00:00", "to":"2024-04-28 23:59:59" }, "limit": 125, "offset": 1000, "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature":"sd0fr5YsdBVmJ...grkglpeXJg==" } // Тело ответа на первый запрос { "operations": [ // сведения об операции { "project_id": "11", "operation_id": "6435212162442", "payment_id": "EP06c1-b285", "operation_type": "sale", "operation_status": "success", "account_number": "431422******0056", "customer_ip": "192.0.2.255", "payment_method_name": "visa", "payment_method_type": "visa", "payment_description": "", "operation_created_at": "2024-04-04T08:28:47+00:00", "provider_date": "2024-04-04 10:34:24", "shipment_date": "", "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1000, "currency": "USD" }, "arn": "12304191169003210000234", "rrn": "001045563840", "payment_provider_code": "0", "payment_provider_message": "Success" }, // сведения о следующей операции { "project_id": "11", "operation_id": "6435212162442", "payment_id": "EP06c1-b285", "operation_type": "sale", "operation_status": "success", "account_number": "431422******0056", "customer_ip": "198.51.100.0", "payment_method_name": "visa", "payment_method_type": "visa", "payment_description": "", "operation_created_at": "2024-04-04T08:28:47+00:00", "provider_date": "2024-04-04 10:34:24", "shipment_date": "", "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1000, "currency": "USD" }, "arn": "30407191169003210010678", "rrn": "128905563823", "payment_provider_code": "0", "payment_provider_message": "Success" }, // сведения об остальных операциях ... ], "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw==" } ``` Если состав параметров, используемый в ответах по умолчанию, не подходит для решения целевых задач, можно определять необходимый состав параметров через массив `fields`. Если при этом необходимо также применять фильтрацию операций, можно задавать критерии фильтрации через различные параметры, например `operation_type`, `operation_status` и `customer_email`. ```language-json // Тело запроса на получение данных: { "project_id":[ 0, 11 ], "interval": { "from":"2024-04-04 00:00:00", "to":"2024-04-19 23:59:59" }, "operation_type": [ "sale", "refund" ], "operation_status": [ "success", "decline" ], "customer_email": "astronaut@earth.station", "token":"qOnHY86dfhpxdghEBb7HSLbe", "fields": [ "operation_id", "operation_type", "operation_status", "sum_initial.amount", "sum_initial.currency", "customer_email" ], "signature":"vtv5TN6aWQV...5QBjpe8Dsv==" } // Тело ответа: { "operations": [ // сведения об операции { "operation_id": "12347892", "operation_type": "sale", "operation_status": "success", "sum_initial": {     "amount": 1000,     "currency": "USD" }, "customer_email": "astronaut@earth.station" }, // сведения об остальных операциях ... ], "signature": "sdkf45rt73jncpEB75HTS==" } ``` ## Контроль операций по отдельным платежам {#ru_dbl_using_api_operations_by_payment} Для получения информации обо всех операциях по конкретному платежу следует использовать запрос к конечной точке [/operations/get-by-payment](https://api-data.ecommpay.com/operations/post-operations-get-by-payment). В этом запросе должны указываться параметры `payment_id` \(идентификатор целевого платежа\), `token` \(токен учётной записи Dashboard\) и `signature` \(подпись; [подробнее](ru_platform_signature.md)\). В ответе на такой запрос содержатся сведения об операциях целевого платежа. ```language-json // Тело запроса { "payment_id":"PID_25467851461-2147", "token":"VmJQhaXILAnZWTKmqwSd3j", "signature":"JM+YWmTL7uGn26IgZWT...yaq030+eNXVtJjjtgrkglpeXJg==" } // Тело ответа { "operations": [ { "arn": "", "operation_completed_at": "2024-11-22T13:13:04+00:00", "operation_type": "refund", "operation_id": "2747253065470", "amount": 221, "currency": "USD", "operation_created_at": "2024-11-22T13:13:04+00:00", "rrn": "803817399309", "payment_provider_code": "0", "payment_provider_message": "Success" }, { "arn": "", "operation_completed_at": "2024-11-22T13:09:03+00:00", "operation_type": "capture", "operation_id": "2747253065469", "amount": 1621, "currency": "USD", "operation_created_at": "2024-11-22T13:09:03+00:00", "rrn": "000000248370", "payment_provider_code": "0", "payment_provider_message": "Success" }, { "arn": "", "operation_completed_at": "2024-11-22T13:06:40+00:00", "operation_type": "auth", "operation_id": "2747253065468", "amount": 200, "currency": "USD", "operation_created_at": "2024-11-22T13:06:38+00:00", "rrn": "000047769105", "payment_provider_code": "0", "payment_provider_message": "Success" } ], "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7b...y1WihDJ4ljz/Hv7NkQFujSnvw==" } ``` --- # Data API {#data_api} **На уровень выше:**[Использование Data API](ru_dbl_api_protocol.md) { "swagger": "2.0", "info": { "version": "2.1.1", "title": "Data API", "description": "Ecommpay Data API is an interface for retrieving information about merchant operations in the payment platform." }, "host": "data.ecommpay.com", "basePath": "/v1", "schemes": [ "https" ], "paths": { "/balance/get": { "post": { "operationId": "POST_balance-get", "summary": "/balance/get", "tags": [ "Balance" ], "description": "Request to retrieve merchant contracts balances.", "consumes": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token generated by Ecommpay Dashboard for user account." }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." } }, "required": [ "token", "signature" ] }, "x-examples": { "application/json": { "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature": "dQcIbv94Z0nPTYX9glSCi...jqInXYrY9zkfcBGQ==" } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ApiBalanceList" }, "examples": { "application/json": { "balance": [ { "name": "Project_Cosmo1_balance_USD", "USD": "1010750" }, { "name": "Project_Cosmo1_balance_SGD", "SGD": "310099" }, { "name": "Project_Cosmo1_balance_EUR", "EUR": "113128" } ], "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w==" } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } }, "/chargeback/get": { "post": { "operationId": "POST_chargeback_get", "summary": "/chargeback/get", "tags": [ "Chargeback" ], "description": "Request to retrieve a single chargeback data.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token generated in the Ecommpay Dashboard for the user account." }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." }, "filter": { "type": "object", "description": "Object used for finding a chargeback by various identifiers. The request must contain one of the following identifiers.", "properties": { "chargeback_id": { "type": "integer", "description": "Chargeback ID provided by Ecommpay." }, "arn": { "type": "string", "description": "Acquirer reference number used for clearing." }, "operation_id": { "type": "integer", "description": "Operation ID provided by Ecommpay." } } } }, "required": [ "token", "signature" ] }, "x-examples": { "example-1": { "token": "r8u26__LapNUP5rPIiOuVaMFiwPWI3", "chargeback_id": 11201, "arn": "74312342013012340041234", "operation_id": 1234123412345, "signature": "DNqOZOCxNlXu3bENrDPuEE8...fSJLWDNM/CE8==" } } } ], "responses": { "200": { "description": "OK", "schema": { "type": "object", "properties": { "signature": { "type": "string" }, "chargeback": { "$ref": "#/definitions/Chargeback" } } }, "examples": { "example-1": { "chargeback": { "chargeback_id": "11201", "charged_amount": "50.00", "channel_amount": "50.00", "case_id": "142", "project_id": "1234", "operation_id": "12330123485431", "report_date": "2024-01-31", "respond_by": "2024-02-04 23:59:59", "rev_date": "null", "tr_date_time": "2024-01-13 17:00:56", "chb_completed_at": "2024-02-21 00:00:00", "chb_amount": "50.00", "chb_settlement_amount": "50.00", "rev_indicator": "null", "chb_ccy": "USD", "chb_settlement_ccy": "USD", "charged_currency": "USD", "channel_currency": "USD", "eci_sli": "7", "reason_code": "10.4", "card_type": "VISA", "merchant_id": "10000123", "card": "431422******0056", "arn": "74312342013012340041234", "status": "string", "chb_amount_in_usd": "WON", "merchant_name": "Cosmoshop_on_Mars", "order_id": "1234123412345", "operation_type": "sale", "auth_code": "061230", "card_holder": "JANE DOE", "issuer_country": "UK", "chargeback_stage": "Arbitration", "pre_arbitration_report_date": "2024-02-06", "pre_arbitration_amount": "50.00", "pre_arbitration_ccy": "USD", "arbitration_report_date": "2024-03-06", "arbitration_amount": "50.00", "arbitration_ccy": "USD", "representment_amount": "50.00", "representment_ccy": "USD" }, "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhdDrzx10vzg/gtmmKfB2g==" } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } }, "/chargeback/list": { "post": { "operationId": "POST_chargeback_list", "summary": "/chargeback/list", "tags": [ "Chargeback" ], "description": "Request to retrieve the list of chargebacks.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token generated in the Ecommpay Dashboard for the user account.\t" }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." }, "filter": { "type": "object", "description": "Object used for filtering chargeback data by various parameters.\n\nThe first three parameters are specified as time intervals and refer to different dates. The report_date parameter specifies the date when the chargeback was registered in the payment platform (format: \"YYYY-MM-DD\"). The respond_by parameter specifies the deadline for submitting a response to the chargeback (format: \"YYYY-MM-DD HH-MM-SS\"). The chb_completed_at parameter specifies the date when the chargeback received one of the final statuses (format: \"YYYY-MM-DD HH-MM-SS\").\n\nThe rest of the parameters can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value). If the array is omitted, the payment platform returns information for all available values.", "properties": { "report_date": { "$ref": "#/definitions/DateRange" }, "respond_by": { "$ref": "#/definitions/DateRange" }, "chb_completed_at": { "$ref": "#/definitions/DateRange" }, "project_id": { "type": "array", "description": "One or more project IDs provided by Ecommpay.", "items": { "type": "string" } }, "chargeback_id": { "description": "Chargeback ID (as a string) or an array of one or more chargeback IDs.", "type": [ "string", "array" ], "items": { "type": "string" } }, "chargeback_stage": { "description": "Chargeback stage (as a string) or an array of one or more chargeback stages.", "type": [ "string", "array" ], "items": { "type": "string" } }, "arn": { "description": "ARN (as a string) or an array of one or more ARNs. Acquirer reference number used for clearing.", "type": [ "string", "array" ], "items": { "type": "string" } }, "card": { "description": "Card number (as a string) or an array of one or more card numbers used by the customers.", "type": [ "string", "array" ], "items": { "type": "string" } }, "card_type": { "description": "Bank card type (as a string) or an array of one or more bank card types.", "type": [ "string", "array" ], "items": { "type": "string" } }, "reason_code": { "type": [ "string", "array" ], "description": "Numerical chargeback reason code (as a string) or an array of one or more reason codes.", "items": { "type": "string" } }, "operation_id": { "description": "Disputed operation ID provided by Ecommpay or an array of one or more IDs.", "type": [ "string", "array" ], "items": { "type": "string" } }, "status": { "description": "Current status of the chargeback (as a string) or an array of one or more statuses.", "type": [ "string", "array" ], "items": { "type": "string" } } } }, "pagination": { "type": "object", "description": "Object used to restrict the number of chargebacks which are returned in a single response.", "properties": { "limit": { "type": "integer", "description": "Number of entries to return per request. Default value is 20. Maximum value is not set." }, "offset": { "type": "integer", "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0." } } } }, "required": [ "token", "signature" ] }, "x-examples": { "example-1": { "token": "r8u26__LapNUPhbhc000VaMFiwPWI3", "filter": { "chargeback_id": [ 44661, 93028 ] }, "signature": "cNIomz5eEZglWmGOQhcpV...vtWQQglfaDhJsUVujIA==" } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ChargebackList" }, "examples": { "example-1": { "chargebacks": [ { "chargeback_id": "44661", "charged_amount": "5000", "channel_amount": "5000", "case_id": "10002", "project_id": "900", "operation_id": "50000010000001", "report_date": "2024-01-31", "respond_by": "2024-02-04 23:59:59", "rev_date": null, "tr_date_time": "2024-01-13 17:39:56", "chb_completed_at": "2024-02-21 00:00:00", "chb_amount": "50.00", "chb_settlement_amount": "50.00", "rev_indicator": null, "chb_ccy": "USD", "chb_settlement_ccy": "USD", "charged_currency": "USD", "channel_currency": "USD", "eci_sli": "7", "reason_code": "10.4", "card_type": "VISA", "merchant_id": "70000004", "card": "400000******0119", "arn": "70000022010000100000003", "status": "WON", "chb_amount_in_usd": "50.0000", "merchant_name": "COSMOSHOP", "order_id": "3245678KSDFVGK", "operation_type": "sale", "auth_code": "000010", "card_holder": "COSMO USER", "issuer_country": "GB", "chargeback_stage": "Arbitration", "pre_arbitration_report_date": "2024-02-06", "pre_arbitration_amount": "50.00", "pre_arbitration_ccy": "USD", "arbitration_report_date": "2024-03-06", "arbitration_amount": "50.00", "arbitration_ccy": "USD", "representment_amount": "50.00", "representment_ccy": "USD" }, { "chargeback_id": "93028", "charged_amount": "5000", "channel_amount": "5000", "case_id": "14000", "project_id": "900", "operation_id": "67000010000001", "report_date": "2024-01-31", "respond_by": "2024-02-04 23:59:59", "rev_date": null, "tr_date_time": "2024-01-12 12:22:07", "chb_completed_at": "2024-02-21 00:00:00", "chb_amount": "50.00", "chb_settlement_amount": "50.00", "rev_indicator": null, "chb_ccy": "USD", "chb_settlement_ccy": "USD", "charged_currency": "USD", "channel_currency": "USD", "eci_sli": "7", "reason_code": "10.4", "card_type": "VISA", "merchant_id": "70000001", "card": "431422******0056", "arn": "70000022010000100000006", "status": "WON", "chb_amount_in_usd": "50.0000", "merchant_name": "COSMOSHOP", "order_id": "8327588FDJNFIH", "operation_type": "sale", "auth_code": "000005", "card_holder": "COSMO USER", "issuer_country": "GB", "chargeback_stage": "Arbitration", "pre_arbitration_report_date": "2024-02-06", "pre_arbitration_amount": "50.00", "pre_arbitration_ccy": "USD", "arbitration_report_date": "2024-03-06", "arbitration_amount": "50.00", "arbitration_ccy": "USD", "representment_amount": "50.00", "representment_ccy": "USD" } ], "hasMoreRows": false, "signature": "t5BfDi85Hos2/sWjWOZocZhdDrzx10vzg/gtmmKfB2g==" } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } }, "/fraud/list": { "post": { "operationId": "POST_fraud_list", "summary": "/fraud/list", "tags": [ "Fraud" ], "description": "Request to retrieve the list of operations deemed as fraudulent by external payment providers.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "token": { "type": "string", "description": "Token generated in the Ecommpay Dashboard for the user account." }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." }, "filter": { "type": "object", "description": "Object used for filtering chargeback data by various parameters. \n", "properties": { "received_on": { "type": "array", "description": "Timeframe within which the payment platform registered the information that the card network reported the operation as fraudulent. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].", "items": { "type": "string" } }, "purchase_date": { "type": "array", "description": "Timeframe within which the operation was completed. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. By default, the response returns 20 most recently completed operations that are deemed fraudulent. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].", "items": { "type": "string" } }, "fraud_report_date": { "type": "array", "description": "Timeframe within which the operation was reported as fraudulent to the issuer. The array must contain start and end dates specified in 24-hour format of the time period for which the data is retrieved. By default, the response returns 20 operations most recently reported as fraudulent. Format: [YYYY-MM-DD HH:MM:SS,YYYY-MM-DD HH:MM:SS].", "items": { "type": "string" } }, "issuer_country": { "type": "array", "description": "Country code of the card issuer. An array of one or more codes specified in the ISO 3166-1 alpha-2 format ([Country codes](https://developers.ecommpay.com/en/en_country_codes.html)).", "items": { "type": "string" } }, "has_chargebacks": { "type": "integer", "description": "Indicator that specifies if at least one chargeback was registered in the payment platform for the operation that is deemed fraudulent. Possible values: 0—none registered, 1—one or more registered." }, "customer_id": { "description": "Identifier of the customer in the merchant's project (as a string) or an array of one or more customer identifiers.", "type": [ "string", "array" ], "items": { "type": "string" } }, "card_type": { "description": "Code identifying the card network. Possible values: mc—Mastercard, visa—Visa. Can also be passed as an array with one or both supported values.", "type": [ "string", "array" ], "items": { "type": "string" } } } }, "pagination": { "type": "object", "description": "Pagination is used to restrict the number of fraud operations information about which is returned in a single response.", "properties": { "limit": { "type": "integer", "description": "Number of entries to return per request. Default value is 20. Maximum value is not set." }, "offset": { "type": "integer", "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0." } } } }, "required": [ "token", "signature" ] }, "x-examples": { "example-1": { "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv", "signature": "sd0fr5YxcVmJ...grkglpeXJg==", "filter": { "purchase_date": [ "2025-12-31 00:00:00", "2026-01-07 23:59:59" ], "fraud_report_date": [ "2026-01-01 00:00:00", "2026-01-01 23:59:59" ], "issuer_country": [ "GB", "FR" ] }, "pagination": { "limit": 1000 } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/FraudApiOperationsList" }, "examples": { "example-1": { "operations": [ { "payment_id": "cosmopayment15_rogd", "operation_id": 6435212162442, "tr_amount": "180.00", "tr_ccy": "GBP", "account_number": "424242******4242", "payment_method_type": "visa", "row_updated_at": "2026-01-01 05:30:30", "customer_id": "earthling1232442", "project_name": "cosmoshop.earth", "project_id": "123", "arn": "14736364365402210100727", "fraud_type": "6", "fraud_report_date": "2026-01-01", "issuer_country": "GB", "received_on": "2026-01-01", "purchase_date": "2025-12-31", "channel_amount_in_usd": "234.58", "issuer_bank_name": "Intergalactic Bank", "bin": "123456", "country_by_ip": "GB", "customer_email": "earthling@earth.earth", "report_and_purchase_date_difference": 2 } ], "signature": "k4iXC84dfwevT+...dS056fssBGIw==" } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } }, "/financial-reporting/operations": { "post": { "operationId": "POST_financial-reporting-operations", "summary": "/financial-reporting/operations", "description": "Request to retrieve itemised operation data for financial reporting (including charged fees) for a specified time period. These data are accurate and can be used for reconciliation.", "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "required": [ "token", "signature", "operation_completed_at", "tz" ], "properties": { "token": { "type": "string", "description": "Token generated in the Ecommpay Dashboard for the user account." }, "signature": { "type": "string", "description": "Digital signature generated by using a secret key associated with the token specified in the token parameter." }, "operation_completed_at": { "type": "object", "description": "Time period with the start and end times for which to retrieve data. Only data about operations completed in the payment platform within the last 30 days can be requested.", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "description": "Start time in the YYYY-MM-DD hh:mm:ss format." }, "to": { "type": "string", "description": "End time in the YYYY-MM-DD hh:mm:ss format." } } }, "tz": { "type": "string", "description": "Identifier of the time zone for the time period. The time zone affects what operations will be selected for the time period specified in the operation_completed_at object. Can be one of the names in the IANA time zone database (for example, Indian/Mauritius) or the UTC offset (for example, +10:30)." }, "project_id": { "type": "array", "description": "Array of one or more project identifiers. If the array is omitted, the response will contain information for all projects accessible for the user account which is associated with the token specified in the token parameter.", "items": { "type": "integer" } }, "provider_id": { "type": "array", "description": "Array of one or more provider identifiers. If the array is omitted, the response will contain information for all providers available for the user account which is associated with the token specified in the token parameter.", "items": { "type": "integer" } }, "operation_id": { "type": "array", "description": "Array of one or more payment operation identifiers provided by Ecommpay. If the array is omitted, the response will contain information for all projects accessible for the user account which is associated with the token specified in the token parameter.", "items": { "type": "integer" } }, "limit": { "type": "integer", "description": "Number of entries to return per request. The default value, which is also the maximum, is 1000." }, "offset": { "type": "integer", "description": "Pagination start offset. Specifies the number of entries to skip before starting to return entries. Default value is 0." } } }, "x-examples": { "application/json": { "project_id": [ 11 ], "operation_completed_at": { "from": "2024-01-01 00:00:00", "to": "2024-01-31 23:59:59" }, "tz": "Indian/Mauritius", "limit": 1000, "offset": 0, "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "signature": "YsrkgdBr5peXJgJ...glVmsd0f==" } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ApiFinancialOperationsList" }, "examples": { "application/json": { "data": [ { "operation_completed_at": "2024-01-29T22:08:19+0000", "transaction_id": "81194009089601", "operation_id": "81194009122865", "provider_payment_id": "0040000028207224", "payment_id": "1994-1312", "arn": "70114165164100000032195", "rrn": "451912040334", "auth_appr_code": "611887", "provider_id": "120461", "provider_name": "Provider name", "payment_description": "purchase", "operation_type": "sale", "operation_status": "success", "tran_region": "domestic", "tariff_region": "EU", "proc_region": "Visa Europe", "security_level": "SEC", "operation_amount": 2098, "operation_currency": "GBP", "billing_conversion_rate": 0, "billing_amount": 2098, "billing_currency": "GBP", "total_interchange_fee": -4.2, "total_scheme_fee": -0.64, "auth_msc_fee": 0, "clearing_msc_fee": -3.785649, "total_msc_fee": -3.78, "hold_amount": 0, "project_id": 11, "project_url": "https://www.company.com", "merchant_name": "COMPANY NAME", "mid": "70000000", "terminal_id": "70000000", "mcc_code": "4722", "legal_country": "GB", "payment_method_name": "visa", "product_type": "Consumer", "account_funding_source": "debit", "account_number": "475144******1111", "card_product": "Visa classic", "issuer_country": "GB", "customer_id": "1436462", "card_holder": "CARD HOLDER" } ], "signature": "fdsfdsf985np=..." } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } }, "tags": [ "Operations" ] } }, "/operations/get": { "post": { "operationId": "POST_operations-get", "summary": "/operations/get", "tags": [ "Operations" ], "description": "Request to retrieve itemised operation data for a specified time period. These data can be used for general purposes of monitoring and anaysis.", "consumes": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "project_id": { "type": "array", "description": "Array of one or more project IDs. If array is omitted, the payment platform returns information for all projects accessible for the user account which is associated with the token specified in the token parameter.", "items": { "type": "integer" } }, "interval": { "type": "object", "description": "Time period with start and end times for which to retrieve data. By default, the response returns operations most recently completed.\r\nIf more than one request is received in the platform from a single Dashboard user account within 10 seconds and the time period for which the information is requested exceeds 180 days, these requests are processed one by one, with 10 seconds timeouts.", "properties": { "from": { "type": "string", "description": "Start time in the YYYY-MM-DD hh:mm:ss format.\r\n" }, "to": { "type": "string", "description": "End time in the YYYY-MM-DD hh:mm:ss format." } }, "required": [ "from", "to" ] }, "tz": { "type": "string", "description": "Identifier of the time zone for the time period. If the request does not contain this parameter, the default is the time zone of the Dashboard user account associated with the token from the token parameter. The time zone affects what operations will be selected for the time period specified in the interval object and the format of time parameters in the response—operation_created_at and operation_completed_at. Can be one of the names in the IANA time zone database (for example, Indian/Mauritius) or the UTC offset (for example, +10:30)." }, "limit": { "type": "integer", "description": "Number of entries to return per request. Maximum and default value is 1000." }, "offset": { "type": "integer", "description": "Pagination start offset. Specifies the number of entries to skip, before starting to return entries. Default value is 0." }, "operation_type": { "type": [ "array", "string" ], "description": "Operation type[s]. One or more operation types supported by the Ecommpay payment platform. The operation_type variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).", "items": { "type": "string" } }, "operation_status": { "type": [ "array", "string" ], "description": "Operation status[es]. One or more operation statuses supported by the Ecommpay payment platform. The operation_status variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).", "items": { "type": "string" } }, "customer_id": { "type": [ "array", "string" ], "description": "Unique customer identifier[s]. One or more unique identifiers of customers in your project. The customer_id variable can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).", "items": { "type": "string" } }, "customer_email": { "type": "string", "description": "Customer email." }, "token": { "type": "string", "description": "Token generated in Ecommpay Dashboard for user account." }, "fields": { "type": "array", "description": "An array of one or more parameter names the values of which are needed to be returned for each operation in the response. In the array, the parameter names must be enclosed in matching quotation marks and separated by commas and can be specified in an arbitrary order (for example, operation_id, payment_id, project_id). However, in the response the parameter values are returned in the fixed order which, together with the list of parameters, is defined in the response specification. If the array is omitted, then the response contains the values of the required parameters for each operation.", "items": { "type": "string" } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." } }, "required": [ "token", "signature" ] }, "x-examples": { "application/json": { "project_id": [ 0, 11 ], "interval": { "from": "2024-08-01 00:00:00", "to": "2024-08-28 23:59:59" }, "limit": 2, "offset": 1000, "operation_type": [ "sale", "refund" ], "operation_status": [ "success", "decline" ], "customer_email": "astronaut@earth.station", "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv", "fields": [ "operation_id", "operation_type", "operation_status", "sum_initial.amount", "sum_initial.currency", "customer_email" ], "signature": "sd0fr5YsdBVmJ...grkglpeXJg==" } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/ApiOperationsList" }, "examples": { "application/json": { "operations": [ { "operation_id": "6435212162442", "operation_type": "sale", "operation_status": "success", "sum_initial": { "amount": 1200, "currency": "USD" }, "customer_email": "astronaut@earth.station" }, { "operation_id": "1232452442", "operation_type": "refund", "operation_status": "success", "sum_initial": { "amount": 5800, "currency": "EUR" }, "customer_email": "astronaut@earth.station" } ], "signature": "k4iXC845FvT+...dS0AH5BGIw==" } } }, "400": { "description": "Validation error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "Authentication error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "Request rate error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "Internal server error", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } }, "/operations/get-by-payment": { "post": { "operationId": "POST_operations-get-by-payment", "summary": "/operations/get-by-payment", "tags": [ "Operations" ], "description": "Request to retrieve all the operations performed in the payment platform for specific payment.", "consumes": [ "application/json" ], "parameters": [ { "name": "body", "in": "body", "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "Payment ID in the project." }, "token": { "type": "string", "description": "Token generated by Ecommpay Dashboard for user account." }, "signature": { "type": "string", "description": "Digital signature generated by using secret key associated with the token specified in the token parameter." } }, "required": [ "payment_id", "token", "signature" ] }, "x-examples": { "application/json": { "payment_id": "PID_25467851461-2147", "token": "VmJQhaXILAnZWTKmqwSd3j", "signature": "JM+YWmTL7uGn26IgZWTKmqwSd...tRkvdC0yaq030+eNXVtJjjtgrkglpeXJg==" } } } ], "responses": { "200": { "description": "", "schema": { "type": "object", "description": "List of operations with operation details.", "properties": { "operations": { "type": "array", "items": { "type": "object", "description": "Operation details.", "properties": { "operation_id": { "type": "string", "description": "Payment operation ID provided by Ecommpay." }, "operation_type": { "type": "string", "description": "Operation type. One of operation types supported by the Ecommpay payment platform." }, "operation_created_at": { "type": "string", "description": "Date and time when the operation was created. Format: YYYY-MM-DD hh:mm:ss." }, "operation_completed_at": { "type": "string", "description": "Date and time when the operation was completed in the payment platform. Format: YYYY-MM-DD hh:mm:ss." }, "amount": { "type": "number", "description": "Operation amount in minor currency units." }, "currency": { "type": "string", "description": "Operation currency code. Currency code must comply with ISO 4217 alpha-3." }, "arn": { "type": "string", "description": "Acquirer Reference Number - 23 digits of the unique operation identifier in clearing exchange between banks or processing centers." }, "rrn": { "type": "string", "description": "Reference Retrieval Number - 12 digits of the unique operation identifier, which is assigned by the Acquirer Bank when the payment is initialized." } }, "required": [ "operation_id", "operation_type", "operation_created_at", "operation_completed_at", "amount", "currency", "arn", "rrn" ] } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "examples": { "application/json": { "operations": [ { "arn": "", "operation_completed_at": "2024-11-22T13:13:04+00:00", "operation_type": "refund", "operation_id": "2747253065470", "amount": 221, "currency": "USD", "operation_created_at": "2024-11-22T13:13:04+00:00", "rrn": "803817399309" }, { "arn": "", "operation_completed_at": "2024-11-22T13:09:03+00:00", "operation_type": "capture", "operation_id": "2747253065469", "amount": 1621, "currency": "USD", "operation_created_at": "2024-11-22T13:09:03+00:00", "rrn": "000000248370" }, { "arn": "", "operation_completed_at": "2024-11-22T13:06:40+00:00", "operation_type": "auth", "operation_id": "2747253065468", "amount": 2000, "currency": "USD", "operation_created_at": "2024-11-22T13:06:38+00:00", "rrn": "000047769105" } ], "signature": "hsUpqn7QPDxNLNH/ZulaK...z/Hv7NkQFujSnvw==" } } }, "400": { "description": "", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "401": { "description": "", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "429": { "description": "", "schema": { "$ref": "#/definitions/ApiErrorResponse" } }, "500": { "description": "", "schema": { "$ref": "#/definitions/ApiErrorResponse" } } } } } }, "definitions": { "ApiBalanceList": { "title": "ApiBalanceList", "type": "object", "description": "List of balances with balance details.", "properties": { "balance": { "type": "array", "description": "Array of balances.", "items": { "$ref": "#/definitions/BalanceTransactionItem" } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "ApiErrorResponse": { "type": "object", "description": "Error details.", "required": [ "status" ], "properties": { "name": { "type": "string", "description": "Error name." }, "message": { "type": "string", "description": "Description of error cause." }, "code": { "type": "integer", "description": "HTTP error code." }, "status": { "type": "integer", "description": "HTTP response code, for example 400 or 401." } } }, "ApiFinancialOperationsList": { "title": "ApiOperationsList", "type": "object", "description": "List of operations with extended data (including charged fees).", "required": [ "data", "signature" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/definitions/FinancialOperationItem" } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "ApiOperationsList": { "type": "object", "description": "List of operations with operation details.", "properties": { "operations": { "type": "array", "items": { "$ref": "#/definitions/OperationItem" } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "BalanceTransactionItem": { "title": "BalanceTransactionItem", "type": "object", "description": "Balance details.", "properties": { "name": { "type": "string", "description": "Balance name within the contract." }, "{additionalProperties}": { "type": "string", "description": "Currency code and balance amount in minor currency units presented as parameter-value pair, for example: EUR: 5000. Currency code is specified as the parameter name. Balance amount is specified as parameter value." } } }, "Chargeback": { "type": "object", "properties": { "chargeback_id": { "type": "string", "description": "Chargeback ID." }, "charged_amount": { "type": "string", "description": "Amount that has been debited (as shown in the Operational Statement). Specified as an integer in minor currency units." }, "channel_amount": { "type": "string", "description": "Amount of the disputed operation (as originally processed by the merchant). Specified as an integer in minor currency units." }, "case_id": { "type": "string", "description": "Identification number of the chargeback case (the case may include multiple chargebacks)." }, "project_id": { "type": "string", "description": "Merchant project ID assigned by Ecommpay." }, "operation_id": { "type": "string", "description": "Operation ID provided by Ecommpay." }, "report_date": { "type": "string", "description": "Date when the chargeback was registered in the payment platform." }, "respond_by": { "type": "string", "description": "Deadline for submitting a response to the chargeback." }, "rev_date": { "type": "string", "description": "Date when the chargeback reversal was performed, otherwise null.", "x-nullable": true }, "tr_date_time": { "type": "string", "description": "Date and time when the disputed operation occurred." }, "chb_completed_at": { "type": "string", "description": "Date when the chargeback received one of the final statuses: won, lost, returned, accepted by merchant." }, "chb_amount": { "type": "string", "description": "Amount for which the issuer initiated a chargeback. Specified as a decimal number with two decimal places." }, "chb_settlement_amount": { "type": "string", "description": "Chargeback amount in the settlement currency of the acquiring bank. Specified as a decimal number with two decimal places." }, "rev_indicator": { "type": "string", "description": "‘R’ if there was a chargeback reversal received, otherwise null.", "x-nullable": true }, "chb_ccy": { "type": "string", "description": "Currency of the chargeback initiated by the issuer." }, "chb_settlement_ccy": { "type": "string", "description": "Settlement currency of the acquiring bank." }, "charged_currency": { "type": "string", "description": "Currency in which the amount has been debited (as shown in the Operational Statement)." }, "channel_currency": { "type": "string", "description": "Operation amount currency code." }, "eci_sli": { "type": "string", "description": "Electronic Commerce Indicator (for Visa) and Security Level Indicator (for Mastercard)." }, "reason_code": { "type": "string", "description": "Numerical chargeback reason code." }, "card_type": { "type": "string", "description": "Card payments processing organisation, for example, Visa or Mastercard." }, "merchant_id": { "type": "string", "description": "Merchant identifier assigned by Ecommpay at the stage of integration. " }, "card": { "type": "string", "description": "Number of the card used by the customer." }, "arn": { "type": "string", "description": "Acquirer reference number used for clearing. " }, "status": { "type": "string", "description": "Current status of the chargeback." }, "chb_amount_in_usd": { "type": "string", "description": "Chargeback amount in USD. Specified as a decimal number with four decimal places." }, "merchant_name": { "type": "string", "description": "Merchant name passed in the merchant.descriptor parameter." }, "order_id": { "type": "string", "description": "Operation ID provided by Ecommpay." }, "operation_type": { "type": "string", "description": "Operation type. One of the operation types supported by the Ecommpay payment platform." }, "auth_code": { "type": "string", "description": "Operation authorization code. Alphanumeric code which confirms that the card issuer or payment system approved processing of the payment. Authorization codes are not assigned to declined payments." }, "card_holder": { "type": "string", "description": "Name of the cardholder (as specified on the card)." }, "issuer_country": { "type": "string", "description": "Country of the issuer determined according to the BIN of the card. Array of one or more country codes in ISO 3166-1 alpha-2 format ([Country codes](https://developers.ecommpay.com/en/en_country_codes.html))." }, "chargeback_stage": { "type": "string", "description": "Stage at which the work with the chargeback is currently carried out." }, "pre_arbitration_report_date": { "type": "string", "description": "Date when Ecommpay was informed that the issuer initiated the Pre-Arbitration stage." }, "pre_arbitration_amount": { "type": "string", "description": "Amount of the disputed operation at the Pre-Arbitration stage. May differ from the initial disputed amount." }, "pre_arbitration_ccy": { "type": "string", "description": "Currency of the amount at the Pre-Arbitration stage." }, "arbitration_report_date": { "type": "string", "description": "Date when Ecommpay was informed that the issuer initiated the Arbitration stage." }, "arbitration_amount": { "type": "string", "description": "Amount of the disputed operation at the Arbitration stage." }, "arbitration_ccy": { "type": "string", "description": "Currency of the amount at the Arbitration stage." }, "representment_amount": { "type": "string", "description": "The amount that is returned to the merchant if the merchant wins the chargeback at the Representment stage." }, "representment_ccy": { "type": "string", "description": "Currency in which the chargeback amount is returned to the merchant if the merchant wins the chargeback at the Representment stage." } } }, "ChargebackList": { "type": "object", "description": "List of chargebacks.", "title": "", "properties": { "chargebacks": { "type": "array", "items": { "$ref": "#/definitions/Chargeback" } }, "hasMoreRows": { "description": "True if the number of rows is more than 20. Please use pagination.", "type": "boolean" }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of the Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "DateRange": { "type": "object", "description": "The object must contain start and end dates of the time period for which the data is retrieved.", "properties": { "from": { "type": "string", "description": "Start date of the required time period. " }, "to": { "type": "string", "description": "End date of the required time period." } } }, "FinancialOperationItem": { "title": "OperationItem", "type": "object", "description": " Extended operation data (including charged fees).", "required": [ "operation_completed_at", "transaction_id", "operation_id", "provider_payment_id", "payment_id", "arn", "rrn", "auth_appr_code", "provider_id", "provider_name", "payment_description", "operation_type", "operation_status", "tran_region", "proc_region", "security_level", "operation_amount", "operation_currency", "billing_conversion_rate", "billing_amount", "billing_currency", "total_interchange_fee", "total_scheme_fee", "total_msc_fee", "auth_msc_fee", "clearing_msc_fee", "hold_amount", "project_id", "project_url", "merchant_name", "terminal_id", "mcc_code", "legal_country", "payment_method_name", "product_type", "account_number", "card_product", "issuer_country", "customer_id", "card_holder" ], "properties": { "operation_completed_at": { "type": "string", "description": "Time when the operation was completed in the payment platform, specified according to the time zone passed in the request. Format: YYYY-MM-DD hh:mm:ss." }, "transaction_id": { "type": "string", "description": "Identifier used for referencing a payment transaction in the Ecommpay payment platform. In the payment platform, the payment identifier is unique only within the merchant's project while the transaction identifier is unique within the entirety of the payment platform." }, "operation_id": { "type": "string", "description": "Operation identifier assigned by Ecommpay." }, "provider_payment_id": { "type": "string", "description": "Operation identifier assigned by the external payment system or provider." }, "payment_id": { "type": "string", "description": "Payment identifier within the project assigned by the merchant." }, "arn": { "type": "string", "description": "Acquirer Reference Number: an operation identifier used for clearing. This identifier is assigned by the acquirer and is used for tracking operations." }, "rrn": { "type": "string", "description": "Reference Retrieval Number: an operation number assigned by the acquirer which is used for associating the operation with the payment details for easier retrieval and reconciliation." }, "auth_appr_code": { "type": "string", "description": "Alphanumeric code which confirms that the card issuer or the payment system approved processing of the payment. Authorisation codes are not assigned to declined payments." }, "provider_id": { "type": "string", "description": "Identifier of an external payment system or a provider in the payment platform." }, "provider_name": { "type": "string", "description": "Name of an external payment system or a provider in the payment platform." }, "payment_description": { "type": "string", "description": "Description of the payment as specified in the initial request." }, "operation_type": { "type": "string", "description": "One of the operation types supported by the Ecommpay payment platform." }, "operation_status": { "type": "string", "description": "One of the operation statuses supported by the Ecommpay payment platform." }, "tran_region": { "type": "string", "description": "Region code for the operation ([Region codes](https://developers.ecommpay.com/en/en_region_codes.html))." }, "tariff_region": { "type": "string", "description": "Reference to the region that determines the processing fee rate." }, "proc_region": { "type": "string", "description": "Reference to the region that determines what processing rules are applied to the operation." }, "security_level": { "type": "string", "description": "Reference to the result of the cardholder 3‑D Secure authentication, determined on the basis of the Electronic Commerce Indicator parameter. Can be populated with one of the following values: sec, attempt, non-sec." }, "operation_amount": { "type": "number", "description": "Amount of the initial operation; can be a decimal number." }, "operation_currency": { "type": "string", "description": "Initial operation currency code in the ISO 4217 alpha-3 format." }, "billing_conversion_rate": { "type": "number", "description": "Exchange rate used for the conversion of the operation amount to the billing currency; can be a decimal number and, depending on the pricing model, can also be sent empty." }, "billing_amount": { "type": "number", "description": "Operation amount in the billing currency; can be a decimal number and, depending on the pricing model, can also be sent empty." }, "billing_currency": { "type": "string", "description": "Billing currency code in the ISO 4217 alpha-3 format. Depending on the pricing model, can be sent empty." }, "total_interchange_fee": { "type": "number", "description": "Interchange fee amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty." }, "total_scheme_fee": { "type": "number", "description": "Scheme fee amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty." }, "total_msc_fee": { "type": "number", "description": "Merchant service charge total amount; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty." }, "auth_msc_fee": { "type": "number", "description": "The portion of the Merchant service charge amount charged for authorisation; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty." }, "clearing_msc_fee": { "type": "number", "description": "The portion of the Merchant service charge amount charged for clearing; a decimal number, can be positive or negative. Depending on the pricing model, can be sent empty." }, "hold_amount": { "type": "number", "description": "Amount of funds held for the operation; can be a decimal number." }, "project_id": { "type": "integer", "description": "Project identifier provided by Ecommpay." }, "project_url": { "type": "string", "description": "Base URL of the merchant's web service associated with the specific project." }, "merchant_name": { "type": "string", "description": "Name of the merchant within the payment platform." }, "mid": { "type": "string", "description": "Identifier of the merchant assigned by the provider (which includes Ecommpay) or by the acquirer and used for processing card payments." }, "terminal_id": { "type": "string", "description": "Identifier of a logical node in the payment platform that determines the configuration of payment processing properties for a certain MID in specific cases. Assigned within MID." }, "mcc_code": { "type": "string", "description": "Merchant category code. A 4-digit number that classifies the type of the merchant's business activity." }, "legal_country": { "type": "string", "description": "Code of the merchant's country of registration in the ISO 3166-1 alpha-2 format." }, "payment_method_name": { "type": "string", "description": "Identifier of the payment system. For card payments, it is the identifier of the card processing network, for example, Visa or Mastercard. For some payment methods, can be sent empty." }, "product_type": { "type": "string", "description": "Reference to the class of the card product offered by a card processing network, for example, consumer or commercial." }, "account_funding_source": { "type": "string", "description": "Type of the payment card funding, for example, debit, credit, or prepaid." }, "account_number": { "type": "string", "description": "Identifier of the payment instrument used by the customer, for example, a card or a wallet number." }, "card_product": { "type": "string", "description": "Card category offered by the issuing bank, for example, Visa Classic or World Elite Mastercard." }, "issuer_country": { "type": "string", "description": "Country code of the issuer determined according to the BIN of the card in the ISO 3166-1 alpha-2 format." }, "customer_id": { "type": "string", "description": "Identifier of the customer in the merchant's project." }, "card_holder": { "type": "string", "description": "Name of the cardholder as specified in the initial request." } } }, "FraudApiOperationsList": { "title": "FraudApiOperationsList", "type": "object", "description": "List of fraudulent operations.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "Payment ID in the project." }, "operation_id": { "type": "integer", "description": "Operation ID provided by Ecommpay." }, "tr_amount": { "type": "string", "description": "Fraudulent operation amount (full operation amount)." }, "tr_ccy": { "type": "string", "description": "Fraudulent operation currency code in ISO 4217 alpha-3 format ([Currency codes](https://developers.ecommpay.com/en/en_currency_codes.html))." }, "account_number": { "type": "string", "description": "Number of the card used by the customer." }, "payment_method_type": { "type": "string", "description": "Type of the payment method used for payment processing." }, "row_updated_at": { "type": "string", "description": "The date and time of the most recent update of the fraudulent operation record in the payment platform." }, "customer_id": { "type": "string", "description": "Identifier of the customer in the merchant's project." }, "project_name": { "type": "string", "description": "Name of the merchant's website (project)." }, "project_id": { "type": "string", "description": "Project ID provided by Ecommpay." }, "arn": { "type": "string", "description": "Acquirer Reference Number: a unique operation identifier in clearing exchange between banks or processing centers." }, "fraud_type": { "type": "string", "description": "Type of fraud declared by the issuer when submitting information about fraudulent operations to payment systems." }, "fraud_report_date": { "type": "string", "description": "Date when the operation was reported as fraudulent to the issuer. Format: [YYYY-MM-DD]." }, "issuer_country": { "type": "string", "description": "Country code of the card issuer determined according to the BIN of the card (two-letter ISO code)." }, "received_on": { "type": "string", "description": "Date when the payment platform registered the information that the card network reported the operation as fraudulent" }, "purchase_date": { "type": "string", "description": "Date when the operation was completed. Format: [YYYY-MM-DD,YYYY-MM-DD]." }, "channel_amount_in_usd": { "type": "string", "description": "Fraudulent operation amount in USD." }, "issuer_bank_name": { "type": "string", "description": "Name of the issuer determined according to the BIN of the card." }, "bin": { "type": "string", "description": "Bank Identification Number that refers to the first six to eight digits of PAN, also known as IIN (Issuer Identification Number)." }, "country_by_ip": { "type": "string", "description": "Country determined according to the IP address of the customer (two-letter ISO country code)." }, "customer_email": { "type": "string", "description": "Customer email address." }, "report_and_purchase_date_difference": { "type": "integer", "description": "The number of full days between fraud report and purchase dates." }, "has_chargebacks": { "type": "integer", "description": "Indicator that specifies if at least one chargeback was registered in the payment platform for the operation that is deemed fraudulent. Possible values: 0—none registered, 1—one or more registered." }, "card_type": { "type": "string", "description": "Code identifying the card network. Possible values: mc—Mastercard, visa—Visa." } } } }, "signature": { "type": "string", "description": "Digital signature generated by using secret key of Ecommpay Dashboard user account. The payment platform uses the same key that was previously used to sign the request." } } }, "OperationItem": { "title": "OperationItem", "type": "object", "description": "Operation details.", "properties": { "project_id": { "type": "string", "description": "Project ID provided by Ecommpay." }, "operation_id": { "type": "string", "description": "Payment operation ID provided by Ecommpay." }, "payment_id": { "type": "string", "description": "Payment ID in the project." }, "operation_type": { "type": "string", "description": "Operation type. One of the operation types supported by the Ecommpay payment platform." }, "operation_status": { "type": "string", "description": "Operation status. One of the operation statuses supported by the Ecommpay payment platform." }, "account_number": { "type": "string", "description": "ID of the payment instrument used by customer, for example, card number or wallet ID." }, "customer_ip": { "type": "string", "description": "Customer IP address." }, "payment_method_name": { "type": "string", "description": "Name of the payment method used for payment processing." }, "payment_method_type": { "type": "string", "description": "Type of the payment method used for payment processing." }, "payment_description": { "type": "string", "description": "Description of the payment as specified in the initial request." }, "operation_created_at": { "type": "string", "description": "Date and time when the operation was created. Format: YYYY-MM-DD hh:mm:ss." }, "operation_completed_at": { "type": "string", "description": "Date and time when the operation was completed in the payment platform. Format: YYYY-MM-DD hh:mm:ss." }, "provider_date": { "type": "string", "description": "Date and time when the operation was completed on the payment provider side. Format: YYYY-MM-DD hh:mm:ss." }, "shipment_date": { "type": "string", "description": "Date and time when the payment provider posted the operation for clearing. Format: YYYY-MM-DD hh:mm:ss." }, "sum_initial": { "type": "object", "description": "Amount and currency code of the operation as specified in the initial request.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "description": "Operation amount in minor currency units as specified in the initial request." }, "currency": { "type": "string", "description": "Operation currency code as specified in the initial request. Must be the ISO 4217 alpha-3 currency code." } } }, "sum_converted": { "type": "object", "description": "Code of the currency that the payment provider used for performing the operation and the initial amount converted to this currency.", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "string", "description": "Operation amount in minor units of the payment provider currency." }, "currency": { "type": "string", "description": "Code of the currency that the payment provider used for performing the operation. Must be the ISO 4217 alpha-3 currency code." } } }, "arn": { "type": "string", "description": "Acquirer Reference Number: a unique operation identifier in clearing exchange between banks or processing centers." }, "rrn": { "type": "string", "description": "Reference Retrieval Number: a unique operation identifier assigned by the acquirer bank when the payment is initialized." }, "payment_provider_code": { "type": "string", "description": "Numeric code of payment result from the card issuer or payment provider." }, "payment_provider_message": { "type": "string", "description": "Message of payment result from the card issuer or payment provider." }, "acquirer_bank_name": { "type": "string", "description": "Name of the acquirer bank." }, "auth_code": { "type": "string", "description": "Alphanumeric code which confirms that the card issuer / payment system approved processing of the payment. Authorization codes are not assigned to declined payments." }, "avs_post_code": { "type": "string", "description": "Customer postal code for verification with the Address Verification Service. AVS applies to cardholders from the UK, USA, and Canada." }, "avs_result": { "type": "string", "description": "A single-letter Address Verification Service response code sent by the issuer following the address verification. AVS applies to cardholders from the UK, USA, and Canada." }, "avs_street_address": { "type": "string", "description": "Customer postal address for verification with the Address Verification Service. AVS applies to cardholders from the UK, USA, and Canada." }, "balance_id": { "type": "string", "description": "ID of the merchant's balance aggregation in the Ecommpay payment platform under which all merchant accounts are aggregated. This ID is masked by adding id_mask to the initial identifier." }, "bank_name": { "type": "string", "description": "Name of the issuer determined according to the BIN of the card." }, "bin": { "type": "string", "description": "Bank Identification Number (first six to eight digits of PAN). Numeric identifier of the card organization member. Assigned separately to each card level (for example, Classic, Standard, Gold, Maestro, Visa Electron, etc.) offered by the issuing bank—a card organization member. Also referred to as IIN (Issuer Identification Number)." }, "card_enroll_check": { "type": "string", "description": "Specifies if the card supports 3-D Secure. Possible values are: E—Enrolled (the card supports 3DS), N—Not enrolled, U—Undefined (was unable to determine)." }, "card_holder": { "type": "string", "description": "The name of the cardholder (as specified on the card)." }, "card_product_name": { "type": "string", "description": "Name of the bank product determined according to the BIN of the card." }, "card_token": { "type": "string", "description": "Token of the customer bank card in the Ecommpay payment platform." }, "completed_refund": { "type": "string", "description": "Amount of the issued refund in minor units of currency." }, "country_by_ip": { "type": "string", "description": "Country determined according to the IP address of the customer (two-letter ISO country code)." }, "country_by_bin": { "type": "string", "description": "Country determined according to the BIN of the card, country of the card's issuer (two-letter ISO code)." }, "currency_rate": { "type": "string", "description": "Currency exchange rate used for conversion of the payment amount from the source currency to the default currency." }, "customer_email": { "type": "string", "description": "Customer email address." }, "customer_id": { "type": "string", "description": "Identifier of the customer in the merchant's project." }, "eci": { "type": "string", "description": "Electronic commerce indicator. For possible values and more information, see [ECI codes](https://developers.ecommpay.com/en/en_ECI_codes.html)." }, "expiration_date": { "type": "string", "description": "Date indicating the validity period of the payment card." }, "legal_entity_name": { "type": "string", "description": "Name of the merchant's legal entity." }, "merchant_id": { "type": "string", "description": "Identifier of the merchant within the payment platform." }, "payment_currency": { "type": "string", "description": "Currency of the payment (currency in which payment_amount is specified). Must be the ISO 4217 alpha-3 currency code." }, "payment_type": { "type": "string", "description": "ID of the payment type. Possible values are: 3—Sale, 31—Purchase_dms, 6—Recurring, 24—Transfer, 11—Payout." }, "project_name": { "type": "string", "description": "Name of the merchant's website (project)." }, "project_url": { "type": "string", "description": "URL of the merchant's website (project)." }, "provider_payment_id": { "type": "string", "description": "Identifier of the operation assigned by the external payment system / provider." }, "recurring_id": { "type": "string", "description": "ID of debiting series received in the callback with the COF purchase registration data. This ID is used for all debits performed as part of the COF purchase." }, "recurring_register": { "type": "string", "description": "Specifies whether the recurring purchase was registered. Possible values are: 0—No. 1—Yes." }, "recurring_valid_thru": { "type": "string", "description": "Specifies the date until which the COF purchase is valid." }, "remaining_refund": { "type": "string", "description": "Reflects the remaining balance, only available for the operations which at certain point had success status." }, "secure_3ds_check": { "type": "string", "description": "Specifies whether the customer was redirected to the ACS (Access Control Service) page where the password from the text message is entered. Possible values are: 0—Was not redirected. 1—Was redirected." }, "transaction_completed_at": { "type": "string", "description": "Time of the payment completion." }, "transaction_created_at": { "type": "string", "description": "Time of the payment creation." }, "transaction_status": { "type": "string", "description": "Payment status." } }, "required": [ "project_id", "operation_id", "payment_id", "operation_type", "operation_status", "account_number", "customer_ip", "payment_method_name", "payment_method_type", "payment_description", "operation_created_at", "provider_date", "shipment_date", "sum_initial", "sum_converted", "arn", "rrn", "payment_provider_code", "payment_provider_message" ] } }, "consumes": [ "application/json" ], "produces": [ "application/json" ] } --- # Платёжные методы {#ru_pm_about} раздел с материалами о поддерживаемых платёжных методах и порядке работы с ними, включая общую информацию о типах методов, каталог методов и описание для каждого из них ## Введение {#section_xt4_mlj_nvb .section} Через платформу Ecommpay можно проводить платежи с использованием разнообразных платёжных методов.Каждый из них поддерживает определённые сценарии и операции в некоторых регионах, и в совокупности — за счёт применения различных методов — можно охватывать самую разную аудиторию в разных уголках Земли. Ecommpay постоянно расширяет спектр поддерживаемых платёжных методов и делает доступными платежи с использованием всё большего числа платёжных инструментов и валют в различных регионах.В этом разделе представлена информация отипах поддерживаемых методов, о самих методах и работе с ними, а также [о возможностях тестирования](ru_pm_testing.md) различных операций для различных методов. С вопросами об условиях и порядке подключения любых из поддерживаемых методов, как и с предложениями о поддержке дополнительных методов, всегда можно обращаться к курирующему менеджеру Ecommpay; с вопросами о способах интеграции, тестирования и работы с различными методами — к специалистам технической поддержки. - *Карточные платежи* — это платежи с переводом средств между счетами пользователя и мерчанта на основе реквизитов платёжной карты пользователя. Такие платежи могут осуществляться через процессинговый центр Ecommpay \(как эквайера\) и через системы партнёров-эквайеров.При этом в качестве платёжного инструмента всегда выступает платёжная карта пользователя, а сценарии могут отличатьсяи включать в себя задействование определённых сервисов и выполнение различных процедур.К методам этого типа относятся классические карточные платежи \(с прямым использованием карт, без задействования дополнительных пользовательских сервисов\)и методы Apple Pay, Click to Pay и Google Pay, при работе с которыми задействуются одноимённые сервисы,ориентированные на улучшение пользовательского опыта в использовании платёжных карт. **Прим.:** В рамках настоящей документации под карточными платежами \(если иное не оговорено отдельно\), как правило, имеются в виду классические карточные платежи. - *Банковские платежи* — это платежи, для проведения которых используются специализированные банковские онлайн-сервисы, позволяющие переводить средства между пользователем и мерчантом \(напрямую или через счёт провайдера\). Платёжным инструментом при этом выступает банковский счёт пользователя, а в сценариях проведения платежей могут применяться технологии интернет-банкинга, банковских переводов и других банковских сервисов.Среди таких методов — методы группы Open Banking в странах Европы, методы интернет-банкинга в странах Юго-Восточной Азии \(такие как Banks of Indonesia\) и многие другие. - *Платежи с использованием электронных кошельков* — это платежи, в рамках которых со стороны пользователя задействуется электронный кошелёк, предоставляемый соответствующим оператором. При этом в качестве платёжного инструмента может выступать непосредственно электронный кошелёк\(например, в таких методах, как PayPal иNeteller\) или платёжная карта пользователя\(например, в таких методах, как Apple Pay иGoogle Pay\), а пользовательские сценарии могут широко варьироваться с учётом специфики разных кошельков. - *Платежи с помощью QR-кодов* — это платежи, для проведения которых пользователю каждый разнеобходимо сканировать специализированный QR-коди в некоторых случаях выполнять определённые действия после этого. В качестве платёжного инструмента при этом может использоваться банковский счёт или электронный кошелёк.К таким методам относятся Promptpay, QRIS и другие. ## Каталогметодов {#section_evs_nlj_nvb .section} Для поиска информации об интересующих методах можно использовать представленную здесь таблицу сполным перечнем методов и возможностями сортировки и фильтрации строкпо различным атрибутам. Помимо этого, для подбора методов с учётом типа бизнеса и других критериев, а также для уточнения финансовых условий подключения и использования актуальных методов можно использовать специализированный каталог [Ecommpay shop](https://ecommpay.com/shop/). | |Метод|Тип|Оплаты|Выплаты| |:-|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_card_payments.svg)|[Классические карточные платежи](ru_pm_card_payments.md)|карточные платежи|+|+| |![](images/pm/methods_icon/pm_alipay.svg)|[Alipay](pm_alipay.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_applepay.svg)|[Apple Pay](pm_applepay.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_astropay.svg)|[AstroPay](pm_astropay.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_bancontact.svg)|[Bancontact](pm_bancontact.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_bancomatpay.svg)|[Bancomat Pay](pm_bancomatpay.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_hk_banks.svg)|[Banks of Hong Kong](pm_hk_banks.md)|банковские платежи|–|+| |![](images/pm/methods_icon/pm_philippines.svg)|[Banks of the Philippines](pm_philippines.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_blik.svg)|[Blik](pm_blik.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_boost.svg)|[Boost wallet](pm_boost.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_brazil_ob.svg)|[Brazil Online Banking](pm_brazil_ob.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_bnpl.svg)|[Buy Now Pay Later](pm_bnpl.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_chile_ob.svg)|[Chile Online Banking](pm_chile_ob.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_unionpay.svg)|[China UnionPay](pm_unionpay.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_clicktopay.svg)|[Click to Pay](pm_clicktopay.md)|карточные платежи|+|–| |![](images/pm/methods_icon/pm_coinsph.svg)|[Coins.ph](pm_coinsph.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_doku.svg)|[DOKU Wallet](pm_doku.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_ecuador_ob.svg)|[Ecuador Online Banking](pm_ecuador_ob.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_eps.svg)|[EPS](pm_eps.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_gcash.svg)|[GCash](pm_gcash.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_googlepay.svg)|[Google Pay](pm_googlepay.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_grabpay.svg)|[GrabPay](pm_grabpay.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_hk_qr.svg)|[Hong Kong FPS QR](pm_hk_qr.md)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_ideal_wero.svg)|[iDEAL \| Wero](pm_ideal.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_indonesia.svg)|[Indonesian Online Banking](pm_indonesia.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_indonesia_va.svg)|[Indonesian Virtual Accounts](pm_indonesia_va.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_malaysia.svg)|[Malaysian Online Banking](pm_malaysia.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_maya.svg)|[Maya](pm_maya.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_mbway.svg)|[MBWay](pm_mbway.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_mexico_ob.svg)|[Mexico Online Banking](pm_mexico_ob.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_momoqr.svg)|[MoMo Wallet](pm_momoqr.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_multibanco.svg)|[Multibanco](pm_multibanco.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_mybank.svg)|[MyBank](pm_mybank.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_neteller.svg)|[Neteller](pm_neteller.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_austria.svg)|[Open Banking in Austria](pm_austria.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_belgium.svg)|[Open Banking in Belgium](pm_belgium.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_denmark.svg)|[Open Banking in Denmark](pm_denmark.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_estonia.svg)|[Open Banking in Estonia](pm_estonia.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_finland.svg)|[Open Banking in Finland](pm_finland.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_france.svg)|[Open Banking in France](pm_france.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_germany.svg)|[Open Banking in Germany](pm_germany.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_hungary.svg)|[Open Banking in Hungary](pm_hungary.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_ireland.svg)|[Open Banking in Ireland](pm_ireland.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_italy.svg)|[Open Banking in Italy](pm_italy.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_latvia.svg)|[Open Banking in Latvia](pm_latvia.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_lithuania.svg)|[Open Banking in Lithuania](pm_lithuania.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_luxembourg.svg)|[Open Banking in Luxembourg](pm_luxembourg.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_norway.svg)|[Open Banking in Norway](pm_norway.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_poland.svg)|[Open Banking in Poland](pm_poland.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_portugal.svg)|[Open Banking in Portugal](pm_portugal.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_romania.svg)|[Open Banking in Romania](pm_romania.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_spain.svg)|[Open Banking in Spain](pm_spain.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_sweden.svg)|[Open Banking in Sweden](pm_sweden.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_netherlands.svg)|[Open Banking in the Netherlands](pm_netherlands.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_uk.svg)|[Open Banking in the UK](pm_uk.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_ovo.svg)|[OVO Wallet](pm_ovo.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_paypal.svg)|[PayPal](pm_paypal.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_paypal_pay_later.svg)|[PayPal Pay Later](pm_paypal_pay_later.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_peru_ob.svg)|[Peru Online Banking](pm_peru_ob.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_philippines_atm.svg)|[Philippines Over the Counter & ATM](pm_philippines_atm.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_pix.svg)|[PIX](pm_pix.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_promptpay.svg)|[Promptpay](pm_promptpay.md)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_przelewy.svg)|[Przelewy24](pm_przelewy.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_satispay.svg)|[Satispay](pm_satispay.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_qris.svg)|[QRIS](pm_qris.md)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_qrph.svg)|[QR Ph](pm_qrph.md)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_shopee.svg)|[Shopee](pm_shopee.md)|платежи с использованием электронных кошельков|+|−| |![](images/pm/methods_icon/pm_skrill.svg)|[Skrill Wallet](pm_skrill.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_swish.svg)|[Swish](pm_swish.md)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_thailand.svg)|[Thai Online Banking](pm_thailand.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_touchngo.svg)|[Touch&Go](pm_touchngo.md)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_truemoney.svg)|[TrueMoney](pm_truemoney.md)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_twint.svg)|[TWINT](pm_twint.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_vietnam.svg)|[Vietnamese Online Banking](pm_vietnam.md)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_instalments.svg)|[Visa Instalments](pm_instalments.md)|карточные платежи|+|–| |![](images/pm/methods_icon/pm_wechat.svg)|[WeChat](pm_wechat.md)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_bankpayout_sepa.svg)|[Выплаты на банковские счета в ЕЗПЕ \(SEPA\)](pm_bankpayout_sepa.md)|банковские платежи|–|+| |![](images/pm/methods_icon/pm_bankpayout_uk.svg)|[Локальные выплаты на банковские счета в Великобритании](pm_bankpayout_uk.md)|банковские платежи|–|+| - **[Карточные платежи](ru_pm_cardpayments.md)** статьи о платёжных методах группы карточных платежей, в которых переводы средств выполняются на основе реквизитов платёжных карт пользователей - **[Банковские платежи](ru_pm_bankpayments.md)** статьи о платёжных методах группы банковских платежей, в которых переводы средств выполняются с использованием специализированных банковских онлайн-сервисов - **[Платежи с использованием электронных кошельков](ru_pm_ewallet.md)** статьи о платёжных методах группы платежей с использованием электронных кошельков, в которых для переводов средств со стороны пользователей задействуются электронные кошельки соответствующих операторов - **[Платежи с помощью QR-кодов](ru_pm_qr.md)** статьи о платёжных методах группы платежей с помощью QR-кодов, в которых для переводов средств со стороны пользователей необходимо сканировать специализированные QR-коды - **[Возможности тестирования](ru_pm_testing.md)** статья с информацией о возможностях тестирования разных типов платежей и операций для различных платёжных методов --- # Карточные платежи {#ru_pm_cardpayments} статьи о платёжных методах группы карточных платежей, в которых переводы средств выполняются на основе реквизитов платёжных карт пользователей *Карточные платежи* — это платежи с переводом средств между счетами пользователя и мерчанта на основе реквизитов платёжной карты пользователя. Такие платежи могут осуществляться через процессинговый центр Ecommpay \(как эквайера\) и через системы партнёров-эквайеров.При этом в качестве платёжного инструмента всегда выступает платёжная карта пользователя, а сценарии могут отличатьсяи включать в себя задействование определённых сервисов и выполнение различных процедур. К такому типу относятся [классические карточные платежи](ru_pm_card_payments.md), в том числе [в рассрочку](pm_instalments.md), а также методы [Apple Pay](pm_applepay.md), [Click to Pay](pm_clicktopay.md) и [Google Pay](pm_googlepay.md). - **[Классические карточные платежи](ru_pm_card_payments.md)** статья о работе с платёжным методом, который позволяет проводить платежи с прямым использованием платёжных карт в большинстве стран и для которого в платформе Ecommpay поддерживаются оплаты разных видов \(в том числе в рассрочку\), возвраты и выплаты - **[Click to Pay](pm_clicktopay.md)** статья о работе с платёжным методом Click to Pay, который позволяет проводить платежи с использованием платёжных карт, сохранённых в сервисе Click to Pay, в большинстве стран мира с применением разных валют и для которого в платформе Ecommpay поддерживаются оплаты в одну и две стадии и возвраты - **[Visa Instalments](pm_instalments.md)** статья о работе с платёжным методом Visa Instalments — функциональным расширением классических карточных платежей с реализацией подхода Buy Now, Pay Later \(BNPL\) **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # Классические карточные платежи {#ru_pm_card_payments} статья о работе с платёжным методом, который позволяет проводить платежи с прямым использованием платёжных карт в большинстве стран и для которого в платформе Ecommpay поддерживаются оплаты разных видов \(в том числе в рассрочку\), возвраты и выплаты *Классические карточные платежи* — метод, позволяющий проводить платежи с прямым использованием платёжных карт в большинстве стран.Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты разных видов\(в том числе [в рассрочку](pm_instalments.md)\), возвраты и выплаты. Метод характеризуется следующими свойствами: |Тип платёжного метода|карточные платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|большинство стран мира| |Валюты платежей|большинство валют мира| |Конвертация валют|+| |Оплаты|+| |Выплаты|+| |Оплаты по сохранённым данным|+| |Полные возвраты|+| |Частичные возвраты|+| |Опротестования|+| |Особенности|–| |Организация и стоимость подключения|По согласованию с курирующим менеджером Ecommpay| Информация о проведении классических карточных платежей через различные интерфейсы платёжной платформы представлена в соответствующих разделах документации — [Payment Page](ru_PP_about.md#section_tqt_nt1_btb), [Gate](ru_Gate_Integration_About.md#section_twd_gmq_qtb) и [Dashboard](ru_dbl_payments.md). **На уровень выше:**[Карточные платежи](ru_pm_cardpayments.md) --- # Click to Pay {#pm_clicktopay} статья о работе с платёжным методом Click to Pay, который позволяет проводить платежи с использованием платёжных карт, сохранённых в сервисе Click to Pay, в большинстве стран мира с применением разных валют и для которого в платформе Ecommpay поддерживаются оплаты в одну и две стадии и возвраты **На уровень выше:**[Карточные платежи](ru_pm_cardpayments.md) ## Обзор {#ru_pm_clicktopay_overview} статья о работе с платёжным методом Click to Pay, который позволяет проводить платежи с использованием платёжных карт, сохранённых в сервисе Click to Pay, в большинстве стран мира с применением разных валют и для которого в платформе Ecommpay поддерживаются оплаты в одну и две стадии и возвраты ### Введение {#section_ql3_5fj_stb .section} Click to Pay — метод, позволяющий проводить платежи с использованием платёжных карт American Express, Maestro, Mastercard и Visa в большинстве стран мира с применением разных валют. При работе с этим методом данные используемых платёжных карт сохраняются с высоким уровнем защиты в сервисе Click to Pay, и для доступа к этим данныммогут применяться разнообразные настольные и мобильные устройства, в том числе работающие под управлением операционных систем Android и iOS. Click to Pay поддерживает проведение платежей в США и Канаде, странах Европейской экономической зоны \(EEA\) и многих из стран Азии, Африки и Южной Америки, при этом покрытие стран и валют активно расширяется. В платёжной платформе Ecommpay поддерживаются оплаты в одну и две стадии и возвраты с применением метода Click to Pay. В этой статье представлена информация о работе с методом Click to Pay: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|карточные платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|большинство стран мира| |Валюты платежей|большинство валют мира| |Конвертация валют|+| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|+| |Особенности|- международные платёжные системы поддерживают и расширяют покрытие стран для метода Click to Pay в соответствии с их критериями \(информацию об этом можно уточнять у курирующего менеджера Ecommpay\) - поддержка метода Click to Pay для пользователей в конкретных странах зависит также от эмитентов платёжных карт в этих странах \(информацию об этом можно уточнять у курирующего менеджера Ecommpay\) - в пользовательском интерфейсе Payment Page Click to Pay выступает как один из вариантов проведения карточной оплаты \(наряду с классическими карточными платежами; подробнее[далее](pm_clicktopay.md#section_bfv_nbd_3cc), в описании сценариев использования\) - при отклонении оплаты методом Click to Pay пользователю может предоставляться повторная попытка с применением классических карточных платежей и, при последующих отклонениях, дополнительные попытки с применением других доступных методов \(подробнее о повторных попытках — [в отдельной статье](ru_PP_Try_Again.md)\) | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Click to Pay задействуются веб-сервис мерчанта, интерфейс Payment Page, платёжная платформа Ecommpay и технические средства сервиса Click to Pay. ![](images/pm/ru_click_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения оплат с использованием метода Click to Pay применяется интерфейс Payment Page, а для выполнения возвратов — интерфейсы Gate и Dashboard. При этом могут быть актуальны различные ограничения по суммам и времени с учётом специфики платёжных систем и эмитентов. ### Сценарии использования {#ru_pm_clicktopay_processing_scenarios} #### Общая информация {#section_ep5_fbd_3cc .section} Проведение оплат с использованием метода Click to Pay осуществляется с регистрацией пользователей и их платёжных карт в сервисе Click to Pay и с выполнением последующих необходимых действий, выполнение возвратов — с заявкой со стороны пользователя и с уведомлением со стороны веб-сервиса. При этом регистрация пользователей и их платёжных карт может выполняться не только в переходе к платежам, но и предварительно: через МПС и эмитентов \(подробнее — [далее](pm_clicktopay.md#section_qlv_wfn_zcc)\). Общие сценарии проведения оплат и выполнения возвратов методом Click to Pay можно представить следующим образом. ![](images/pm/ru_clicktopay_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_clicktopay_interfaces_gate_refund.svg "Возврат через Gate") Частные сценарии проведения оплаты с использованием метода Click to Pay могут отличаться с учётом того, какой пользователь, с какого устройства, через какой браузер и с какой картой участвует в оплате. Основными при этом можно считать следующие сценарии: - *Returning user checkout* \(оплата зарегистрированным пользователем; кратко: *типичная оплата*\) — оплата зарегистрированным пользователем с применением задействованных им ранее устройства, браузера и платёжной карты, а также с идентификацией этого пользователя по адресу его электронной почты и номеру телефона и последующей аутентификацией в сервисе Click to Pay. - *Returning user checkout, unrecognized device* \(оплата зарегистрированным пользователем с нового устройства; кратко: *оплата с нового устройства*\) — оплата зарегистрированным пользователем с применением устройства или браузера, которые не задействовались им ранее. - *Returning user checkout with a new card* \(оплата зарегистрированным пользователем с новой карты; кратко: *оплата с новой карты*\) — оплата зарегистрированным пользователем с применением карты, которая не задействовалась им ранее. - *First time user enrollment* \(оплата с регистрацией пользователя; кратко: *оплата новым пользователем*\) — оплата новым пользователем с его регистрацией в сервисе Click to Pay. **Прим.:** При указании в исходном запросе номера телефона и адреса электронной почты пользователя \(а в некоторых случаях — только одного из этих параметров\) пользовательские сценарии оплаты методом Click to Pay могут облегчаться за счёт автоматической идентификации и аутентификации такого пользователя либо за счёт предварительного заполнения соответствующих полей.В связи с этим рекомендуется регистрировать в веб-сервисе и указывать в запросах на проведение оплат номера телефонов и адреса электронной почты пользователей — чтобы улучшать пользовательский опыт и конверсию платёжной формы. К особенностям оплат с использованием метода Click to Pay можно отнести то, что при их проведении используются специализированные страницы, отображаемые в платёжной форме на основе информации от „фасилитаторов платежей“ \(Digital Card Facilitators, DCF\), в роли которых выступают международные платёжные системы — участницы сервиса Click to Pay, предоставляющие пользователям доступ к цифровым картам. #### Типичная оплата {#section_bfv_nbd_3cc .section} Пользовательский сценарий *типичной оплаты* через Payment Page выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_3.svg "Идентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_4.svg "Аутентификация Click to Pay") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_3.svg "Bыбор карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_4.svg "Уведомление об обработке платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_5.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_6.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_7.svg "Возвращение к веб-сервису") При передаче номера телефона и адреса электронной почты пользователя в исходном запросе \(а в некоторых случаях — только одного из этих параметров\) шаги с идентификацией и аутентификацией пользователя в сервисе Click to Pay пропускаются. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_3.svg "Bыбор карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_4.svg "Уведомление об обработке платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_5.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_6.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_common_7.svg "Возвращение к веб-сервису") #### Оплата с нового устройства {#section_m3s_sbd_3cc .section} Пользовательский сценарий *оплаты с нового устройства* через Payment Page выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_3.svg "Идентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_4.svg "Аутентификация Click to Pay") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_5.svg "Bыбор карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_6.svg "Уведомление об обработке платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_7.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_8.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_9.svg "Возвращение к веб-сервису") Если в исходном запросе передаются номер телефона и адрес электронной почты пользователя \(а в некоторых случаях — только один из этих параметров\), шаг с идентификацией пользователя пропускается. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_4.svg "Аутентификация Click to Pay") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_5.svg "Bыбор карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_6.svg "Уведомление об обработке платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_7.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_8.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_otpcode_9.svg "Возвращение к веб-сервису") #### Оплата с новой карты {#section_bvm_fcd_3cc .section} Пользовательский сценарий *оплаты с новой карты* через Payment Page выглядит следующим образом. При этом, если в исходном запросе передаются номер телефона и адрес электронной почты пользователя, соответствующие поля отображаются предварительно заполненными. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_3.svg "Переход к добавлению карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_4.svg "Указание данных") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_5.svg "Уведомление о добавлении карты") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_6.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_7.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_addcard_8.svg "Возвращение к веб-сервису") #### Оплата новым пользователем {#section_xbv_fcd_3cc .section} Пользовательский сценарий *оплаты новым пользователем* через Payment Page выглядит следующим образом. При этом, если в исходном запросе передаются номер телефона и адрес электронной почты пользователя, соответствующие поля отображаются предварительно заполненными. ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_2.svg "Открытие формы") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_3.svg "Идентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_4.svg "Указание данных") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_5.svg "Уведомление о регистрации") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_6.svg "Аутентификация 3‑D Secure") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_7.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_click_registration_8.svg "Возвращение к веб-сервису") #### Предварительная регистрация {#section_qlv_wfn_zcc .section} Регистрация пользователей и их карт в сервисе Click to Pay может выполняться не только при переходе к платежам\(как в приведённых ранее сценариях\), но и предварительно: - через платёжные системы: - American Expressобеспечивает для держателей карт Amex доступ к учётным записям Click to Pay по адресам электронной почты, которые использовались для создания учётных записей на сайте или в мобильном приложении American Express; - Mastercardдаёт возможность регистрироваться [по ссылке](https://src.mastercard.com/profile/card/add); - Visaдаёт возможность регистрироваться [по ссылке](https://secure.checkout.visa.com/); - через эмитентов платёжных карт— они могут предлагать пользователям создавать учётные записи Click to Pay в своих мобильных приложениях или на сайтах, а также предварительно регистрировать пользователей и их карты в сервисе, если эти карты отвечают заданным критериям отбора. ## Оплаты через Payment Page {#ru_pm_clicktopay_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Click to Pay со стороны веб-сервиса в общем случае необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. При этом в случае с оплатой в две стадии позднее может быть необходимым отправить дополнительный запрос на списание заблокированных средств \([подробнее](ru_platform_dms_model.md)\). Полная схема проведения оплаты в одну стадию выглядит следующим образом. ![](images/pm/ru_clicktopay_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к сервису Click to Pay передаётся запрос на проверку наличия учётной записи пользователя в сервисе Click to Pay. 6. В сервисе Click to Pay выполняется обработка запроса. 7. От сервиса Click to Pay к платёжной платформе передаётся подтверждения наличия учётной записи пользователя. 8. От платёжной платформы к сервису Click to Pay передаётся запрос на получение информации о картах пользователя, привязанных к его учётной записи в сервисе Click to Pay. 9. В сервисе Click to Pay выполняется обработка запроса. 10. От сервиса Click to Pay к платёжной платформе передаётся список доступных платёжных карт пользователя. 11. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 12. Пользователю отображается платёжная форма со списком карт, привязанных к его учётной записи в сервисе Click to Pay. 13. Пользователь выбирает платёжную карту и подтверждает оплату. 14. К сервису Click to Pay передаётся запрос на проведение оплаты с использованием выбранной платёжной карты. 15. В сервисе Click to Pay выполняется обработка запроса. 16. От сервиса Click to Pay к Payment Page передаются данные для отображения страницы ожидания сервиса. 17. Пользователю отображается страница ожидания Click to Pay. 18. От сервиса Click to Pay к платёжной платформе передаётся подтверждение возможности проведения оплаты с использованием выбранной карты. 19. От платёжной платформы к Payment Page направляется информация о подтверждении. 20. Пользователю отображается страница ожидания Payment Page. 21. В платформе выполняются дальнейшая обработка запроса и его отправка к сервису международной платёжной системы. 22. В сервисе международной платёжной системы выполняется обработка платежа. 23. От сервиса международной платёжной системы к платёжной платформе направляется информация о результате оплаты. 24. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 25. От платёжной платформы к Payment Page направляется информация о результате оплаты. 26. Информация о результате оплаты отображается пользователю на Payment Page. В случае с оплатой в две стадии схема блокировки средств через Payment Page с использованием метода Click to Pay идентична представленной схеме оплаты в одну стадию, с той разницей, что вместо незамедлительного списания средств инициируется и выполняется их предварительная блокировка. В остальных сценариях пользовательское взаимодействие с интерфейсом Payment Page соответствует сценариям, представленным [ранее](pm_clicktopay.md), в то время как действия со стороны веб-сервиса не меняются. В дополнение к этому, при использовании возможности повторных попыток и отклонении в каком-либо из сценариев оплаты методом Click to Pay пользователю предоставляется повторная попытка с применением классических карточных платежей и, при последующих отклонениях, дополнительные попытки с применением других доступных методов \(подробнее о повторных попытках — [в отдельной статье](ru_PP_Try_Again.md)\). Информация о форматах запросов и оповещений, используемых для проведения оплат методом Click to Pay через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Click to Pay необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. **Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача параметра `booking_info` с информацией о датах начала и окончания бронируемой услуги \([подробнее](ru_pp_additional_data.md)\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий \([Merchant Category Code, MCC](ru_glossary.md)\) 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922. 2. Для указания варианта проведения оплаты, отличного от заданного по умолчанию для используемого проекта, необходимо указывать параметр `operation_type` со значением `sale`\(для незамедлительного списания средств при оплате в одну стадию\) или `auth`\(для предварительной блокировки средств при оплате в две стадии\). 3. Дополнительно рекомендуется указывать телефонный код страны, номер телефона и адрес электронной почты пользователя в параметрах `customer_phone_country`, `customer_phone` и `customer_email`. Указание этих параметров в запросе позволяет аутентифицировать пользователя на стороне сервиса Click to Payи не отображать соответствующие поля в пользовательском интерфейсе, даже если пользователь применяет устройство или браузер, которые не задействовались им ранее. Если эти параметры отсутствуют в запросе, а пользователь при этом применяет новое устройство или браузер, то в платёжной форме отображаются поля для ввода недостающих значений, а также выполняется аутентификация пользователя в сервисе с использованием одноразового проверочного кода, отправляемого на указанный номер телефона или адрес электронной почты пользователя. ```language-json "customer_phone_country": "44", "customer_phone": "1172345678", "customer_email": "test@test.com" ``` 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Click to Pay должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор пользователя и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` Вместе с тем, рекомендуемый состав параметров может выглядеть следующим образом. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "GBP", "customer_id": "customer1", "customer_phone_country": "44", "customer_phone": "1172345678", "customer_email": "test@test.com", "signature": "oMg2x9dgASNAFUldOcZzUCwX6R\/ekpsdfkIFf==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Click to Pay используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `1204` для пользователя `cust123` была проведена оплата в размере `10,00 USD`. ```language-json { "project_id": 1204, "payment": { "id": "Payment_15671726468667687", "type": "purchase", "status": "success", "date": "2024-08-30T13:58:12+0000", "method": "etoken-click2pay", "sum": { "amount": 1000, "currency": "USD" }, "description": "Purchase" }, "customer": { "id": "cust123" }, "account": { "number": "518600******8785" }, "operation": { "id": 47478000001698, "type": "sale", "status": "success", "date": "2024-08-30T13:58:12+0000", "created_date": "2024-08-30T13:58:06+0000", "request_id": "0a5cb476be3a55010fb050ec1c1cbd35361ac912a3", "sum": { "amount": 1000, "currency": "USD" }, "provider": { "id": 120461, "payment_id": "24fb3f30-000f-5000-8000-1c329d900c68", "date": "2024-08-30T13:58:09+0000", "auth_code": "591748" }, "code": "0", "message": "Success" }, "signature": "5DtWEGy+dMGZZnm3Owjgw9ly67Mb9siv7+WD1u7AyIYdQ==" } ``` В следующем примере оповещение свидетельствует о том, что оплата была отклонена. ```language-json { "account": { "number": "518600******8785" }, "customer": { "id": "cust123" }, "payment": { "date": "2024-08-06T12:57:03+0000", "id": "10906183900", "method": "etoken-click2pay", "status": "decline", "sum": { "amount": 1030000, "currency": "USD" }, "type": "purchase", "description": "test" }, "project_id": 312, "country": "GB", "operation": { "id": 45047000000055, "type": "sale", "status": "decline", "date": "2024-08-06T12:57:03+0000", "created_date": "2024-08-06T12:57:00+0000", "request_id": "f92c3dfdf76133d5e1a9d26279b3b77b7da32e", "sum": { "amount": 1030000, "currency": "USD" }, "provider": { "id": 120461, "payment_id": "5cb2f2fb-e4df-4807-8839-067f9366d506", "auth_code": "" }, "code": "10105", "message": "Insufficient funds on card" }, "signature": "9CIXvWMsKOcQsWEHKLsSVSRo8YNjIxHPjEEQSmLAtClQ==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Возвраты через Gate {#ru_pm_clicktopay_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Click to Pay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_clicktopay_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка к сервису международной платёжной системы. 7. В сервисе международной платёжной системы выполняется обработка возврата. 8. От сервиса международной платёжной системы к платёжной платформе направляется информация о результате возврата. 9. В платёжной платформе обеспечивается обработка полученной информации и передача информации о возврате к сервису Click to Pay, после чего от платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Click to Pay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода Click to Pay необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — буквенный код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Click to Pay должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возвратов с применением метода Click to Pay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `424242` для пользователя `cust123` был выполнен возврат в размере `10,00 USD`. ```language-json { "project_id": 424242, "payment": { "id": "payment_15792507735", "type": "purchase", "status": "refunded", "date": "2024-01-20T08:31:36+0000", "method": "etoken-click2pay", "sum": { "amount": 1000, "currency": "USD" }, "description": "purchase" }, "customer": { "id": "cust123" }, "account": { "number": "518600******8785" }, "operation": { "id": 69512000019571, "type": "refund", "status": "success", "date": "2024-01-20T08:31:36+0000", "created_date": "2024-01-20T08:31:35+0000", "request_id": "e0069513", "sum": { "amount": 1000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 120461, "payment_id": "0000438583", "auth_code": "" } }, "signature": "beJ1deUiEDd+7zuo6YrfSRzgEQj34sKAStuW8Fg==" } ``` В следующем примере оповещение свидетельствует о том, что возврат был отклонён. ```language-json { "project_id": 424242, "payment": { "id": "Payment_1579250773501", "type": "purchase", "status": "success", "date": "2024-01-20T08:31:36+0000", "method": "etoken-click2pay", "sum": { "amount": 100, "currency": "USD" }, "description": "" }, "customer": { "id": "cust123" }, "account": { "number": "518600******8785" }, "operation": { "sum": { "amount": 100000, "currency": "USD" }, "code": "3283", "message": "Refund amount more than init amount", "provider": { "id": 120461, "payment_id": "0000438582", "auth_code": "" }, "id": 69512000019571, "type": "refund", "status": "decline", "date": "2024-01-20T08:31:36+0000", "created_date": "2024-01-20T08:31:35+0000", "request_id": "e0069142" }, "signature": "beJ1deUiEDd+7zuooJzgEQj34sKAStuW8Fg==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Dashboard {#ru_pm_dash_refund} При использовании интерфейса Dashboard можно выполнять возвратыметодом Click to Pay с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата. - Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов. При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры возвратов — требованиям, представленным в разделе [Возвраты через Gate](pm_clicktopay.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о выполнении возвратов через Dashboard представлена в [отдельном разделе](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_clicktopay_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Click to Pay, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к соответствующим разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Visa Instalments {#pm_instalments} статья о работе с платёжным методом Visa Instalments — функциональным расширением классических карточных платежей с реализацией подхода Buy Now, Pay Later \(BNPL\) **На уровень выше:**[Карточные платежи](ru_pm_cardpayments.md) ## Обзор {#ru_pm_instalments_overview} статья о работе с платёжным методом Visa Instalments — функциональным расширением классических карточных платежей с реализацией подхода Buy Now, Pay Later \(BNPL\) ### Введение {#section_ql3_5fj_stb .section} Visa Instalments — функциональное расширение [классических карточных платежей](ru_pm_card_payments.md) с реализацией подхода Buy Now, Pay Later \(BNPL\). Такой подход может использоваться в различных сферах бизнеса и является актуальным, когда пользователям удобно расплачиваться не сразу на полную сумму, а последовательно по частям, в течение заданного количества месяцев.Это, в частности, распространено в туристической отрасли и торговле дорогостоящими товарами и помогает в привлечении и удержании клиентов и в построении устойчивого бизнеса. Платежи Visa Instalments могут быть доступны как вариант карточной оплаты при использовании со стороны пользователей кредитных карт Visa от тех эмитентов, которые поддерживают сервис по проведению платежей с рассрочкой Visa Instalment Solution. В платёжной платформе Ecommpay поддерживаются оплаты Visa Instalments с применением платёжной формы Payment Page и зачислением полной суммы оплаты на баланс мерчанта в одну или две стадии \(с предварительной блокировкой\).При этом функциональность доступна только для мерчантов, работающих в Великобритании. В этой статье представлена информация о работе с оплатами Visa Instalments: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|карточные платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|[GB](references/ru/countries/GB.md)| |Валюты платежей|[GBP](references/ru/currencies/GBP.md)| |Конвертация валют|+| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|+| |Особенности|согласно разделу, представленному [далее](pm_instalments.md#section_nxx_cfl_5fc)| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay, дополнительную информацию можно получить в [Ecommpay shop](https://ecommpay.com/payment-methods/payment-method-finder/)| ### Особенности и ограничения {#section_nxx_cfl_5fc .section} При работе с возможностью Visa Instalments необходимо учитывать следующие особенности и ограничения. - Функциональность доступна только для мерчантов, работающих на рынке Великобритании. - Могут использоваться только кредитные карты Visa, которые выпущены эмитентами, базирующимися в Великобритании и поддерживающими программу Visa Instalments. - Пользователи, оплачивающие покупки с использованием этой функциональности, должны быть информированы о том, что это один из видов кредитования, с уменьшением доступных средств по используемой карте и с обязательством своевременного погашения задолженности \(в соответствии с планом рассрочки\). При срывах в погашении задолженности эмитенты могут выставлять дополнительные комиссии держателям карт. - Решение о допустимости рассрочки в каждом конкретном случае принимается на стороне эмитента. - Функциональность поддерживается только при использовании платёжной формы Payment Page 5-го поколения и допустима для разовых одностадийных и двухстадийных оплат, как с указанием платёжных данных в явном виде, так и с использованием сохранённых данных и токенов. - Вместе с основной комиссией за проведение оплаты по итогам проведения через платёжную платформу каждой оплаты Visa Instalments \(с получением суммы платежа от эмитента\) с мерчанта взимается дополнительная комиссия в пользу платёжной системы Visa и Ecommpay. Информацию об этой комиссии, как и о любых других, можно получить у курирующего менеджера Ecommpay. С вопросами об ограничениях, условиях использования и перспективах расширения такой функциональности на другие регионы можно обращаться к курирующему менеджеру Ecommpay, с техническими вопросами — к специалистам технической поддержки. ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельной оплаты Visa Instalments задействуются веб-сервис мерчанта, интерфейс Payment Page, платёжная платформа Ecommpay и технические средства сервиса Visa Instalments и эмитента используемой карты. ![](images/ecommpay/ru_instalments_functional.svg) В процессе оплаты Visa Instalments пользователь самостоятельно выбирает период рассрочки и подтверждает расчёты с эмитентом согласно выбранному плану. При этом из суммы средств, доступных держателю используемой кредитной карты, сразу вычитается полная сумма оплаты — на условиях эмитента по программе рассрочки. И в дальнейшем пользователь рассчитывается напрямую с эмитентом. ![](images/ecommpay/ru_pp_visa_instalments_plan_selection.svg "Оплата Visa Instalments") В свою очередь, мерчант при такой оплате сразу получает полную сумму платежа \(без разбиения на части, но с вычетом полагающихся комиссий, как и при других оплатах\), поскольку эта сумма выплачивается эмитентом используемой кредитной карты. ### Сценарий использования {#section_fgt_sdl_ggb .section} Базовый пользовательский сценарий проведения оплаты с использованием возможности Visa Instalments выглядит следующим образом. ![](images/ecommpay/ru_pp_visa_instalments_1.svg "Переход к оплате") ![](images/ecommpay/ru_pp_visa_instalments_2.svg "Ввод номера карты") ![](images/ecommpay/ru_pp_visa_instalments_3.svg "Проверка возможности оплаты в рассрочку") ![](images/ecommpay/ru_pp_visa_instalments_4.svg "Уведомление о доступности Visa Instalments") ![](images/ecommpay/ru_pp_visa_instalments_5.svg "Отображение доступных планов рассрочки") ![](images/ecommpay/ru_pp_visa_instalments_6.svg "Выбор плана рассрочки") ![](images/ecommpay/ru_pp_visa_instalments_7.svg "Подтверждение оплаты") ![](images/ecommpay/ru_pp_visa_instalments_8.svg "Завершение оплаты") В рамках этого сценария: 1. Пользователь переходит в веб-сервисе к оплате. 2. Пользователь выбирает в платёжной форме платёжный метод и указывает номер карты. 3. Пользователю отображается сообщение о проверке возможности оплаты в рассрочку — **Checking instalment eligibility** \(поскольку для используемого проекта доступна возможность оплат Visa Instalments\). 4. По итогам проверки пользователю отображается уведомление о том, что для указанной карты доступна оплата в рассрочку, после чего он при необходимости указывает остающиеся данные и переходит далее. 5. Пользователю отображаются доступные планы рассрочки, вместе с базовым вариантом оплаты полной суммы \(без рассрочки\). 6. Пользователь выбирает подходящий план рассрочки и переходит далее. Если на этапе выбора плана пользователю необходима дополнительная информация об оплатах Visa Instalments, он может переходить к ней с помощью ссылки **Learn more** \(с открытием модального окна со справочной информацией\). 7. Пользователю отображается информация об условиях выбранного плана рассрочки, после чего он подтверждает проведение оплаты выбранным способом. 8. Пользователю последовательно отображаются страницы ожидания и завершения оплаты. По итогам проведения оплаты на указанный адрес электронной почты или номер телефона пользователя отправляется чек-уведомление с детальной информацией о плане рассрочки.Помимо типовой информации, в таком чеке указываются: - количество частей, на которые разбита оплата; - общая стоимость покупки с учётом всех комиссий; - общая сумма комиссий; - применяемая годовая процентная ставка \(Annual Percentage Rate, APR\); - сумма ежемесячного платежа. ![](images/ecommpay/ru_pp_visa_instalments_receipt.svg "Уведомление о проведённой оплате") ## Оплаты через Payment Page {#ru_pm_instalments_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты Visa Instalments через Payment Page со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. При этом в случае с оплатой в две стадии позднее может быть необходимым отправить дополнительный запрос на списание заблокированных средств \([подробнее](ru_pp_purchase_auth.md)\).Полная схема проведения оплаты в одну стадию выглядит следующим образом. ![](images/ecommpay/ru_instalments_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает платёжный метод и указывает номер карты. 8. В платёжную платформу передаётся запрос на проверку доступности оплаты в рассрочку. 9. В платёжной платформе выполняется обработка полученного запроса и его отправка в платёжную среду. 10. В платёжной среде выполняется обработка платежа. 11. От платёжной среды к платёжной платформе направляется информация о доступных планах рассрочки. 12. От платёжной платформы к Payment Page направляется информация о доступных планах рассрочки. 13. Пользователю отображается информация о доступных планах рассрочки. 14. Пользователь выбирает подходящий план рассрочки и подтверждает оплату выбранным способом. 15. В платёжную платформу передаётся запрос на проведение оплаты Visa Instalments. 16. В платёжной платформе выполняются обработка полученного запроса и его отправка в платёжную среду. 17. В платёжной среде выполняется обработка платежа. 18. От платёжной среды к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. В случае с оплатой в две стадии схема блокировки средств через Payment Page идентична представленной схеме оплаты в одну стадию, с той разницей, что вместо незамедлительного списания средств инициируется и выполняется их предварительная блокировка. Информация о форматах запросов и оповещений, используемых для проведения оплат Visa Instalments через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} Поскольку оплаты Visa Instalments являются функциональным расширением классических карточных платежей, формат запросов на такие оплаты соответствует формату для классических карточных платежей, с учётом требований и рекомендаций к параметрам, которые перечислены в статьях [Проведение оплат](ru_pp_purchase.md) и [Блокировка средств](ru_pp_purchase_auth.md). В целом, при формировании запросов на открытие платёжной формы необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Для указания варианта проведения оплаты, отличного от заданного по умолчанию для используемого проекта, необходимо указывать параметр `operation_type` со значением `sale`\(для незамедлительного списания средств при оплате в одну стадию\) или `auth`\(для предварительной блокировки средств при оплате в две стадии\). 3. Дополнительно рекомендуется указывать почтовые индекс и адрес пользователя в параметрах `avs_post_code` и `avs_street_address`. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в статьях [Проверка Address Verification Service](ru_PP_avs.md) и [Дополнение информации о платежах](ru_pp_clarification.md)\). 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, в общем случае корректный запрос на открытие платёжной формы должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор пользователя и подпись, а также может содержать различные дополнительные параметры. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 60000, "payment_currency": "GBP", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 60000, "payment_currency": "GBP", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат Visa Instalments используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). К особенностям оповещений в случае с оплатами Visa Instalments можно отнести то, что в объектах `installment_plan` могут передаваться сведения о выбранных пользователями планах рассрочки. Включение таких объектов в состав оповещений настраивается по согласованию со специалистами технической поддержки Ecommpay. ``` {#codeblock_z1z_cmv_qgc .language-json} { "installment_plan": { "payment_frequency": "M", "payment_count": 9, "cost": { "currency": "GBP", "total_cost": 60000, "total_fee_amount": 3825, "regular_payment": { "total_amount": 7092 }, "first_payment": { "total_amount": 7092 }, "last_payment": { "total_amount": 7089 }, "annual_percentage_rate": 8.5 }, "reference": "Y38135539", "terms_and_conditions": { "text": "text_eng", "url": "https://www.fornaxbank.co.uk" } } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page. - [Блокировка средств](ru_pp_purchase_auth.md)— о том, как проводить разовые оплаты со списанием после предварительной блокировки через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_instalments_dash_analysis} Для анализа информации об оплатах Visa Instalments можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Банковские платежи {#ru_pm_bankpayments} статьи о платёжных методах группы банковских платежей, в которых переводы средств выполняются с использованием специализированных банковских онлайн-сервисов *Банковские платежи* — это платежи, для проведения которых используются специализированные банковские онлайн-сервисы, позволяющие переводить средства между пользователем и мерчантом \(напрямую или через счёт провайдера\). Платёжным инструментом при этом выступает банковский счёт пользователя, а в сценариях проведения платежей могут применяться технологии интернет-банкинга, банковских переводов и других банковских сервисов. К таким платёжным методам относятся: - [Bancontact](pm_bancontact.md) - Банки Юго-Восточной Азии: - [Banks of Hong Kong](pm_hk_banks.md) - [Banks of the Philippines](pm_philippines.md) - [Indonesian Online Banking](pm_indonesia.md) - [Malaysian Online Banking](pm_malaysia.md) - [Thai Online Banking](pm_thailand.md) - [Vietnamese Online Banking](pm_vietnam.md) - [Blik](pm_blik.md) - [Brazil Online Banking](pm_brazil_ob.md) - [Buy Now Pay Later](pm_bnpl.md) - [Chile Online Banking](pm_chile_ob.md) - [China UnionPay](pm_unionpay.md) - [Ecuador Online Banking](pm_ecuador_ob.md) - [EPS](pm_eps.md) - [iDEAL \| Wero](pm_ideal.md) - [Indonesian Virtual Accounts](pm_indonesia_va.md) - [Mexico Online Banking](pm_mexico_ob.md) - [Multibanco](pm_multibanco.md) - [MyBank](pm_mybank.md) - Open Banking\([группа методов](pm_openbanking.md)\) в странах Европы: | - [Austria](pm_austria.md) - [Belgium](pm_belgium.md) - [Denmark](pm_denmark.md) - [Estonia](pm_estonia.md) - [Finland](pm_finland.md) - [France](pm_france.md) - [Germany](pm_germany.md) - [Hungary](pm_hungary.md) - [Italy](pm_italy.md) - [Ireland](pm_ireland.md) - [Latvia](pm_latvia.md) | - [Lithuania](pm_lithuania.md) - [Luxembourg](pm_luxembourg.md) - [Netherlands](pm_netherlands.md) - [Norway](pm_norway.md) - [Poland](pm_poland.md) - [Portugal](pm_portugal.md) - [Romania](pm_romania.md) - [Spain](pm_spain.md) - [Sweden](pm_sweden.md) - [United Kingdom](pm_uk.md) | | | - [Peru Online Banking](pm_peru_ob.md) - [Philippines Over the Counter & ATM](pm_philippines_atm.md) - [PIX](pm_pix.md) - [Przelewy24](pm_przelewy.md) - [Swish](pm_swish.md) - [Выплаты на банковские счета в ЕЗПЕ \(SEPA\)](pm_bankpayout_sepa.md) - [Локальные выплаты на банковские счета в Великобритании](pm_bankpayout_uk.md) - **[Bancontact](pm_bancontact.md)** статья о работе с платёжным методом Bancontact, который позволяет проводить платежи в евро с использованием платёжных карт в Бельгии и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Banks of Hong Kong](pm_hk_banks.md)** статья о работе с платёжным методом Banks of Hong Kong, который позволяет проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге и для которого в платформе Ecommpay поддерживаются выплаты - **[Banks of the Philippines](pm_philippines.md)** статья о работе с платёжным методом Banks of the Philippines, который позволяет проводить платежи в филиппинских песо с использованием банковских счетов в Филиппинах и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[Blik](pm_blik.md)** статья о работе с платёжным методом Blik, который позволяет проводить платежи в злотых с банковских счетов в Польше и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Brazil Online Banking](pm_brazil_ob.md)** статья о работе с платёжным методом Brazil Online Banking, который позволяет проводить платежи в бразильских реалах и долларах США с использованием банковских счетов в Бразилии и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Buy Now Pay Later](pm_bnpl.md)** статья о работе с платёжным методом Buy Now Pay Later, который позволяет проводить платежи в фунтах стерлингов с использованием рассрочки в Великобритании и для которого в платформе Ecommpay поддерживаются оплаты - **[Chile Online Banking](pm_chile_ob.md)** статья о работе с платёжным методом Chile Online Banking, который позволяет проводить платежи в долларах США и чилийских песо с использованием банковских счетов в Чили и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[China UnionPay](pm_unionpay.md)** статья о работе с платёжным методом China UnionPay, который позволяет проводить платежи в разных валютах с использованием платёжных карт в разных странах и для которого в платформе Ecommpay поддерживаются оплаты и возврат - **[Ecuador Online Banking](pm_ecuador_ob.md)** статья о работе с платёжным методом Ecuador Online Banking, который позволяет проводить платежи в долларах США с использованием банковских счетов в Эквадоре и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[EPS](pm_eps.md)** статья о работе с платёжным методом EPS, который позволяет проводить платежи в евро с использованием банковских счетов в Австрии и для которого в платформе Ecommpay поддерживаются оплаты - **[iDEAL \| Wero](pm_ideal.md)** статья о работе с платёжным методом iDEAL \| Wero, который позволяет проводить платежи в евро с использованием банковских счетов в Нидерландах и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Indonesian Online Banking](pm_indonesia.md)** статья о работе с платёжным методом Indonesian Online Banking, который позволяет проводить платежи в индонезийских рупиях с использованием банковских счетов в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[Indonesian Virtual Accounts](pm_indonesia_va.md)** статья о работе с платёжным методом Indonesian Virtual Accounts, который позволяет проводить платежи в индонезийских рупиях с использованием наличных, банковских счетов и платёжных карт в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты - **[Malaysian Online Banking](pm_malaysia.md)** статья о работе с платёжным методом Malaysian Online Banking, который позволяет проводить платежи в малайзийских ринггитах с использованием банковских счетов в Малайзии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[Mexico Online Banking](pm_mexico_ob.md)** статья о работе с платёжным методом Mexico Online Banking, который позволяет проводить платежи в долларах США и мексиканских песо с использованием банковских счетов в Мексике и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Multibanсo](pm_multibanco.md)** статья о работе с платёжным методом Multibanсo, который позволяет проводить платежи в евро с использованием банковских счетов в Португалии и для которого в платформе Ecommpay поддерживаются оплаты - **[MyBank](pm_mybank.md)** статья о работе с платёжным методом MyBank, который позволяет проводить платежи в евро с использованием банковских счетов в разных европейских странах и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Open Banking](pm_openbanking.md)** статья о группе методов Open Banking, базирующихся на применении открытых банковских протоколов и позволяющих проводить платежи в евро и ряде других европейских валют через различные банки Европы с использованием банковских счетов - **[Open Banking in Austria](pm_austria.md)** статья о работе с платёжным методом Open Banking in Austria, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Австрии - **[Open Banking in Belgium](pm_belgium.md)** статья о работе с платёжным методом Open Banking in Belgium, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Бельгии - **[Open Banking in Denmark](pm_denmark.md)** статья о работе с платёжным методом Open Banking in Denmark, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Дании - **[Open Banking in Estonia](pm_estonia.md)** статья о работе с платёжным методом Open Banking in Estonia, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Эстонии - **[Open Banking in Finland](pm_finland.md)** статья о работе с платёжным методом Open Banking in Finland, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Финляндии - **[Open Banking in France](pm_france.md)** статья о работе с платёжным методом Open Banking in France, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Франции - **[Open Banking in Germany](pm_germany.md)** статья о работе с платёжным методом Open Banking in Germany, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Германии - **[Open Banking in Hungary](pm_hungary.md)** статья о работе с платёжным методом Open Banking in Hungary, который относится к группе Open Banking и позволяет проводить платежи в форинтах через банки Венгрии - **[Open Banking in Italy](pm_italy.md)** статья о работе с платёжным методом Open Banking in Italy, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Италии - **[Open Banking in Ireland](pm_ireland.md)** статья о работе с платёжным методом Open Banking in Ireland, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Ирландии - **[Open Banking in Latvia](pm_latvia.md)** статья о работе с платёжным методом Open Banking in Latvia, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Латвии - **[Open Banking in Lithuania](pm_lithuania.md)** статья о работе с платёжным методом Open Banking in Lithuania, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Литвы - **[Open Banking in Luxembourg](pm_luxembourg.md)** статья о работе с платёжным методом Open Banking in Luxembourg, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Люксембурга - **[Open Banking in the Netherlands](pm_netherlands.md)** статья о работе с платёжным методом Open Banking in the Netherlands, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Нидерландов - **[Open Banking in Norway](pm_norway.md)** статья о работе с платёжным методом Open Banking in Norway, который относится к группе Open Banking и позволяет проводить платежи в норвежских кронах через банки Норвегии - **[Open Banking in Poland](pm_poland.md)** статья о работе с платёжным методом Open Banking in Poland, который относится к группе Open Banking и позволяет проводить платежи в злотых через банки Польши - **[Open Banking in Portugal](pm_portugal.md)** статья о работе с платёжным методом Open Banking in Portugal, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Португалии - **[Open Banking in Romania](pm_romania.md)** статья о работе с платёжным методом Open Banking in Romania, который относится к группе Open Banking и позволяет проводить платежи в леях через банки Румынии - **[Open Banking in Spain](pm_spain.md)** статья о работе с платёжным методом Open Banking in Spain, который относится к группе Open Banking и позволяет проводить платежи в евро через банки Испании - **[Open Banking in Sweden](pm_sweden.md)** статья о работе с платёжным методом Open Banking in Sweden, который относится к группе Open Banking и позволяет проводить платежи в шведских кронах через банки Швеции - **[Open Banking in the UK](pm_uk.md)** статья о работе с платёжным методом Open Banking in the UK, который относится к группе Open Banking и позволяет проводить платежи в фунтах через банки Великобритании - **[Peru Online Banking](pm_peru_ob.md)** статья о работе с платёжным методом Peru Online Banking, который позволяет проводить платежи в долларах США и перуанских солях с использованием банковских счетов в Перу и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Philippines Over the Counter & ATM](pm_philippines_atm.md)** статья о работе с платёжным методом Philippines Over the Counter & ATM, который позволяет проводить платежи в филиппинских песо с использованием наличных и платёжных карт в Филиппинах и для которого в платформе Ecommpay поддерживаются оплаты - **[PIX](pm_pix.md)** статья о работе с платёжным методом PIX, который позволяет проводить платежи в бразильских реалах и долларах США с использованием банковских счетов в Бразилии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[Przelewy24](pm_przelewy.md)** статья о работе с платёжным методом Przelewy24, который позволяет проводить платежи в евро и злотых с использованием банковских счетов и платёжных карт в Польше и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Swish](pm_swish.md)** статья о работе с платёжным методом Swish, который позволяет проводить платежи в шведских кронах с использованием банковских счетов в Швеции и для которого в платформе Ecommpay поддерживаются оплаты и возвраты - **[Thai Online Banking](pm_thailand.md)** статья о работе с платёжным методом Thai Online Banking, который позволяет проводить платежи в тайских батах с использованием банковских счетов в Таиланде и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[Vietnamese Online Banking](pm_vietnam.md)** статья о работе с платёжным методом Vietnamese Online Banking, который позволяет проводить платежи в вьетнамских донгах с использованием банковских счетов во Вьетнаме и для которого в платформе Ecommpay поддерживаются оплаты и выплаты - **[«Выплаты на банковские счета в ЕЗПЕ \(SEPA\)»](pm_bankpayout_sepa.md)** статья о работе с платёжным методом «Выплаты на банковские счета в ЕЗПЕ \(SEPA\)», который позволяет проводить платежи в евро с использованием банковских счетов в странах ЕЗПЕ и для которого в платформе Ecommpay поддерживаются выплаты - **[«Локальные выплаты на банковские счета в Великобритании»](pm_bankpayout_uk.md)** статья о работе с платёжным методом «Локальные выплаты на банковские счета в Великобритании», который позволяет проводить платежи в фунтах стерлингов с использованием банковских счетов в Великобритании и для которого в платформе Ecommpay поддерживаются выплаты **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # Bancontact {#pm_bancontact} статья о работе с платёжным методом Bancontact, который позволяет проводить платежи в евро с использованием платёжных карт в Бельгии и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_bancontact_overview} ### Введение {#section_ql3_5fj_stb .section} Bancontact — метод, позволяющий проводить платежи в евро с использованием платёжных карт в Бельгии. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом Bancontact: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|[BE](references/ru/countries/BE.md)| |Валюты платежей|[EUR](references/ru/currencies/EUR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|если сумма платежа превышает 500,00 [EUR](references/ru/currencies/EUR.md), то такой платёж не может быть совершён с использованием мобильного приложения Bancontact| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/bancontact/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Bancontact задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса Bancontact. ![](images/pm/ru_bancontact_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Bancontact могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [EUR](references/ru/currencies/EUR.md)|Время¹| |минимум|максимум|базовое|предельное| |--|---------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|1,00|–|–|30 дней| |Возвраты|–|–|–|–| **Прим.:** 1. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Bancontact осуществляется с перенаправлением пользователей к сервису Bancontact, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_bancontact_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_bancontact_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_bancontact_interfaces_gate_refund.svg "Возврат через Gate") ## Оплаты через Payment Page {#ru_pm_bancontact_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Bancontact со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_bancontact_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Bancontact. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Bancontact. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Bancontact. 10. В сервисе Bancontact выполняется обработка запроса на оплату. 11. От сервиса Bancontact к платёжной платформе передаются данные для перенаправления пользователя к сервису Bancontact. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису Bancontact. 14. Пользователь выполняет необходимые действия для оплаты. Если сумма платежа меньше 500,00 [EUR](references/ru/currencies/EUR.md), то пользователю, помимо полей для ввода данных платёжной карты Bancontact, отображается QR-код для сканирования с использованием мобильного приложения Bancontact. Пользователь может выбрать один из упомянутых вариантов для совершения оплаты. Если сумма платежа больше 500,00 [EUR](references/ru/currencies/EUR.md), то пользователю не отображается QR-код и оплата не может быть совершена с использованием мобильного приложения. 15. В сервисе Bancontact выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе Bancontact. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса Bancontact к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Bancontact через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Bancontact необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно рекомендуется указывать фамилию пользователя в параметре `customer_last_name` \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если этот параметров отсутствует в запросе, в платёжной форме может отобразиться поле для ввода пользователем недостающего значения \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Для предварительного выбора метода Bancontact необходимо указывать код этого метода в параметре `force_payment_method` — `bancontact`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Bancontact должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и фамилию пользователя, а также подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "EUR", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "EUR", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Bancontact используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `211` была проведена оплата в размере `10,00 EUR`. ```language-json { "project_id": 211, "payment": { "id": "ECT_TEST_1562051806691899", "type": "purchase", "status": "success", "date": "2019-07-02T09:28:29+0000", "method": "bancontact", "sum": { "amount": 1000, "currency": "EUR" }, "description": "ECT_TEST_1562051806691810" }, "customer": { "last_name": "Johnson" }, "operation": { "id": 37493000003351, "type": "sale", "status": "success", "date": "2019-07-02T09:28:29+0000", "created_date": "2019-07-02T09:28:24+0000", "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1241, "payment_id": "", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "e7wGQAoo1wKMPwsJVCg4zwpWiZVR83hnRnYsIZ84g==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 211, "payment": { "id": "ECT_TEST_1562051806691810", "type": "purchase", "status": "decline", "date": "2019-07-02T09:28:29+0000", "method": "bancontact", "sum": { "amount": 50, "currency": "EUR" } }, "customer": { "last_name": "Johnson" }, "operation": { "id": 37493000003351, "type": "sale", "status": "decline", "date": "2019-07-02T09:28:29+0000", "created_date": "2019-07-02T09:28:24+0000", "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c", "sum_initial": { "amount": 50, "currency": "EUR" }, "sum_converted": { "amount": 50, "currency": "EUR" }, "provider": { "id": 1241, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "e7wGQAoo1wKMPwsJVCghpAH3AqwpWiZVR83hnRnYsIZ84g==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_bancontact_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Bancontact со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису Bancontact. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_bancontact_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Bancontact. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Bancontact. 7. В сервисе Bancontact выполняется обработка запроса на оплату. 8. От сервиса Bancontact к платёжной платформе передаются данные для перенаправления пользователя к сервису Bancontact. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Bancontact. 10. Пользователь перенаправляется к сервису Bancontact. 11. Пользователь выполняет необходимые действия для оплаты. Если сумма платежа меньше 500,00 [EUR](references/ru/currencies/EUR.md), то пользователю, помимо полей для ввода данных платёжной карты Bancontact, отображается QR-код для сканирования с использованием мобильного приложения Bancontact. Пользователь может выбрать один из упомянутых вариантов для совершения оплаты. Если сумма платежа больше 500,00 [EUR](references/ru/currencies/EUR.md), то пользователю не отображается QR-код и оплата не может быть совершена с использованием мобильного приложения. 12. В сервисе Bancontact выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса Bancontact к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Bancontact через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Bancontact необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `[/v2/payment/bancontact/sale](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bancontact-sale)`. 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `last_name` — фамилия пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если параметр не указан в запросе, то он дополнительно запрашивается в оповещении о необходимости дополнить данные \(подробнее — в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md)\); - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для перенаправления пользователя по нажатию кнопки на любом шаге оплаты. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Bancontact должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 211, "payment_id": "payment_id", "signature": "PLwY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 1000, "currency": "EUR" }, "customer": { "last_name": "Johnson", "id": "123", "ip_address": "192.0.2.0" }, "return_url": { "return": "http://example.com/return" } } ``` ```language-json { "general": { "project_id": 211, "payment_id": "payment_id", "signature": "PLwY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 1000, "currency": "EUR" }, "customer": { "last_name": "Johnson", "id": "123", "ip_address": "192.0.2.0" }, "return_url": { "return": "http://example.com/return" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису Bancontact при проведении каждого платежа с использованием метода Bancontact необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": [], "method": "GET", "url": "https://bancontact.girogate.be/bi/t0bc?tx=example ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах оплат с применением метода Bancontact используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `211` была проведена оплата в размере `10,00 EUR`. ```language-json { "project_id": 211, "payment": { "id": "ECT_TEST_1562051806691899", "type": "purchase", "status": "success", "date": "2019-07-02T09:28:29+0000", "method": "bancontact", "sum": { "amount": 1000, "currency": "EUR" }, "description": "ECT_TEST_1562051806691810" }, "customer": { "last_name": "Johnson" }, "operation": { "id": 37493000003351, "type": "sale", "status": "success", "date": "2019-07-02T09:28:29+0000", "created_date": "2019-07-02T09:28:24+0000", "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1241, "payment_id": "", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "e7wGQAoo1wKMPwsJVCg4zwpWiZVR83hnRnYsIZ84g==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 211, "payment": { "id": "ECT_TEST_1562051806691810", "type": "purchase", "status": "decline", "date": "2019-07-02T09:28:29+0000", "method": "bancontact", "sum": { "amount": 50, "currency": "EUR" } }, "customer": { "last_name": "Johnson" }, "operation": { "id": 37493000003351, "type": "sale", "status": "decline", "date": "2019-07-02T09:28:29+0000", "created_date": "2019-07-02T09:28:24+0000", "request_id": "7e08d48c4f5da3692b65e5426f44ed36896e569c", "sum_initial": { "amount": 50, "currency": "EUR" }, "sum_converted": { "amount": 50, "currency": "EUR" }, "provider": { "id": 1241, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "e7wGQAoo1wKMPwsJVCghpAH3AqwpWiZVR83hnRnYsIZ84g==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_bancontact_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Bancontact со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_bancontact_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Bancontact. 7. В сервисе Bancontact выполняется обработка возврата. 8. От сервиса Bancontact к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Bancontact через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возврат с применением метода Bancontact необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке `[/v2/payment/bancontact/refund](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bancontact-refund)`. 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Bancontact должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "EUR" }, "customer": { "ip_address": "192.0.2.0" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "EUR" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возврата с применением метода Bancontact используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `211` был выполнен возврат в размере `10,00 EUR`. ``` { "project_id": 211, "payment": { "id": "refund_02", "type": "purchase", "status": "refunded", "date": "2019-02-19T14:25:25+0000", "method": "bancontact", "sum": { "amount": 1000, "currency": "EUR" }, "description": "test_02" }, "account": { "number": "035209875690435" }, "operation": { "id": 14153000003282, "type": "refund", "status": "success", "date": "2019-02-19T14:25:25+0000", "created_date": "2019-02-19T14:25:24+0000", "request_id": "9d11b2ca618ec3ba0f588af8af3c4fc9f5fa58f174", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1169, "payment_id": "105887607", "date": "2019-02-19T14:25:24+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "of8k9xerKSKpFBR4XL1QFaDH3p9ZYO56lCv+f1M0Sf/7eg==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ```language-json { "project_id": 211, "payment": { "id": "refund_02", "type": "purchase", "status": "success", "date": "2019-02-19T14:25:25+0000", "method": "bancontact", "sum": { "amount": 100000, "currency": "EUR" }, "description": "test_02" }, "account": { "number": "035209875690435" }, "operation": { "id": 14153000003282, "type": "refund", "status": "decline", "date": "2019-02-19T14:25:25+0000", "created_date": "2019-02-19T14:25:24+0000", "request_id": "9d11b2ca618ec3ba0f588af8af3c4fc9f5fa58f174", "sum_initial": { "amount": 100000, "currency": "EUR" }, "sum_converted": { "amount": 100000, "currency": "EUR" }, "provider": { "id": 1169, "payment_id": "105887607", "date": "2019-02-19T14:25:24+0000", "auth_code": "" }, "code": "3283", "message": "Refund amount more than init amount" }, "signature": "of8k9xerKSKpFwKJ7KLTZYO56lCv+f1M0Sf/7eg==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_bancontact_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Bancontact, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Banks of Hong Kong {#pm_hk_banks} статья о работе с платёжным методом Banks of Hong Kong, который позволяет проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге и для которого в платформе Ecommpay поддерживаются выплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_hk_banks_overview} статья о работе с платёжным методом Banks of Hong Kong, который позволяет проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге и для которого в платформе Ecommpay поддерживаются выплаты ### Введение {#section_ql3_5fj_stb .section} Banks of Hong Kong — метод, позволяющий проводить платежи в гонконгских долларах и юанях с использованием банковских счетов в Гонконге. Для этого метода в платёжной платформе Ecommpay поддерживаются выплаты. В этой статье представлена информация о работе с методом Banks of Hong Kong: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[HK](references/ru/countries/HK.md)| |Валюты платежей|[HKD](references/ru/currencies/HKD.md), [CNY](references/ru/currencies/CNY.md)| |Конвертация валют|–| |Разовые оплаты|–| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|+| |Опротестования|–| |Особенности|–| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/bank-payouts-hong-kong/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Banks of Hong Kong задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_hk_banks_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Banks of Hong Kong могут применяться различные интерфейсы платёжной платформы. Так выплаты могут проводиться через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения. ||Суммы, [HKD](references/ru/currencies/HKD.md)| |минимум|максимум| |--|---------------------------------------------| |-------|--------| |Выплаты|–|4 000 000,00| ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение выплат осуществляется с уведомлением пользователей через веб-сервис мерчанта. ![](images/pm/ru_hk_banks_interfaces_gate_payout.svg "Выплата через Gate") Вместе с тем, к особенностям работы с методом Banks of Hong Kong можно отнести то, что для каждого платежа с использованием этого метода должен быть указан конкретный банк. При работе через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Способы работы с идентификаторами банков описаны в следующем подразделе, [Поддержка со стороны банков](pm_hk_banks.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы некоторых банков, поддерживающих работу с методом Banks of Hong Kong. Более подробный список представлен по ссылке: [Список поддерживаемых банков](files_for_downloads/Banks%20of%20Hong%20Kong/pm_hk_banks_list.pdf). Данную информацию следует уточнять у курирующего менеджера Ecommpay. |Банк|ID| |----|--| |BANK OF CHINA \(HONG KONG\) LIMITED Cheung Chau Branch|54661| |BANK OF COMMUNICATIONS CO., LTD. Hong Kong Branch|53911| |CHANG HWA COMMERCIAL BANK LTD Hong Kong Branch|53121| |CHINA CITIC BANK INTERNATIONAL LIMITED Mei Foo Branch|36991| |CHINA CONSTRUCTION BANK \(ASIA\) CORPORATION LIMITED Hunghom Ma Tau Wai Road Branch|53571| |CHONG HING BANK LTD Hong Kong Main Branch|31061| |CHONG HING BANK LTD North Point Branch|54311| |CIMB BANK BERHAD Hong Kong Branch|54021| |CITIBANK \(HONG KONG\) LIMITED Mei Foo Sun Chuen Branch|54481| |DAH SING BANK LTD Fortress Hill Branch|54071| |DAH SING BANK LTD Tai Po Branch|53181| |DBS BANK \(HONG KONG\) LIMITED Yaumatei Branch|54441| |FUBON BANK \(HONG KONG\) LIMITED Chai Wan Branch|53851| |FUBON BANK \(HONG KONG\) LIMITED Yuen Long Branch|48651| |HANG SENG BANK LTD Fortune Kingswood Branch|35031| |HANG SENG BANK LTD Tai Po Branch|54651| |INDUSTRIAL AND COMMERCIAL BANK OF CHINA \(ASIA\) LTD Central Branch|54471| |NANYANG COMMERCIAL BANK LTD Western Branch|54221| |OCBC WING HANG BANK LIMITED Fortress Hill Branch|53031| |PUBLIC BANK \(HONG KONG\) LIMITED Prince Edward Branch|53821| |PUBLIC BANK \(HONG KONG\) LIMITED Tai Po Branch|44931| |SHANGHAI COMMERCIAL BANK LTD Mongkok Branch|54511| |SHANGHAI COMMERCIAL BANK LTD West Point Branch|54551| |STANDARD CHARTERED BANK \(HONG KONG\) LIMITED Kwun Tong Branch|54011| |TAI YAU BANK LTD Head Office|25681| |THE BANK OF EAST ASIA, LTD Chai Wan Branch|43941| |THE BANK OF EAST ASIA, LTD Main Branch|27401| |THE HONGKONG AND SHANGHAI BANKING CORPORATION LTD Paterson Street HPC|54601| |TMB BANK PUBLIC COMPANY LIMITED, HONG KONG Hong Kong Branch|54061| |WING LUNG BANK LTD Happy Valley Branch|53991| С вопросами о работе с банками, поддерживающими метод Banks of Hong Kong, можно обращаться к курирующему менеджеру Ecommpay. ## Выплаты через Gate {#ru_pm_hk_banks_gate_payout} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate с использованием метода Banks of Hong Kong со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения выплаты выглядит следующим образом. ![](images/pm/ru_hk_banks_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату через Banks of Hong Kong. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе [Формат ответа](ru_gate_interaction_organisation.md). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка выплаты. 8. От сервиса провайдера к платёжной платформе направляется информация о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты. Информация о форматах запросов и оповещений, используемых для проведения выплат методом Banks of Hong Kong через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на выплаты с применением метода Banks of Hong Kong необходимо учитывать следующее: 1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/hk/payout`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма выплаты в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемой выплаты; - `account` — сведения о счёте пользователя: - `bank_id` — идентификатор банка, - `number` — номер счёта, - `customer_name` — имя получателя. 3. Валютой платежа может быть только [HKD](references/ru/currencies/HKD.md) или [CNY](references/ru/currencies/CNY.md). 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на выплату с применением метода Banks of Hong Kong должен содержать идентификатор проекта, базовые сведения о платеже \(его идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, данные счёта и подпись. ```language-json { "general": { "project_id": 383000, "payment_id": "12278b5d662764c9506b4db9df8c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w==" }, "customer": { "id": "fr-2374245", "ip_address": "192.0.2.0" }, "payment": { "amount": 10000, "currency": "HKD" }, "account": { "bank_id": 22791, "number": "1234567890", "customer_name": "John Doe" } } ``` ```language-json { "general": { "project_id": 383000, "payment_id": "12278b5d662764c9506b4db9df8c5c35", "signature": "GINgwlggTvpF9AnkT8rUUVC7bmSCAaQlYc9Mtb3Lv...5vOA7w==" }, "customer": { "id": "fr-2374245", "ip_address": "192.0.2.0" }, "payment": { "amount": 10000, "currency": "HKD" }, "account": { "bank_id": 22791, "number": "1234567890", "customer_name": "John Doe" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат с применением метода Banks of Hong Kong используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `789` для пользователя `customer3` была проведена выплата в размере `100,00 HKD`. ```language-json { "project_id": 789, "payment": { "id": "ABC1234321", "type": "payout", "status": "success", "date": "2021-04-26T08:41:59+0000", "method": "hk", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "account": { "number": "1234567" }, "customer": { "id": "customer3" }, "operation": { "id": 4348000010681, "type": "payout", "status": "success", "date": "2021-04-26T08:41:59+0000", "created_date": "2021-04-26T08:41:54+0000", "request_id": "3d7ef0727decad0829d608cabd0f8a6d96fbd3a...006256", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "0", "message": "Success", "provider": { "id": 5181, "payment_id": "aff0b...cf9f2cd", "auth_code": "", "date": "2021-04-26T08:41:55+0000" } }, "signature": "1L2fmnHY/51dZPI1j/IVa9LqzEPR67j9pPghn...c545R1xsGzw0zQ==" } } ``` В следующем примере оповещение свидетельствует об отклонённой выплате. ```language-json { "project_id": 0123, "payment": { "id": "ABC1234567", "type": "payout", "status": "decline", "date": "2021-04-26T08:41:59+0000", "method": "hk", "sum": { "amount": 10000, "currency": "HKD" }, "description": "" }, "account": { "number": "123456789" }, "customer": { "id": "customer1234" }, "operation": { "id": 4348000010681, "type": "payout", "status": "decline", "date": "2021-04-26T08:41:59+0000", "created_date": "2021-04-26T08:41:54+0000", "request_id": "a19b65b2463fa7377f518d49674275cbaa4397a7...004349", "sum_initial": { "amount": 10000, "currency": "HKD" }, "sum_converted": { "amount": 10000, "currency": "HKD" }, "code": "20000", "message": "General decline", "provider": { "id": 5181, "payment_id": "aff0b...cf9f2cd", "auth_code": "", "date": "2021-04-26T08:41:55+0000" } }, "signature": "eQxj9hXHVWFBDMcko2Tj0071CvnFPsp...A9CchCgVr/Hqbu6w==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с выплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Выплаты](ru_Gate_payout.md)— о том, как проводить выплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Dashboard {#ru_pm_dash_payout} При использовании интерфейса Dashboard можно проводить *одиночные* и *массовые*выплатыметодом Banks of Hong Kong с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры \(включая метод\), отправить запрос и убедиться в проведении выплаты. - Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат. При этомдолжен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры выплат— требованиям, представленным в разделе [Выплаты через Gate](pm_hk_banks.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о проведении выплат через Dashboard представлена в [отдельной статье](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_hk_banks_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Banks of Hong Kong, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Banks of the Philippines {#pm_philippines} статья о работе с платёжным методом Banks of the Philippines, который позволяет проводить платежи в филиппинских песо с использованием банковских счетов в Филиппинах и для которого в платформе Ecommpay поддерживаются оплаты и выплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_philippines_overview} статья о работе с платёжным методом Banks of the Philippines, который позволяет проводить платежи в филиппинских песо с использованием банковских счетов в Филиппинах и для которого в платформе Ecommpay поддерживаются оплаты и выплаты ### Введение {#section_ql3_5fj_stb .section} Banks of the Philippines — метод, позволяющий проводить платежи в филиппинских песо с использованием банковских счетов в Филиппинах. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи выплаты. В этой статье представлена информация о работе с методом Banks of the Philippines: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[PH](references/ru/countries/PH.md)| |Валюты платежей|[PHP](references/ru/currencies/PHP.md)| |Конвертация валют|доступна только для оплат —на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|+| |Опротестования|–| |Особенности|поддержка полных и частичных возвратов осуществляется со стороны провайдера| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/online-banking-philippines/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Banks of the Philippines задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса одного из банков, поддерживающих работу с этим методом. ![](images/pm/ru_banksphilippines_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Banks of the Philippines могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [PHP](references/ru/currencies/PHP.md)|Время¹| |Минимум|Максимум|Базовое|Предельное| |--|---------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|1,00|1 000 000,00|30 минут|1 день| |Полные возвраты|\*|\*|\*|\*| |Частичные возвраты|\*|\*|\*|\*| |Выплаты|10,00|100 000,00|до 10 минут|48 часов| \* Для проведения полных и частичных возвратов пользователям необходимо заполнять [форму обращения](https://www.dragonpay.ph/refund). **Прим.:** 1. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Banks of the Philippines осуществляется с перенаправлением пользователей к сервису Banks of the Philippines, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта. Пользовательский сценарий оплаты через Payment Page \(в базовом варианте, с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису\) выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_2.svg "Выбор метода") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_3.svg "Выбор банка") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_4.svg "Аутентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_5.svg "Подтверждение платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_6.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_philippines_7.svg "Возвращение к веб-сервису") Общие сценарии проведения оплати выплат можно представить следующим образом. ![](images/pm/ru_banksphilippines_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_banksphilippines_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_banks_overview_gate_payout.svg "Выплата через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Banks of the Philippines соответствуют специфике этих возможностей. Вместе с тем, к особенностям работы с методом Banks of the Philippines можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат и выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе [Оплаты через Payment Page](pm_philippines.md)этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, [Поддержка со стороны банков](pm_philippines.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Banks of the Philippines. Каждому банку соответствуют свой идентификатор, который используется при инициировании выплат через Gate, и буквенный код, который используется в оповещениях о результатах выплат для идентификации банка. |Банк|Оплата|Выплата|ID|Код| |----|------|-------|--|---| |AUB Online/Cash Payment|–|+|485|AUB| |Bank of Commerce|+|+|1561|BOC| |BDO Corporate Internet Banking|+|–|2241|BDOC| |BDO Internet Banking|+|+|486|BDO| |BDO Internet Banking \(Bills Payment\)|+|–|2231|BDOP| |BDO Mobile Internet Banking|+|–|2251|BDOM| |BPI ExpressOnline/Mobile \(Fund Transfer\)|+|+|487|BPI| |BPI ExpressOnline/Mobile \(new\)|+|–|2261|BPIA| |BPI ExpressOnline \(Bills Payment\)|+|–|2271|BPIB| |BPI Family Bank|–|+|488|BFB| |Chinabank Online|+|+|489|CBC| |Chinabank Savings|–|+|1531|CBCS| |Chinatrust|–|+|1571|CTBC| |EastWest CA/SA|–|+|490|EWB| |Landbank ATM Online|+|–|2291|LBPA| |Landbank CA/SA|–|+|491|LBP| |Maybank|–|+|1541|MAY| |Maybank Online Banking|+|–|2281|MAYB| |Metrobankdirect|+|+|492|MBTC| |PBCom|–|+|1511|PBCM| |PNB E-Banking|–|+|493|PNB| |PNB e-Banking Bills Payment|+|–|2301|PNBB| |PSBank|–|+|1501|PSB| |RCBC Online Banking|+|+|494|RCBC| |RobinsonsBank Online Bills Payment|+|+|495|RSB| |Security Bank Online Transfer|+|+|496|SBC| |Sterling Bank|–|+|1551|SBA| |UCPB Connect|+|+|498|UCPB| |Unionbank CA/SA, EON|–|+|497|UBP| |Unionbank EON|+|–|2321|UBE| |Unionbank Internet Banking|+|–|2311|UBPB| |Veterans Bank|–|+|1521|PVB| Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечной точкеконечным точкам `/v2/info/banks/philippines/sale/list`\(для оплат\) и `/v2/info/banks/philippines/payout/list` \(для выплат\), которые относятся к группе конечных точек [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) Gate API.В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений. ```language-json { "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 1500, "currency": "PHP" } } ``` ```language-json [ { "id": 2241, // Индентификатор банка "abbr": "BDOC", // Служебная аббревиатура банка, используемая в платформе "name": "BDO Corporate Internet Banking", // Основное (международное) название банка "nativeName": "BDO Corporate Banking", // Локальное (национальное или региональное) название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 1076, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "PHP", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "608", // Цифровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 2 // Число дробных разрядов валюты } ] }, { "id": 1571, "abbr": "CTBC", "name": "Chinatrust", "nativeName": "Chinatrust", "currencies": [ { "id": 1076, "alpha_3_4217": "PHP", "number_3_4217": "608", "exponent": 2 } ] }, { "id": 2241, "abbr": "MAY", "name": "Maybank", "nativeName": "Maybank", "currencies": [ { "id": 1076, "alpha_3_4217": "PHP", "number_3_4217": "608", "exponent": 2 } ] } ] ``` С вопросами о работе с банками, поддерживающими метод Banks of the Philippines, можно обращаться к курирующему менеджеру Ecommpay. ## Оплаты через Payment Page {#ru_pm_philippines_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Banks of the Philippines со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. При этом можно использовать различные варианты выбора метода и банка, указывая соответствующие параметры в запросах.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_banksphilippines_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Banks of the Philippines. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Banks of the Philippines. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис банка. 10. В сервисе банка выполняется обработка запроса на оплату. 11. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису банка. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе банка выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе банка. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Banks of the Philippines, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page \(подробнее [Формат запросов](pm_philippines.md#section_p5j_fgl_ggb)\), при этом допустимы следующие варианты: - 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк \(этот вариант используется по умолчанию\); - 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков; - 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков; - 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков; - 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением. ![](images/universal/pm/splits/ru_asian_banking_pp_1_philippines.svg "1 — Выбор метода и банка") ![](images/universal/pm/splits/ru_asian_banking_pp_2_philippines.svg "2 — Выбор банка среди доступных методов") ![](images/universal/pm/splits/ru_asian_banking_pp_4_philippines.svg "3 — Выбор среди доступных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_5_philippines.svg "4 — Выбор среди заданных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_6_philippines.svg "5 — Перенаправление к сервису заданного банка") Информация о форматах запросов и оповещений, используемых для проведения оплат методом Banks of the Philippines через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Banks of the Philippines необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно рекомендуется указывать адрес электронной почты пользователя в параметре `customer_email`. Также может потребоваться указание имени и фамилии пользователя в параметрах `customer_first_name` и `customer_last_name` соответственно. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Вариант выбора банка может определяться следующим образом: 1. *Через выбор в Payment Page метода и банка \(1\)* — как вариант по умолчанию, применяемый, если не указываются параметр `force_payment_method` и объект `payment_methods_options`, упоминаемые в подпунктах *2–5*. 2. *Через выбор в Payment Page банка среди доступных методов \(2\)* — для этого в объекте `payment_methods_options` необходимо указывать объект `online_philippines_banks`, содержащий параметр `split_banks` со значением `true`: ```language-json "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true}}" ``` 3. *Через выбор в Payment Page банка из числа доступных \(3\)* — для этого в параметре `force_payment_method` необходимо указывать код предварительного выбора метода `online-philippines-banks`. 4. *Через выбор в Payment Page банка из числа заданных \(4\)* — для этого необходимо указывать: - код `online-philippines-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_philippines_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификаторы целевых банков: ```language-json "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261, 2271]}}" ``` 5. *Через подтверждение в Payment Page перенаправления к сервису заданного банка \(5\)* — для этого необходимо указывать: - код `online-philippines-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_philippines_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификатор целевого банка: ```language-json "payment_methods_options": "{\"online_philippines_banks\": {\"split_banks\": true, \"banks_id\": [2261]}}" ``` 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Banks of the Philippines должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "PHP", "customer_id": "customer1", "customer_email": "test@example.com", "customer_first_name": "John", "customer_last_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "PHP", "customer_id": "customer1", "customer_email": "test@example.com", "customer_first_name": "John", "customer_last_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` Вместе с тем, в случае с выбором из заданных банков \(4\), запрос на открытие Payment Page может содержать расширенный набор данных. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "PHP", "customer_id": "customer1", "customer_email": "test@example.com", "customer_first_name": "John", "customer_last_name": "Doe", "force_payment_method": "online-philippines-banks", "payment_methods_options": {"online_philippines_banks": {"split_banks": true, "banks_id": [2261, 2271]}} "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Banks of the Philippines используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `239` была проведена оплата в размере `10,00 PHP`. ```language-json { "project_id": 239, "payment": { "id": "EPfa87-bcfd", "type": "purchase", "status": "success", "date": "2020-03-06T14:11:00+0000", "method": "Philippines banks", "sum": { "amount": 1000, "currency": "PHP" }, "description": "" }, "operation": { "id": 464, "type": "sale", "status": "success", "date": "2020-03-06T14:11:00+0000", "created_date": "2020-03-06T14:10:34+0000", "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001", "sum_initial": { "amount": 1000, "currency": "PHP" }, "sum_converted": { "amount": 1000, "currency": "PHP" }, "code": "0", "message": "Success", "provider": { "id": 1369, "payment_id": "7QKID3P3", "auth_code": "", "endpoint_id": "BOG", "date": "2020-03-06T14:10:54+0000" } }, "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 239, "payment": { "id": "EPfa87-bcfc", "type": "purchase", "status": "decline", "date": "2020-03-07T14:11:00+0000", "method": "Philippines banks", "sum": { "amount": 200000000, "currency": "PHP" }, "description": "" }, "operation": { "id": 465, "type": "sale", "status": "decline", "date": "2020-03-07T14:11:00+0000", "created_date": "2020-03-06T14:10:34+0000", "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002", "sum_initial": { "amount": 200000000, "currency": "PHP" }, "sum_converted": { "amount": 200000000, "currency": "PHP" }, "code": "20101", "message": "Decline due to amount or frequency limit", "provider": { "id": 1369, "payment_id": "7QKID3P3", "auth_code": "", "endpoint_id": "BOG", "date": "2020-03-06T14:10:54+0000" } }, "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob==" } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_philippines_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Banks of the Philippines со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису банка. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_banksphilippines_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Banks of the Philippines. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис банка. 7. В сервисе банка выполняется обработка запроса на оплату. 8. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису банка. 10. Пользователь перенаправляется к сервису банка. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе банка выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Banks of the Philippines через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Banks of the Philippines необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `v2/payment/banks/philippines/sale`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. - `email` — адрес электронной почты пользователя, - `account` — объект, содержащий сведения о банковском счёте пользователя: - `bank_id` — идентификатор банка; - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис мерчанта: - `success` — URL для перенаправления пользователя в случае успешной оплаты. 3. Дополнительно рекомендуется указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя, - `last_name` — фамилия пользователя. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение \(подробнее — в статье [Дополнение информации о платеже](ru_Gate_Clarification.md)\). 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Banks of the Philippines должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, идентификатор банка и URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 580, "payment_id": "test_philippines_sale", "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw==" }, "payment": { "amount": 1000, "currency": "PHP" }, "customer": { "id": "123", "email": "test_customer@example.com", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe" }, "account": { "bank_id": 2681 }, "return_url": { "success": "http://example.com/success" } } ``` ```language-json { "general": { "project_id": 580, "payment_id": "test_philippines_sale", "signature": "pgwRHcfv2OTsdILn33R5Nr/yMx/9FSeIqYHTTd6YhIiLWw==" }, "payment": { "amount": 1000, "currency": "PHP" }, "customer": { "id": "123", "email": "test_customer@example.com", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe" }, "account": { "bank_id": 2681 }, "return_url": { "success": "http://example.com/success" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису банка при проведении каждого платежа с использованием метода Banks of the Philippines необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://test.ph/Pay.aspx?tokenid=3f511c2d&procid=BITC" } ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах оплат с применением метода Banks of the Philippines используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `239` была проведена оплата в размере `10,00 PHP`. ```language-json { "project_id": 239, "payment": { "id": "EPfa87-bcfd", "type": "purchase", "status": "success", "date": "2020-03-06T14:11:00+0000", "method": "Philippines banks", "sum": { "amount": 1000, "currency": "PHP" }, "description": "" }, "operation": { "id": 464, "type": "sale", "status": "success", "date": "2020-03-06T14:11:00+0000", "created_date": "2020-03-06T14:10:34+0000", "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000001", "sum_initial": { "amount": 1000, "currency": "PHP" }, "sum_converted": { "amount": 1000, "currency": "PHP" }, "code": "0", "message": "Success", "provider": { "id": 1369, "payment_id": "7QKID3P3", "auth_code": "", "endpoint_id": "BOG", "date": "2020-03-06T14:10:54+0000" } }, "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGoA==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 239, "payment": { "id": "EPfa87-bcfc", "type": "purchase", "status": "decline", "date": "2020-03-07T14:11:00+0000", "method": "Philippines banks", "sum": { "amount": 200000000, "currency": "PHP" }, "description": "" }, "operation": { "id": 465, "type": "sale", "status": "decline", "date": "2020-03-07T14:11:00+0000", "created_date": "2020-03-06T14:10:34+0000", "request_id": "f6ab99eb0940e43a774b969cb74a88ef08eec6c8951-00000002", "sum_initial": { "amount": 200000000, "currency": "PHP" }, "sum_converted": { "amount": 200000000, "currency": "PHP" }, "code": "20101", "message": "Decline due to amount or frequency limit", "provider": { "id": 1369, "payment_id": "7QKID3P3", "auth_code": "", "endpoint_id": "BOG", "date": "2020-03-06T14:10:54+0000" } }, "signature": "YZKXHr2ZdK3tPqiMzPpSJZ...+WGku5dANQAVWPteHKmwzMQ+mvGob==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с выплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Выплаты](ru_Gate_payout.md)— о том, как проводить выплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Gate {#ru_pm_philippines_gate_payout} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate с использованием метода Banks of the Philippines со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения выплаты выглядит следующим образом. ![](images/pm/ru_banks_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату через Banks of the Philippines. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе [Формат ответа](ru_gate_interaction_organisation.md). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис банка. 7. В сервисе банка выполняется обработка выплаты. 8. От сервиса банка к платёжной платформе направляется информация о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты. Информация о форматах запросов и оповещений, используемых для проведения выплат методом Banks of the Philippines через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на выплату с применением метода Banks of the Philippines необходимо учитывать следующее: 1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/philippines/payout`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма выплаты в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `description` — описание платежа; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `account` — объект, содержащий сведения о банковском счёте пользователя: - `bank_id` — идентификатор банка, - `customer_name` — имя держателя банковского счета, - `number` — номер счёта. 3. Валютой платежа может быть только [PHP](references/ru/currencies/PHP.md). 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на выплату с применением метода Banks of the Philippines должен содержать идентификатор проекта, базовые сведения о платеже \(его идентификатор, сумму и код валюты\), информацию о пользователе и счёте, а также подпись. ```language-json { "general": { "project_id": 445, "payment_id": "1000003", "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA==" }, "customer": { "id": "123", "ip_address": "192.0.2.0" }, "payment": { "amount": 1000, "currency": "PHP", "description": "Payout description" }, "account": { "bank_id": 486, "customer_name": "John Doe", "number": "1670033323" } } ``` ```language-json { "general": { "project_id": 445, "payment_id": "1000003", "signature": "PJkV8ej\/UG0Di8hTng6fBaNIipTv+AWoXW\/9MTO8yJA==" }, "customer": { "id": "123", "ip_address": "192.0.2.0" }, "payment": { "amount": 1000, "currency": "PHP", "description": "Payout description" }, "account": { "bank_id": 486, "customer_name": "John Doe", "number": "1670033323" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат с применением метода Banks of the Philippines используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). К особенностям метода Banks of the Philippines можно отнести то, что название банка, в котором открыт счёт пользователя, указывается в параметре `endpoint_id` объекта `operation.provider` \(информация о банках и соответствующих им буквенных кодах представлена в пункте [Поддержка со стороны банков](pm_philippines.md#section_rqp_zdl_ggb)\). В следующем примере оповещение свидетельствует о том, что в рамках проекта `445` для пользователя `123` была проведена выплата в размере `10,00 PHP` на счёт `1670033323`, открытый в банке `Banco de Oro CA/SA`. ```language-json { "project_id": 445, "payment": { "id": "100011", "type": "payout", "status": "success", "date": "2019-03-18T08:06:13+0000", "method": "Philippines banks", "sum": { "amount": 1000, "currency": "PHP" }, "description": "payout" }, "account": { "number": "1670033323" }, "customer": { "id": "123" }, "operation": { "id": 147, "type": "payout", "status": "success", "date": "2019-03-18T08:06:13+0000", "created_date": "2019-03-18T08:06:06+0000", "request_id": "9499286583e3d1102f752a9cd47d2fb7469cc613e11", "sum_initial": { "amount": 1000, "currency": "PHP" }, "sum_converted": { "amount": 1000, "currency": "PHP" }, "provider": { "id": 1346, "payment_id": "6Q2G5D83", "date": "2019-03-18T08:06:11+0000", "auth_code": "", "endpoint_id": "BDO" }, "code": "0", "message": "Success" }, "signature": "oFGfjOtZZkFxi7Pd1yikCw01b0BsedgKr8z/E8qfizh1A==" } ``` В следующем примере оповещение свидетельствует об отклонённой выплате. ```language-json { "project_id": 445, "payment": { "id": "100014", "type": "payout", "status": "decline", "date": "2019-03-18T10:49:50+0000", "method": "Philippines banks", "sum": { "amount": 900, "currency": "PHP" }, "description": "payout" }, "account": { "number": "1670033323" }, "customer": { "id": "123" }, "operation": { "id": 148, "type": "payout", "status": "decline", "date": "2019-03-18T10:49:51+0000", "created_date": "2019-03-18T10:49:46+0000", "request_id": "d626cece0855a8863f687985e6c57935d9872183c", "sum_initial": { "amount": 900, "currency": "PHP" }, "sum_converted": { "amount": 900, "currency": "PHP" }, "provider": { "id": 1346, "payment_id": "YDK0QS4X", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "fz0Yu5BFLRLJez747kDfZHgmKGIOgMa5DAzPE/4GLWlZSzCwkdkqyrTqUQvLp6A==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Выплаты через Dashboard {#ru_pm_dash_payout} При использовании интерфейса Dashboard можно проводить *одиночные* и *массовые*выплатыметодом Banks of the Philippines с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры \(включая метод\), отправить запрос и убедиться в проведении выплаты. - Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат. При этомдолжен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры выплат— требованиям, представленным в разделе [Выплаты через Gate](pm_philippines.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о проведении выплат через Dashboard представлена в [отдельной статье](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_philippines_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Banks of the Philippines, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Blik {#pm_blik} статья о работе с платёжным методом Blik, который позволяет проводить платежи в злотых с банковских счетов в Польше и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_blik_overview} статья о работе с платёжным методом Blik, который позволяет проводить платежи в злотых с банковских счетов в Польше и для которого в платформе Ecommpay поддерживаются оплаты и возвраты ### Введение {#section_y4j_lny_qvb .section} Blik — метод, позволяющий проводить платежи в злотых с банковских счетов в Польше. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом Blik: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[PL](references/ru/countries/PL.md)| |Валюты платежей|[PLN](references/ru/currencies/PLN.md)| |Конвертация валют|–| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|открытие формы оплаты в сервисе Blik недоступно в объекте iframe| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/blik/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Blik задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса Blik. ![](images/pm/ru_blik_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операцийс использованием метода Blik могут применяться различные интерфейсы платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard\(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для всех операций характерныследующие свойства и ограничения. ||Суммы, [PLN](references/ru/currencies/PLN.md)¹|Время²| |минимум|максимум|базовое|предельное| |--|----------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|0,01|10 000,00\*|\*|\*| |Возвраты|–|–|–|–| **Прим.:** 1. Ограничения сумм и время проведения платежей зависят от банков. 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Blik выполняется с перенаправлением пользователей к сервису Blik, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_blik_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_blik_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_blik_interfaces_gate_refund.svg "Возврат через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Blik соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_blik_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Blik со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_blik_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Blik. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Blik. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис Blik. 10. В сервисе Blik выполняется обработка запроса на оплату. 11. От сервиса Blik к платёжной платформе передаются данные для перенаправления пользователя к сервису Blik. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису Blik. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе Blik выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе Blik. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса Blik к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Blik через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Blik необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно рекомендуется указывать следующие параметры: - `customer_first_name` — имя пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `customer_last_name` — фамилия пользователя в рамках проекта \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\), - `customer_email` — адрес электронной почты. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Валютой платежа может быть только [PLN](references/ru/currencies/PLN.md). 4. Для предварительного выбора метода Blik необходимо указывать код этого метода в параметре `force_payment_method` — `blik`. 5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 6. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Blik должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "PLN", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Johnson", "customer_email": "customer@example.com', "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ``` {#codeblock_rqr_3px_jgc .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "PLN", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Johnson", "customer_email": "customer@example.com', "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Blik используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `423` была проведена оплата в размере `1,00 PLN`. ```language-json { "project_id": 423, "payment": { "id": "03315", "type": "purchase", "status": "success", "date": "2022-05-12T14:32:59+0000", "method": "blik", "sum": { "amount": 100, "currency": "PLN" }, "description": "PAYMENT_03315" }, "customer": { "id": "11" }, "operation": { "id": 50241, "type": "sale", "status": "success", "date": "2022-05-09T09:32:10+0000", "created_date": "2022-05-09T09:20:09+0000", "request_id": "6db6ed63860b74b33b0c870-00010993", "sum_initial": { "amount": 100, "currency": "PLN" }, "sum_converted": { "amount": 100, "currency": "PLN" }, "code": "0", "message": "Success", "provider": { "id": 151, "payment_id": "8464654", "auth_code": "" } }, "signature": "5xpLaag4iVH4p5poiI25KSUQWESwbg/gVj4fWfTzVBg==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 423, "payment": { "id": "3614", "type": "purchase", "status": "decline", "date": "2022-05-16T08:16:29+0000", "method": "blik", "sum": { "amount": 100, "currency": "PLN" }, "description": "PAYMENT_3614" }, "customer": { "id": "11" }, "operation": { "id": 73761, "type": "sale", "status": "decline", "date": "2022-05-16T08:16:29+0000", "created_date": "2022-05-16T08:06:20+0000", "request_id": "b4aa45de7042c95b992e9a5ab874bfbcf-00051169", "sum_initial": { "amount": 100, "currency": "PLN" }, "sum_converted": { "amount": 100, "currency": "PLN" }, "code": "20000", "message": "General decline", "provider": { "id": 151, "payment_id": "600325", "auth_code": "" } }, "signature": "wn7dHQhfgluzGfw1EJGZ5tHfS8oTW1EsxEhvJW6Tiw==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_blik_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Blik со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису Blik. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_blik_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Blik. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Blik. 7. В сервисе Blik выполняется обработка запроса на оплату. 8. От сервиса Blik к платёжной платформе передаются данные для перенаправления пользователя к сервису Blik. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису Blik. 10. Пользователь перенаправляется к сервису Blik. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе Blik выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса Blik к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Blik через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Blik необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/blik/sale](https://api-developers.ecommpay.com/api-specification/blik/post-v2-payment-blik-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор, уникальный в рамках проекта; - `ip_address` — IP-адрес, актуальный для инициируемого платежа. 3. Дополнительно рекомендуется указывать фамилию и адрес электронной почты пользователя. - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `last_name` — фамилия \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `email` — адрес электронной почты. Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение \(подробнее — в статье [Дополнение информации о платеже](ru_Gate_Clarification.md)\). 4. Дополнительно можно передавать URL для перенаправления пользователя в веб-сервис. - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для возврата пользователя в веб-сервис мерчанта во время или после оплаты. 5. Валютой платежа может быть только [PLN](references/ru/currencies/PLN.md). 6. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Blik должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ``` {#codeblock_lnc_j4x_jgc .language-json} { "general": { "project_id": 423, "payment_id": "5554", "signature": "PJkV8ej\/UG0Di8LwYipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 100, "currency": "PLN" }, "customer": { "id": "123", "ip_address": "192.0.2.0", "email": "customer@example.com", "first_name": "John", "last_name": "Johnson" } } ``` ``` {#codeblock_sxd_kpx_jgc .language-json} { "general": { "project_id": 423, "payment_id": "5554", "signature": "PJkV8ej\/UG0Di8LwYipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 100, "currency": "PLN" }, "customer": { "id": "123", "ip_address": "192.0.2.0", "email": "customer@example.com", "first_name": "John", "last_name": "Johnson" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису Blik при проведении каждого платежа с использованием метода Blik необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для итоговых оповещений об оплатах с применением метода Blik используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `423` была проведена оплата в размере `1,00 PLN`. ```language-json { "project_id": 423, "payment": { "id": "03315", "type": "purchase", "status": "success", "date": "2022-05-12T14:32:59+0000", "method": "blik", "sum": { "amount": 100, "currency": "PLN" }, "description": "PAYMENT_03315" }, "customer": { "id": "11" }, "operation": { "id": 50241, "type": "sale", "status": "success", "date": "2022-05-09T09:32:10+0000", "created_date": "2022-05-09T09:20:09+0000", "request_id": "6db6ed63860b74b33b0c870-00010993", "sum_initial": { "amount": 100, "currency": "PLN" }, "sum_converted": { "amount": 100, "currency": "PLN" }, "code": "0", "message": "Success", "provider": { "id": 151, "payment_id": "8464654", "auth_code": "" } }, "signature": "5xpLaag4iVH4p5poiI25KSUQ/gVj4fWfTzVBg==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 423, "payment": { "id": "3614", "type": "purchase", "status": "decline", "date": "2022-05-16T08:16:29+0000", "method": "blik", "sum": { "amount": 100, "currency": "PLN" }, "description": "PAYMENT_3614" }, "customer": { "id": "11" }, "operation": { "id": 73761, "type": "sale", "status": "decline", "date": "2022-05-16T08:16:29+0000", "created_date": "2022-05-16T08:06:20+0000", "request_id": "b4aa45de7042c95b992e9a5ab874bfbcf-00051169", "sum_initial": { "amount": 100, "currency": "PLN" }, "sum_converted": { "amount": 100, "currency": "PLN" }, "code": "20000", "message": "General decline", "provider": { "id": 151, "payment_id": "600325", "auth_code": "" } }, "signature": "wn7dHQhfVYLPZuVx8r0ggluzGf8oTW1EsxEhvJW6Tiw==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о том, как создавать и проверять подписи в запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_blik_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Blik со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_blik_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Blik. 7. В сервисе Blik выполняется обработка возврата. 8. От сервиса Blik к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Blik через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода Blik необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/blik/refund](https://api-developers.ecommpay.com/api-specification/blik/post-v2-payment-blik-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\). 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Blik должен содержать идентификаторы проекта и платежа, описание возврата, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json "general": { "project_id": 430, "payment_id": "refund_02", "signature": "4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" }, "payment": { "amount": 100, "currency": "PLN", "description": "refund" } ``` ```language-json "general": { "project_id": 430, "payment_id": "refund_02", "signature": "4XL1QFaDH3p9Mh0CIcjmOwSwKJ7KLTZYO56lCv+f1M0Sf/7eg==" }, "payment": { "amount": 100, "currency": "PLN", "description": "refund" } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возвратов с применением метода Blik используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `171` для пользователя `user_33` был выполнен возврат в размере `50,00 PLN`. ```language-json { "project_id": 171, "payment": { "id": "PAYMENT_6315", "type": "purchase", "status": "refunded", "date": "2022-05-12T14:32:59+0000", "method": "blik", "sum": { "amount": 0, "currency": "PLN" }, "description": "REFUND_FOR_PAYMENT_6315" }, "customer": { "id": "user_33" }, "operation": { "id": 10992010050461, "type": "refund", "status": "success", "date": "2022-05-12T14:32:59+0000", "created_date": "2022-05-12T14:32:56+0000", "request_id": "1d970130f663c4639a2058a6b4727c9b710ddb3-00010993", "sum_initial": { "amount": 5000, "currency": "PLN" }, "sum_converted": { "amount": 5000, "currency": "PLN" }, "code": "0", "message": "Success", "provider": { "id": 151, "payment_id": "151983", "auth_code": "" } }, "signature": "TueTURmjrc9Vw2b1LtOG1NCCRA+UO0ov3wWc6ueXYUSTdxaZHj0w==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о том, как создавать и проверять подписи в запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Dashboard {#ru_pm_dash_refund} При использовании интерфейса Dashboard можно выполнять возвратыметодом Blik с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата. - Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов. При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры возвратов — требованиям, представленным в разделе [Возвраты через Gate](pm_blik.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о выполнении возвратов через Dashboard представлена в [отдельном разделе](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_blik_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Blik, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Brazil Online Banking {#pm_brazil_ob} статья о работе с платёжным методом Brazil Online Banking, который позволяет проводить платежи в бразильских реалах и долларах США с использованием банковских счетов в Бразилии и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_brazil_ob_overview} статья о работе с платёжным методом Brazil Online Banking, который позволяет проводить платежи в бразильских реалах и долларах США с использованием банковских счетов в Бразилии и для которого в платформе Ecommpay поддерживаются оплаты и возвраты ### Введение {#section_ql3_5fj_stb .section} Brazil Online Banking — метод, позволяющий проводить платежи в бразильских реалах и долларах США с использованием банковских счетов в Бразилии. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом Brazil Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[BR](references/ru/countries/BR.md)| |Валюты платежей|[BRL](references/ru/currencies/BRL.md), [USD](references/ru/currencies/USD.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|проведение полного и частичного возврата возможно в течение 90 календарных дней после проведения оплаты| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Brazil Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_brazil_ob_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Brazil Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы¹|Время²| |минимум|максимум|базовое|предельное| |--|------|------| |-------|--------|-------|----------| |Оплаты|\*|\*|3 минуты|36 часов| |Возвраты|\*|\*|5 минут|36 часов| **Прим.:** 1. Минимальные и максимальные суммы платежа зависят от банков, доступных для выбора пользователю после перенаправления к сервису провайдера. Если сумма платежа не соответствует ограничениям банка, его выбор недоступен. 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Brazil Online Banking осуществляется с перенаправлением пользователей к сервису провайдера, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_brazil_ob_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_brazil_ob_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_pm_brazil_ob_interfaces_gate_refund.svg "Возврат через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Brazil Online Banking соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_brazil_ob_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Brazil Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_brazil_ob_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Brazil Online Banking. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Brazil Online Banking. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 15. В сервисе провайдера выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе провайдера. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Brazil Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Brazil Online Banking необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно необходимо указывать следующие параметры: - `customer_first_name` — имя пользователя; - `customer_last_name` — фамилия пользователя; - `customer_email` — адрес электронной почты пользователя; - `identify_doc_number` — *уникальный идентификатор налогоплательщика* \(Cadastro de Pessoas Físicas, CPF\), состоит из 11 цифр, должен указываться без маскирования, пробелов и иных разделительных символов. Для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов в значениях параметров `customer_first_name` и `customer_last_name`. 3. Для предварительного выбора метода Brazil Online Banking необходимо указывать код этого метода в параметре `force_payment_method` — `online-brazil-banks`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Brazil Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_gdb_pts_w2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "identify_doc_number": "12345678901", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ``` {#codeblock_hzt_vsw_x2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "identify_doc_number": "12345678901", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Brazil Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "brazil", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "brazil", "sum": { "amount": 1000, "currency": "USD" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181" }, "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_brazil_ob_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Brazil Online Banking со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису провайдера. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_brazil_ob_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Brazil Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его оправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера. 11. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 12. В сервисе провайдера выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Brazil Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Brazil Online Banking необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/brazil/sale`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. 3. Дополнительно необходимо указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `last_name` — фамилия пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `email` — адрес электронной почты пользователя. - `identify` — объект, содержащий сведения о документе, подтверждающем личность пользователя: - `doc_number` — уникальный идентификатор налогоплательщика \(Cadastro de Pessoas Físicas, CPF\), состоит из 11 цифр, должен указываться без маскирования, пробелов и иных разделительных символов. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Brazil Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_wwl_c5s_w2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com", "identify": { "doc_number": "12345678901" } } } ``` ``` {#codeblock_kqf_rgl_33c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com", "identify": { "doc_number": "12345678901" } } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису провайдера при проведении каждого платежа с использованием метода Brazil Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ``` {#codeblock_t1c_gx1_1fc .language-json} "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для итоговых оповещений об оплатах с применением метода Brazil Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "brazil", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-3c6a0ba271207cb817a0c683cf36e7a33ff2d9b4-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lfth8yxvoqn15Q0dM2S+iD5RNQvCeMsG/PmpHnKhIw+5XaZ+Fsd6z/xfTIf6Kl+WjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "brazil", "sum": { "amount": 1000, "currency": "USD" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8b07d9f0442268d404145e6153584-197b9b48dcbf85651b13318f699befb1e501a90a-05031181" }, "signature": "XvIAwMNq/nDzn28ZwuIN8QmuR57NqP2r8RD1ZYsCusvS4jF7XJd7YX9D0LQSly5kKquIdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_brazil_ob_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Brazil Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_pm_brazil_ob_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка возврата. 8. От сервиса провайдера к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Brazil Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода Brazil Online Banking необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Brazil Online Banking должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя и подпись, а также, при необходимости, код валюты и сумму возврата. ``` {#codeblock_fqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 10000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ``` {#codeblock_gqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 10000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возвратов с применением метода Brazil Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `433772` для пользователя `1` был выполнен полный возврат в размере `100,00 USD`. ``` {#codeblock_pmy_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "TEST_PAYMENT_265608", "type": "purchase", "status": "refunded", "date": "2025-06-26T06:48:37+0000", "method": "brazil", "sum": { "amount": 0, "currency": "USD" }, "description": "TEST_PAYMENT_265608" }, "customer": { "id": "1" }, "operation": { "id": 7373000014760, "type": "refund", "status": "success", "date": "2025-06-26T06:48:37+0000", "created_date": "2025-06-26T06:48:34+0000", "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 1903, "payment_id": "1750920516487", "auth_code": "" } }, "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ``` {#codeblock_iqj_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "test_29.04.25_3", "type": "purchase", "status": "partially refunded", "date": "2024-12-29T11:36:34+0000", "method": "brazil", "sum": { "amount": 90000, "currency": "BRL" }, "description": "test_29.04.25_3" }, "customer": { "id": "1" }, "operation": { "id": 5557000012956, "type": "refund", "status": "decline", "date": "2024-12-29T11:22:44+0000", "created_date": "2024-12-29T11:22:44+0000", "request_id": "c717b3de84d1ba574598a637f856a-00002267", "sum_initial": { "amount": 50000, "currency": "BRL" }, "sum_converted": { "amount": 8994, "currency": "USD" }, "code": "3283", "message": "Refund amount more than init amount", "provider": { "id": 21514, "payment_id": "1418092457", "auth_code": "" } }, "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Dashboard {#ru_pm_dash_refund} При использовании интерфейса Dashboard можно выполнять возвратыметодом Brazil Online Banking с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата. - Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов. При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры возвратов — требованиям, представленным в разделе [Возвраты через Gate](pm_brazil_ob.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о выполнении возвратов через Dashboard представлена в [отдельном разделе](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_brazil_ob_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Brazil Online Banking, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Buy Now Pay Later {#pm_bnpl} статья о работе с платёжным методом Buy Now Pay Later, который позволяет проводить платежи в фунтах стерлингов с использованием рассрочки в Великобритании и для которого в платформе Ecommpay поддерживаются оплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_bnpl_overview} статья о работе с платёжным методом Buy Now Pay Later, который позволяет проводить платежи в фунтах стерлингов с использованием рассрочки в Великобритании и для которого в платформе Ecommpay поддерживаются оплаты ### Введение {#section_ql3_5fj_stb .section} Buy Now Pay Later — метод, позволяющий проводить платежи в фунтах стерлингов с использованием рассрочки в Великобритании. Условия рассрочки определяются в результате взаимодействия пользователя и провайдера. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты. В этой статье представлена информация о работе с методом Buy Now Pay Later: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|[GB](references/ru/countries/GB.md)| |Валюты платежей|[GBP](references/ru/currencies/GBP.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|- возвраты выполняются только через заявки в сервисе провайдера, при этом рассмотрение отдельной заявки занимает не более одного рабочего дня, но все заявки обрабатываются последовательно и каждая очередная заявка принимается только после обработки предыдущей - при перенаправлении к сервису провайдера не может использоваться вариант с применением элемента iframe; страница этого сервиса может открываться в отдельной вкладке или в модальном окне | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Buy Now Pay Later задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_bnpl_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Buy Now Pay Later могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, GBP|Время¹| |минимум|максимум|базовое|предельное| |--|----------|------| |-------|--------|-------|----------| |Оплаты|1,00|30 000,00|5 минут|24 часа| **Прим.:** 1. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Buy Now Pay Later осуществляется перенаправлением пользователей к сервису провайдера. ![](images/pm/ru_bnpl_interfaces_gate.svg "Оплата через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Buy Now Pay Later соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_bnpl_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Buy Now Pay Later со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Buy Now Pay Later. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Buy Now Pay Later. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для регистрации договора на рассрочку и оплаты. 15. В сервисе провайдера выполняется обработка информации. 16. Информация о результате отображается пользователю в сервисе провайдера. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Buy Now Pay Later через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Buy Now Pay Later необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма оплаты в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Должны указываться имя и фамилия пользователя в параметрах `customer_first_name` и `customer_last_name`. 3. Для предварительного выбора метода Buy Now Pay Later необходимо указывать код этого метода в параметре `force_payment_method` — `bnpl-humm`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Buy Now Pay Later должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, а также подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 3000, "payment_currency": "GBP", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 3000, "payment_currency": "GBP", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Buy Now Pay Later используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом в параметре `type` объекта `payment` может указываться значение `bnpl`. В следующем примере оповещение свидетельствует о том, что в рамках проекта `59051` была проведена оплата на `10,00 GBP`. ```language-json { "customer": { "id": "zxc", "phone": "07811123331" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_600055", "type": "bnpl", "status": "success", "date": "2024-11-14T11:20:31+0000", "method": "bnpl", "sum": { "amount": 1000, "currency": "GBP" }, "description": "TEST_PAYMENT_600055" }, "operation": { "sum_initial": { "amount": 1000, "currency": "GBP" }, "sum_converted": { "amount": 1000, "currency": "GBP" }, "code": "0", "message": "Success", "provider": { "id": 16891, "payment_id": "Twp7saulXXF05mzi", "auth_code": "" }, "id": 29741010169841, "type": "sale", "status": "success", "date": "2024-11-14T11:20:31+0000", "created_date": "2024-11-14T11:08:10+0000", "request_id": "497a5edb8ba907ae27d12f508c3d2ba096-00029742" }, "signature": "XV7CVXtQv7n53zvg3jlt1ThyVdedpUKg3UX/9i6jWLPiA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "customer": { "id": "zxc" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_577285", "type": "bnpl", "status": "decline", "date": "2024-11-14T11:49:55+0000", "method": "bnpl", "sum": { "amount": 1000, "currency": "GBP" }, "description": "TEST_PAYMENT_577285" }, "operation": { "sum_initial": { "amount": 1000, "currency": "GBP" }, "sum_converted": { "amount": 1000, "currency": "GBP" }, "code": "20000", "message": "General decline", "provider": { "id": 16891, "payment_id": "xAIr1FeVlr1QGo4h", "auth_code": "" }, "id": 35876010169968, "type": "sale", "status": "decline", "date": "2024-11-14T11:49:55+0000", "created_date": "2024-11-14T11:39:57+0000", "request_id": "f5313e75fade8bb5076a05692a9c82-00035877" }, "signature": "C3I7F8GCUMf/7MJjQszBerLdVWYncTyi+ZAD9uKDQDg==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_bnpl_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Buy Now Pay Later со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису провайдера. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Buy Now Pay Later. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера. 11. Пользователь выполняет необходимые действия для регистрации договора на рассрочку и оплаты. 12. В сервисе провайдера выполняется обработка информации. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Buy Now Pay Later через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Buy Now Pay Later необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/bnpl/humm/sale](https://api-developers.ecommpay.com/api-specification/bancontact/post-v2-payment-bnpl-humm-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты;; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `first_name` — имя пользователя; - `last_name` — фамилия пользователя. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Buy Now Pay Later должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, а также подпись. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej/UG0Di8hTng6JvipTv+AWoXW/9MTO8yJA==" }, "payment": { "amount": 30000, "currency": "GBP" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej/UG0Di8hTng6JvipTv+AWoXW/9MTO8yJA==" }, "payment": { "amount": 30000, "currency": "GBP" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe" } } ``` ### Формат оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису провайдера при проведении каждого платежа с использованием метода Buy Now Pay Later необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "POST", "url": "https://www.example.com/pay" } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений с применением метода Buy Now Pay Later используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). При этом в параметре `type` объекта `payment` может указываться значение `bnpl`. В следующем примере оповещение свидетельствует о том, что в рамках проекта `59051` была проведена оплата на `10,00 GBP`. ``` {#codeblock_jbq_jnd_f2c .language-json} { "customer": { "id": "zxc", "phone": "07811123331" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_600055", "type": "bnpl", "status": "success", "date": "2024-11-14T11:20:31+0000", "method": "bnpl", "sum": { "amount": 1000, "currency": "GBP" }, "description": "TEST_PAYMENT_600055" }, "operation": { "sum_initial": { "amount": 1000, "currency": "GBP" }, "sum_converted": { "amount": 1000, "currency": "GBP" }, "code": "0", "message": "Success", "provider": { "id": 16891, "payment_id": "Twp7saulXXF05mzi", "auth_code": "" }, "id": 29741010169841, "type": "sale", "status": "success", "date": "2024-11-14T11:20:31+0000", "created_date": "2024-11-14T11:08:10+0000", "request_id": "497a5edb8ba907ae27d12f508c3d2ba096-00029742" }, "signature": "XV7CVXtQv7n53zvg3jlt1ThyVdedpUKg3UX/9i6jWLPiA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_kbq_jnd_f2c .language-json} { "customer": { "id": "zxc" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_577285", "type": "bnpl", "status": "decline", "date": "2024-11-14T11:49:55+0000", "method": "bnpl", "sum": { "amount": 1000, "currency": "GBP" }, "description": "TEST_PAYMENT_577285" }, "operation": { "sum_initial": { "amount": 1000, "currency": "GBP" }, "sum_converted": { "amount": 1000, "currency": "GBP" }, "code": "20000", "message": "General decline", "provider": { "id": 16891, "payment_id": "xAIr1FeVlr1QGo4h", "auth_code": "" }, "id": 35876010169968, "type": "sale", "status": "decline", "date": "2024-11-14T11:49:55+0000", "created_date": "2024-11-14T11:39:57+0000", "request_id": "f5313e75fade8bb5076a05692a9c82-00035877" }, "signature": "C3I7F8GCUMf/7MJjQszBerLdVWYncTyi+ZAD9uKDQDg==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_bnpl_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Buy Now Pay Later, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Chile Online Banking {#pm_chile_ob} статья о работе с платёжным методом Chile Online Banking, который позволяет проводить платежи в долларах США и чилийских песо с использованием банковских счетов в Чили и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_chile_ob_overview} статья о работе с платёжным методом Chile Online Banking, который позволяет проводить платежи в долларах США и чилийских песо с использованием банковских счетов в Чили и для которого в платформе Ecommpay поддерживаются оплаты и возвраты ### Введение {#section_ql3_5fj_stb .section} Chile Online Banking — метод, позволяющий проводить платежи в долларах США и чилийских песо с использованием банковских счетов в Чили. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и возвраты. В этой статье представлена информация о работе с методом Chile Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[CL](references/ru/countries/CL.md)| |Валюты платежей|[CLP](references/ru/currencies/CLP.md), [USD](references/ru/currencies/USD.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|- поскольку [CLP](references/ru/currencies/CLP.md) не имеет дробных разрядов, суммы в этой валюте идентичны в целых и дробных единицах - проведение полного и частичного возврата возможно в течение 90 календарных дней после проведения оплаты | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Chile Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_chile_ob_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Chile Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы¹|Время²| |минимум|максимум|базовое|предельное| |--|------|------| |-------|--------|-------|----------| |Оплаты|\*|\*|3 минуты|36 часов| |Возвраты|\*|\*|5 минут|36 часов| **Прим.:** 1. Минимальные и максимальные суммы платежа зависят от банков, доступных для выбора пользователю после перенаправления к сервису провайдера. Если сумма платежа не соответствует ограничениям банка, его выбор недоступен. 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Chile Online Banking осуществляется с перенаправлением пользователей к сервису провайдера, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_chile_ob_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_chile_ob_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_pm_chile_ob_interfaces_gate_refund.svg "Возврат через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Chile Online Banking соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_chile_ob_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Chile Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chile_ob_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Chile Online Banking. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Chile Online Banking. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 15. В сервисе провайдера выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе провайдера. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Chile Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Chile Online Banking необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты \(для [CLP](references/ru/currencies/CLP.md) эта сумма соответствует сумме в целых единицах валюты\); - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно необходимо указывать имя, фамилию и адрес электронной почты пользователя в параметрах `customer_first_name`, `customer_last_name` и `customer_email`. Для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов в значениях параметров `customer_first_name` и `customer_last_name`. 3. Для предварительного выбора метода Chile Online Banking необходимо указывать код этого метода в параметре `force_payment_method` — `online-chile-banks`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Chile Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_gdb_pts_w2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ``` {#codeblock_hzt_vsw_x2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Chile Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "chile", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c68b-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lfthWjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "chile", "sum": { "amount": 1000, "currency": "EUR" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8b07d9f1e501a90a-05031181" }, "signature": "XvIAwMNq/nDzn28ZsvS4jdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_chile_ob_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Chile Online Banking со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису провайдера. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chile_ob_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Chile Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его оправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера. 11. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 12. В сервисе провайдера выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Chile Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Chile Online Banking необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/chile/sale`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты \(для [CLP](references/ru/currencies/CLP.md) эта сумма соответствует сумме в целых единицах валюты\); - `currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. 3. Дополнительно необходимо указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `last_name` — фамилия пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `email` — адрес электронной почты пользователя. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Chile Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_wwl_c5s_w2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com" } } ``` ``` {#codeblock_fp4_1tw_x2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису провайдера при проведении каждого платежа с использованием метода Chile Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ``` {#codeblock_t1c_gx1_1fc .language-json} "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для итоговых оповещений об оплатах с применением метода Chile Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "chile", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c68b-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lfthWjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "chile", "sum": { "amount": 1000, "currency": "EUR" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8b07d9f1e501a90a-05031181" }, "signature": "XvIAwMNq/nDzn28ZsvS4jdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_chile_ob_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Chile Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_pm_chile_ob_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка возврата. 8. От сервиса провайдера к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Chile Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода Chile Online Banking необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате, для [CLP](references/ru/currencies/CLP.md) эта сумма соответствует сумме в целых единицах валюты\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Chile Online Banking должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя и подпись, а также, при необходимости, код валюты и сумму возврата. ``` {#codeblock_fqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 10000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ``` {#codeblock_gqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 10000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возвратов с применением метода Chile Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `433772` для пользователя `1` был выполнен полный возврат в размере `100,00 USD`. ``` {#codeblock_pmy_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "TEST_PAYMENT_265608", "type": "purchase", "status": "refunded", "date": "2025-06-26T06:48:37+0000", "method": "chile", "sum": { "amount": 0, "currency": "USD" }, "description": "TEST_PAYMENT_265608" }, "customer": { "id": "1" }, "operation": { "id": 7373000014760, "type": "refund", "status": "success", "date": "2025-06-26T06:48:37+0000", "created_date": "2025-06-26T06:48:34+0000", "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 1903, "payment_id": "1750920516487", "auth_code": "" } }, "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ``` {#codeblock_iqj_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "test_29.04.25_3", "type": "purchase", "status": "partially refunded", "date": "2024-12-29T11:36:34+0000", "method": "chile", "sum": { "amount": 200000, "currency": "CLP" }, "description": "test_29.04.25_3" }, "customer": { "id": "1" }, "operation": { "id": 5557000012956, "type": "refund", "status": "decline", "date": "2024-12-29T11:22:44+0000", "created_date": "2024-12-29T11:22:44+0000", "request_id": "c717b3de84d1ba574598a637f856a-00002267", "sum_initial": { "amount": 100000, "currency": "CLP" }, "sum_converted": { "amount": 106, "currency": "USD" }, "code": "3283", "message": "Refund amount more than init amount", "provider": { "id": 21514, "payment_id": "1418092457", "auth_code": "" } }, "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Dashboard {#ru_pm_dash_refund} При использовании интерфейса Dashboard можно выполнять возвратыметодом Chile Online Banking с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата. - Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов. При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры возвратов — требованиям, представленным в разделе [Возвраты через Gate](pm_chile_ob.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о выполнении возвратов через Dashboard представлена в [отдельном разделе](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_chile_ob_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Chile Online Banking, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # China UnionPay {#pm_unionpay} статья о работе с платёжным методом China UnionPay, который позволяет проводить платежи в разных валютах с использованием платёжных карт в разных странах и для которого в платформе Ecommpay поддерживаются оплаты и возврат **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_unionpay_overview} статья о работе с платёжным методом China UnionPay, который позволяет проводить платежи в разных валютах с использованием платёжных карт в разных странах и для которого в платформе Ecommpay поддерживаются оплаты и возврат ### Введение {#section_ql3_5fj_stb .section} China UnionPay — метод, позволяющий проводить платежи в разных валютах с использованием платёжных карт в разных странах. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом China UnionPay: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|платёжные карты| |Регионы использования|[AE](references/ru/countries/AE.md), [AG](references/ru/countries/AG.md), [AT](references/ru/countries/AT.md), [AU](references/ru/countries/AU.md), [AZ](references/ru/countries/AZ.md), [BD](references/ru/countries/BD.md), [BE](references/ru/countries/BE.md), [BN](references/ru/countries/BN.md), [BY](references/ru/countries/BY.md), [CA](references/ru/countries/CA.md), [CN](references/ru/countries/CN.md), [DE](references/ru/countries/DE.md), [ES](references/ru/countries/ES.md), [FI](references/ru/countries/FI.md), [FR](references/ru/countries/FR.md), [GB](references/ru/countries/GB.md), [GE](references/ru/countries/GE.md), [HK](references/ru/countries/HK.md), [HU](references/ru/countries/HU.md), [ID](references/ru/countries/ID.md), [IE](references/ru/countries/IE.md), [IT](references/ru/countries/IT.md), [JP](references/ru/countries/JP.md), [KE](references/ru/countries/KE.md), [KG](references/ru/countries/KG.md), [KH](references/ru/countries/KH.md), [KR](references/ru/countries/KR.md), [KZ](references/ru/countries/KZ.md), [LB](references/ru/countries/LB.md), [LI](references/ru/countries/LI.md), [LK](references/ru/countries/LK.md), [LT](references/ru/countries/LT.md), [LU](references/ru/countries/LU.md), [MG](references/ru/countries/MG.md), [MN](references/ru/countries/MN.md), [MO](references/ru/countries/MO.md), [MT](references/ru/countries/MT.md), [MU](references/ru/countries/MU.md), [MX](references/ru/countries/MX.md), [MY](references/ru/countries/MY.md), [NL](references/ru/countries/NL.md), [NP](references/ru/countries/NP.md), [NZ](references/ru/countries/NZ.md), [PA](references/ru/countries/PA.md), [PF](references/ru/countries/PF.md), [PH](references/ru/countries/PH.md), [PT](references/ru/countries/PT.md), [SC](references/ru/countries/SC.md), [SG](references/ru/countries/SG.md), [SI](references/ru/countries/SI.md), [SK](references/ru/countries/SK.md), [SR](references/ru/countries/SR.md), [TH](references/ru/countries/TH.md), [TJ](references/ru/countries/TJ.md), [TZ](references/ru/countries/TZ.md), [US](references/ru/countries/US.md), [VN](references/ru/countries/VN.md) \*| |Валюты платежей|[AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md) \*| |Конвертация валют|–| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|+| |Особенности|при работе с опротестованиями по операциям, которые были выполнены методом China UnionPay, важно учитывать следующие особенности:- порядок работы по таким опротестованиям может отличаться от порядка для классических карточных платежей, описанного в настоящей документации - для таких опротестований не поддерживаются возможности работы через интерфейс Dashboard - при оформлении таких опротестований специалисты Ecommpay сообщают об этом специалистам мерчанта, предоставляют информацию о порядке последующей работы и консультируют по возникающим вопросам - с общими вопросами о порядке работы по таким опротестованиям можно обращаться к курирующему менеджеру Ecommpay | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/unionpay-securepay/)| **Прим.:** \* Подробную информацию следует уточнять у курирующего менеджера Ecommpay. ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода China UnionPay задействуются веб-сервис мерчанта, один из интерфейсови платёжная платформа Ecommpay, а также технические средства сервиса China UnionPay. ![](images/pm/ru_chinaunionpay_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода China UnionPay могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода China UnionPay осуществляется с перенаправлением пользователей к сервису China UnionPay, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_chinaunionpay_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_chinaunionpay_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_chinaunionpay_interfaces_gate_refund.svg "Возврат через Gate") ## Оплаты через Payment Page {#ru_pm_unionpay_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода China UnionPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод China UnionPay. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода China UnionPay. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис China UnionPay. 10. В сервисе China UnionPay выполняется обработка запроса на оплату. 11. От сервиса China UnionPay к платёжной платформе передаются данные для перенаправления пользователя к сервису China UnionPay. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису China UnionPay. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе China UnionPay выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе China UnionPay. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса China UnionPay к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом China UnionPay через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода China UnionPay необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно, в зависимости от провайдера, обрабатывающего платёж, может потребоваться указать фамилию пользователя в рамках проекта в параметре `customer_last_name` \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Валютой платежа может быть одна из следующих валют [AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md). Информацию о доступных валютах следует уточнять у курирующего менеджера Ecommpay. 4. Payment Page можно открывать на китайском языке. Для этого необходимо передавать код языка `zh` в параметре `language_code` \(подробнее — в разделе [Управление языком платёжной формы](ru_PP_WigetLanguages.md)\). 5. Для предварительного выбора метода China UnionPay необходимо указывать код этого метода в параметре `force_payment_method` — `cup-union`. 6. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 7. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода China UnionPay должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и фамилию пользователя, а также подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "USD", "customer_id": "customer1", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` была проведена оплата в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "success", "date": "2018-12-06T13:33:33+0000", "method": "unionpay", "sum": { "amount": 100, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002161, "type": "sale", "status": "success", "date": "2018-12-06T13:33:33+0000", "created_date": "2018-12-06T13:31:41+0000", "request_id": "986be38f02e8fe3fb8-c1990f3e7af3", "sum_initial": { "amount": 100, "currency": "USD" }, "sum_converted": { "amount": 100, "currency": "USD" }, "provider": { "id": 410, "payment_id": "74580000021610207055371314024366", "date": "2018-12-06T13:31:42+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1548340290097231", "type": "purchase", "status": "decline", "date": "2019-01-26T14:36:35+0000", "method": "unionpay", "sum": { "amount": 2000000, "currency": "CNY" }, "description": "TEST_1548340290097" }, "customer": { "id": "1" }, "operation": { "id": 4723000002794, "type": "sale", "status": "decline", "date": "2019-01-26T14:36:35+0000", "created_date": "2019-01-24T14:36:33+0000", "request_id": "72b28ec3f95271699dcade", "sum_initial": { "amount": 2000000, "currency": "CNY" }, "sum_converted": { "amount": 294684, "currency": "USD" }, "provider": { "id": 410, "payment_id": "47230000027940105280386327826886", "date": "2019-01-24T14:36:35+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_unionpay_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода China UnionPay со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису China UnionPay. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода China UnionPay. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис China UnionPay. 7. В сервисе China UnionPay выполняется обработка запроса на оплату. 8. От сервиса China UnionPay к платёжной платформе передаются данные для перенаправления пользователя к сервису China UnionPay. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису China UnionPay. 10. Пользователь перенаправляется к сервису China UnionPay. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе China UnionPay выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса China UnionPay к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом China UnionPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на оплату с применением метода China UnionPay необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/cup/union/sale](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-cup-union-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `last_name*` — фамилия \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\). Если параметр не указан в запросе, то он дополнительно запрашивается в оповещении о необходимости дополнить данные \(подробнее — в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md)\); - `return_url*` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `success*` — URL для перенаправления пользователя после проведения оплаты, - `return*` — URL для перенаправления пользователя на любом шаге оплаты. **Прим.:** \*Информацию обязательности этих параметров необходимо уточнять у курирующего менеджера Ecommpay. 3. Валютой платежа может быть одна из следующих валют [AUD](references/ru/currencies/AUD.md), [CAD](references/ru/currencies/CAD.md), [CHF](references/ru/currencies/CHF.md), [CNY](references/ru/currencies/CNY.md), [EUR](references/ru/currencies/EUR.md), [GBP](references/ru/currencies/GBP.md), [HKD](references/ru/currencies/HKD.md), [JPY](references/ru/currencies/JPY.md), [NZD](references/ru/currencies/NZD.md), [SGD](references/ru/currencies/SGD.md), [USD](references/ru/currencies/USD.md), [THB](references/ru/currencies/THB.md). Информацию о доступных валютах следует уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода China UnionPay должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 198, "payment_id": "TEST_15532590003171111", "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...==" }, "customer": { "ip_address": "192.0.2.0", "last_name": "Johnson" "id": "123" }, "payment": { "amount": 1000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "return": "https://example.com/return" } } ``` ```language-json { "general": { "project_id": 198, "payment_id": "TEST_15532590003171111", "signature": "dMNfpKk0MnZhXWKjAKWTckxgEoNbjNhOYQMh6lB4C9J7gksH...==" }, "customer": { "ip_address": "192.0.2.0", "last_name": "Johnson" "id": "123" }, "payment": { "amount": 1000, "currency": "USD" }, "return_url": { "success": "https://example.com/success", "return": "https://example.com/return" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису China UnionPay при проведении каждого платежа с использованием метода China UnionPay необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` была проведена оплата в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "success", "date": "2018-12-06T13:33:33+0000", "method": "unionpay", "sum": { "amount": 100, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002161, "type": "sale", "status": "success", "date": "2018-12-06T13:33:33+0000", "created_date": "2018-12-06T13:31:41+0000", "request_id": "986be38f02e8fe3fb8-c1990f3e7af3", "sum_initial": { "amount": 100, "currency": "USD" }, "sum_converted": { "amount": 100, "currency": "USD" }, "provider": { "id": 410, "payment_id": "74580000021610207055371314024366", "date": "2018-12-06T13:31:42+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "lci0uOA7aWgJ5nwyImqQjXAfdP+nEzyXwb/t9G1E1U8+5vDkdb...==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1548340290097231", "type": "purchase", "status": "decline", "date": "2019-01-26T14:36:35+0000", "method": "unionpay", "sum": { "amount": 2000000, "currency": "CNY" }, "description": "TEST_1548340290097" }, "customer": { "id": "1" }, "operation": { "id": 4723000002794, "type": "sale", "status": "decline", "date": "2019-01-26T14:36:35+0000", "created_date": "2019-01-24T14:36:33+0000", "request_id": "72b28ec3f95271699dcade", "sum_initial": { "amount": 2000000, "currency": "CNY" }, "sum_converted": { "amount": 294684, "currency": "USD" }, "provider": { "id": 410, "payment_id": "47230000027940105280386327826886", "date": "2019-01-24T14:36:35+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "vOpSHO5fMolQhUGItTilgFKcVkbdmBMaf2cD7FsIB...==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_unionpay_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода China UnionPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.В некоторых случаях, по одному платежу вы можете выполнить только один частичный возврат, далее для совершения дополнительных возвратов по этому платежу вам необходимо обратиться в службу технической поддержки платежной системы. Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_chinaunionpay_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис China UnionPay. 7. В сервисе China UnionPay выполняется обработка возврата. 8. От сервиса China UnionPay к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом China UnionPay через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода China UnionPay необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/unionpay/refund](https://api-developers.ecommpay.com/api-specification/china-unionpay/post-v2-payment-unionpay-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода China UnionPay должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возврата с применением метода China UnionPay используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `198` был выполнен возврат в размере `10,00 USD`. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_154402240162030", "type": "purchase", "status": "refunded", "date": "2018-12-06T14:24:08+0000", "method": "unionpay", "sum": { "amount": 1000, "currency": "USD" }, "description": "TEST_154402240162930" }, "operation": { "id": 7458000002162, "type": "refund", "status": "success", "date": "2018-12-06T14:24:08+0000", "created_date": "2018-12-06T14:23:58+0000", "request_id": "758cf8a4a495acf7f27eb0c1b", "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1000, "currency": "USD" }, "provider": { "id": 410, "payment_id": "", "date": "2018-12-06T22:24:04+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "pHyB8h89qctuJ3ksW9xsERYpVSi3SDWAAWnknJw4o9f...==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ```language-json "callbackBody": { "project_id": 198, "payment": { "id": "TEST_1542789072282111", "type": "purchase", "status": "partially refunded", "date": "2018-11-21T12:33:38+0000", "method": "unionpay", "sum": { "amount": 50, "currency": "USD" }, "description": "TEST_1542789072282" }, "customer": { "id": "1" }, "errors": [ { "code": "2701", "message": "Rules Failed Code", "description": "fatal: RULES_FAILED_CODE" } ], "operation": { "id": 16115000001979, "type": "refund", "status": "decline", "date": "2018-11-21T12:49:38+0000", "created_date": "2018-11-21T12:49:38+0000", "request_id": "3abc68c33b2298127", "sum_initial": { "amount": 50, "currency": "USD" }, "sum_converted": { "amount": 50, "currency": "USD" }, "provider": { "id": 410, "payment_id": "" }, "code": "2701", "message": "Rules Failed Code" }, "signature": "hAS3NXs1LmLl0xYtaHqLrRCAANBq1Z+/g26NVka...==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_unionpay_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу China UnionPay, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Ecuador Online Banking {#pm_ecuador_ob} статья о работе с платёжным методом Ecuador Online Banking, который позволяет проводить платежи в долларах США с использованием банковских счетов в Эквадоре и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_ecuador_ob_overview} статья о работе с платёжным методом Ecuador Online Banking, который позволяет проводить платежи в долларах США с использованием банковских счетов в Эквадоре и для которого в платформе Ecommpay поддерживаются оплаты и возвраты ### Введение {#section_ql3_5fj_stb .section} Ecuador Online Banking — метод, позволяющий проводить платежи в долларах США с использованием банковских счетов в Эквадоре. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и возвраты. В этой статье представлена информация о работе с методом Ecuador Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[EC](references/ru/countries/EC.md)| |Валюты платежей|[USD](references/ru/currencies/USD.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|проведение полного и частичного возврата возможно в течение 90 календарных дней после проведения оплаты| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Ecuador Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_ecuador_ob_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Ecuador Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы¹|Время²| |минимум|максимум|базовое|предельное| |--|------|------| |-------|--------|-------|----------| |Оплаты|\*|\*|3 минуты|36 часов| |Возвраты|\*|\*|5 минут|36 часов| **Прим.:** 1. Минимальные и максимальные суммы платежа зависят от банков, доступных для выбора пользователю после перенаправления к сервису провайдера. Если сумма платежа не соответствует ограничениям банка, его выбор недоступен. 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Ecuador Online Banking осуществляется с перенаправлением пользователей к сервису провайдера, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_ecuador_ob_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_ecuador_ob_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_pm_ecuador_ob_interfaces_gate_refund.svg "Возврат через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Ecuador Online Banking соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_ecuador_ob_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Ecuador Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_ecuador_ob_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка к открытию платёжной формы согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Ecuador Online Banking. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Ecuador Online Banking. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 15. В сервисе провайдера выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе провайдера. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Ecuador Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Ecuador Online Banking необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — буквенный код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно необходимо указывать имя, фамилию и адрес электронной почты пользователя в параметрах `customer_first_name`, `customer_last_name` и `customer_email`. Для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов в значениях параметров `customer_first_name` и `customer_last_name`. 3. Для предварительного выбора метода Ecuador Online Banking необходимо указывать код этого метода в параметре `force_payment_method` — `online-ecuador-banks`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Ecuador Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_gdb_pts_w2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ``` {#codeblock_hzt_vsw_x2c .language-json} { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "USD", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Doe", "customer_email": "johndoe@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Ecuador Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "ecuador", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c68bf9a123911551da98eb071c-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lfth8yxvoqn/PmpHnKhIw+5XaZ/xfTIf6Kl+WjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "ecuador", "sum": { "amount": 1000, "currency": "USD" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "USD" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8b07d9f04422befb1e501a90a-05031181" }, "signature": "XvIAwMNq/nDzn28ZwuI5kKquIdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_ecuador_ob_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Ecuador Online Banking со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису провайдера. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_ecuador_ob_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Ecuador Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его оправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера. 11. Пользователь выполняет необходимые действия для оплаты на стороне сервиса провайдера. 12. В сервисе провайдера выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Ecuador Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода Ecuador Online Banking необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/ecuador/sale`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — буквенный код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. 3. Дополнительно необходимо указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `last_name` — фамилия пользователя \(для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов\); - `email` — адрес электронной почты пользователя. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Ecuador Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись, а также может содержать различные дополнительные параметры. ``` {#codeblock_wwl_c5s_w2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com" } } ``` ``` {#codeblock_fp4_1tw_x2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "USD" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Doe", "email": "johndoe@example.com" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису провайдера при проведении каждого платежа с использованием метода Ecuador Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ``` {#codeblock_t1c_gx1_1fc .language-json} "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_wsx_3jl_ggb .section} Для итоговых оповещений об оплатах с применением метода Ecuador Online Banking используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `123456` для пользователя `1` была проведена оплата в размере `100,00 USD`. ``` {#codeblock_hdb_pts_w2c .language-json} { "project_id": 123456, "payment": { "id": "24113462", "type": "purchase", "status": "success", "date": "2025-04-28T12:35:34+0000", "method": "ecuador", "sum": { "amount": 10000, "currency": "USD" }, "description": "Test sale TEST_PAYMENT_280425_1" }, "customer": { "id": "1" }, "operation": { "id": 3096000012631, "type": "sale", "status": "success", "date": "2025-04-28T12:35:34+0000", "created_date": "2025-04-28T12:20:31+0000", "request_id": "10ebdff5fbed43c6e7a33ff2d9b4-00003097", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 21463, "payment_id": "140347770236", "auth_code": "" } }, "signature": "vZ8+G9mQFv1lf+WjRkHKXE29nw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` {#codeblock_idb_pts_w2c .language-json} { "customer": { "id": "1" }, "project_id": 59051, "payment": { "id": "TEST_PAYMENT_398957", "type": "purchase", "status": "decline", "date": "2025-04-21T01:15:28+0000", "method": "ecuador", "sum": { "amount": 1000, "currency": "EUR" }, "description": "TEST_PAYMENT_398957" }, "operation": { "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1139, "currency": "USD" }, "code": "20000", "message": "General decline", "provider": { "id": 16353, "payment_id": "140347102975", "auth_code": "" }, "id": 5031180010141499, "type": "sale", "status": "decline", "date": "2025-04-21T01:15:28+0000", "created_date": "2025-04-14T12:15:04+0000", "request_id": "a57b332905b8501a90a-05031181" }, "signature": "XvIAwMNq/nDzdamW2Xzu4uS4v9PnLw==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_ecuador_ob_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода Ecuador Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_pm_ecuador_ob_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка возврата. 8. От сервиса провайдера к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом Ecuador Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возвраты с применением метода Ecuador Online Banking необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/refund](https://api-developers.ecommpay.com/api-specification/direct-debit/post-v2-payment-refund). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода Ecuador Online Banking должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя и подпись, а также, при необходимости, код валюты и сумму возврата. ``` {#codeblock_fqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ``` {#codeblock_gqj_w1d_t2c .language-json} { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "USD" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возвратов с применением метода Ecuador Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `433772` для пользователя `1` был выполнен полный возврат в размере `100,00 USD`. ``` {#codeblock_pmy_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "TEST_PAYMENT_265608", "type": "purchase", "status": "refunded", "date": "2025-06-26T06:48:37+0000", "method": "ecuador", "sum": { "amount": 0, "currency": "USD" }, "description": "TEST_PAYMENT_265608" }, "customer": { "id": "1" }, "operation": { "id": 7373000014760, "type": "refund", "status": "success", "date": "2025-06-26T06:48:37+0000", "created_date": "2025-06-26T06:48:34+0000", "request_id": "ad3982700e2b1db7038c7fada82ab9c85e4071f0-8e341c2093149beae0f501759402e5753c7d7f2c-00007374", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "0", "message": "Success", "provider": { "id": 1903, "payment_id": "1750920516487", "auth_code": "" } }, "signature": "GpBmChC6jOdrdA7Shl5UBhX1Soj+efRx//eCni5FFx+9Fa7KTqa1y6zQfZu7hXeEB19vWtEOuCr2L/VFmkQ3DQ==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ``` {#codeblock_iqj_w1d_t2c .language-json} { "project_id": 433772, "payment": { "id": "test_29.04.25_3", "type": "purchase", "status": "partially refunded", "date": "2024-12-29T11:36:34+0000", "method": "ecuador", "sum": { "amount": 20000, "currency": "USD" }, "description": "test_29.04.25_3" }, "customer": { "id": "1" }, "operation": { "id": 5557000012956, "type": "refund", "status": "decline", "date": "2024-12-29T11:22:44+0000", "created_date": "2024-12-29T11:22:44+0000", "request_id": "c717b3de84d1ba574598a637f856a-00002267", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "code": "3283", "message": "Refund amount more than init amount", "provider": { "id": 21514, "payment_id": "1418092457", "auth_code": "" } }, "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как организовать взаимодействие с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Dashboard {#ru_pm_dash_refund} При использовании интерфейса Dashboard можно выполнять возвратыметодом Ecuador Online Banking с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для выполнения одиночного возврата необходимо выбрать целевую оплату, открыть карточку этой оплаты, указать сумму возврата, отправить запрос и убедиться в выполнении возврата. - Для выполнения массового возврата необходимо подготовить и загрузить файл с информацией обо всех целевых возвратах, отправить пакет запросов и убедиться в выполнении возвратов. При этом должен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры возвратов — требованиям, представленным в разделе [Возвраты через Gate](pm_ecuador_ob.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о выполнении возвратов через Dashboard представлена в [отдельном разделе](ru_dbl_payments.md). ## Анализ результатов проведения платежей {#ru_pm_ecuador_ob_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Ecuador Online Banking, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # EPS {#pm_eps} статья о работе с платёжным методом EPS, который позволяет проводить платежи в евро с использованием банковских счетов в Австрии и для которого в платформе Ecommpay поддерживаются оплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_eps_overview} статья о работе с платёжным методом EPS, который позволяет проводить платежи в евро с использованием банковских счетов в Австрии и для которого в платформе Ecommpay поддерживаются оплаты ### Введение {#section_ql3_5fj_stb .section} EPS — метод, позволяющий проводить платежи в евро с использованием банковских счетов в Австрии.Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты. В этой статье представлена информация о работе с методом EPS: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[AT](references/ru/countries/AT.md)| |Валюты платежей|[EUR](references/ru/currencies/EUR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|–| |Опротестования|–| |Особенности|–| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [ecommshop](https://ecommpay.com/shop/payment-methods/eps/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода EPS задействуются веб-сервис мерчанта, один из интерфейсови платёжная платформа Ecommpay, а также технические средства сервиса EPS. ![](images/pm/ru_eps_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода EPS могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [EUR](references/ru/currencies/EUR.md)¹|Время²| |минимум|максимум|базовое|предельное| |--|----------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|1,00|10 000,00|в пределах 10 минут|до 48 часов| **Прим.:** 1. Точную информацию по лимитам сумм уточняйте у курирующего менеджера Ecommpay 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода EPS осуществляется с перенаправлением пользователей к сервису EPS. ![](images/pm/ru_eps_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_eps_interfaces_gate.svg "Оплата через Gate") ## Оплаты через Payment Page {#ru_pm_eps_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода EPS со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_eps_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод EPS. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода EPS. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис EPS. 10. В сервисе EPS выполняется обработка запроса на оплату. 11. От сервиса EPS к платёжной платформе передаются данные для перенаправления пользователя к сервису EPS. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису EPS. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе EPS выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе EPS. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса EPS к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом EPS через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода EPS необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Дополнительно рекомендуется указывать имя, фамилию и адрес электронной почты пользователя в параметрах `customer_first_name`, `customer_last_name` и `customer_email`. Если какие-либо из этих параметров отсутствуют в запросе, в платёжной форме могут отображаться поля для ввода пользователем недостающих значений \(подробнее — в разделе [Дополнение информации о платежах](ru_pp_clarification.md)\). 3. Для предварительного выбора метода EPS необходимо указывать код этого метода в параметре `force_payment_method` — `eps`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода EPS должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "EUR", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Johnson", "customer_email": "John@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "EUR", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Johnson", "customer_email": "John@example.com", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода EPS используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `238` была проведена оплата в размере `10,00 EUR`. ```language-json { { "project_id": 238, "payment": { "id": "TEST_1560760354708", "type": "purchase", "status": "success", "date": "2019-06-17T08:56:47+0000", "method": "eps", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "operation": { "id": 29891000002914, "type": "sale", "status": "success", "date": "2019-06-17T08:56:47+0000", "created_date": "2019-06-17T08:50:34+0000", "request_id": "0d6aabd20c7925f1719b7cb63f728b32a3450cf0", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1208, "payment_id": "148907", "date": "2019-06-17T08:56:46+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "V0zYWk7OzwfcMBAJJxArOuQoQfNv92z0wBJeQIHwj75hpkuXFNqHjYGMdfhycMw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { { "project_id": 238, "payment": { "id": "TEST_156162712312", "type": "purchase", "status": "decline", "date": "2019-06-27T12:53:58+0000", "method": "eps", "sum": { "amount": 500, "currency": "USD" }, "description": "TEST_1561627597648" }, "customer": { "id": "1" }, "operation": { "id": 1590021, "type": "sale", "status": "decline", "date": "2019-06-27T12:53:58+0000", "created_date": "2019-06-27T12:49:41+0000", "request_id": "935dc4ba8b35ca5046", "sum_initial": { "amount": 500, "currency": "USD" }, "sum_converted": { "amount": 440, "currency": "EUR" }, "provider": { "id": 1239, "payment_id": "922806", "date": "2019-06-27T12:53:57+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "S4qhcifHHzZgnOwRC0GSsEfoPl9zyGnNp7g==" } } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_eps_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода EPS со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису EPS. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_eps_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода EPS. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис EPS. 7. В сервисе EPS выполняется обработка запроса на оплату. 8. От сервиса EPS к платёжной платформе передаются данные для перенаправления пользователя к сервису EPS. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису EPS. 10. Пользователь перенаправляется к сервису EPS. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе EPS выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса EPS к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом EPS через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода EPS необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/bank-transfer/eps/sale`. Эта точка относится к группе [/v2/payment/bank-transfer/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/bank-transfer/post-v2-payment-bank-transfer-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `first_name` — имя пользователя; - `last_name` — фамилия пользователя; - `email` — адрес электронной почты пользователя; - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для перенаправления пользователя во время проведения оплаты. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода EPS должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 2990, "payment_id": "payment_id", "signature": "PJkV8ej\/UG0Di8NN5e7cIipTv+AWoXW\/9MTO8yJA==" }, "customer": { "ip_address": "192.0.2.0", "email": "Johnson@mail.com", "first_name": "John", "last_name": "Johnson", "id": "123" }, "payment": { "amount": 1000, "currency": "EUR" }, "return_url": { "return": "http://example.com" } } ``` ```language-json { "general": { "project_id": 2990, "payment_id": "payment_id", "signature": "PJkV8ej\/UG0Di8NN5e7cIipTv+AWoXW\/9MTO8yJA==" }, "customer": { "ip_address": "192.0.2.0", "email": "Johnson@mail.com", "first_name": "John", "last_name": "Johnson", "id": "123" }, "payment": { "amount": 1000, "currency": "EUR" }, "return_url": { "return": "http://example.com" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису EPS при проведении каждого платежа с использованием метода EPS необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода EPS используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `238` была проведена оплата в размере `10,00 EUR`. ```language-json { { "project_id": 238, "payment": { "id": "TEST_1560760354708", "type": "purchase", "status": "success", "date": "2019-06-17T08:56:47+0000", "method": "eps", "sum": { "amount": 1000, "currency": "EUR" }, "description": "" }, "operation": { "id": 29891000002914, "type": "sale", "status": "success", "date": "2019-06-17T08:56:47+0000", "created_date": "2019-06-17T08:50:34+0000", "request_id": "719b7cb63f728b32a3450cf0", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1208, "payment_id": "148907", "date": "2019-06-17T08:56:46+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "V0zYWk7OzwfcMBAJJxArOuQoQfNv92z0wBJeQIHwj75huXFNqHjYGMdfhycMw==" } } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { { "project_id": 238, "payment": { "id": "TEST_156162712312", "type": "purchase", "status": "decline", "date": "2019-06-27T12:53:58+0000", "method": "eps", "sum": { "amount": 500, "currency": "USD" }, "description": "TEST_1561627597648" }, "customer": { "id": "1" }, "operation": { "id": 1590021, "type": "sale", "status": "decline", "date": "2019-06-27T12:53:58+0000", "created_date": "2019-06-27T12:49:41+0000", "request_id": "935dc4ba8b35ca5046", "sum_initial": { "amount": 500, "currency": "USD" }, "sum_converted": { "amount": 440, "currency": "EUR" }, "provider": { "id": 1239, "payment_id": "922806", "date": "2019-06-27T12:53:57+0000", "auth_code": "" }, "code": "20000", "message": "General decline" }, "signature": "S4qhcifHHzZgnOwRC0GSsEfoPl9zyGnNp7g==" } } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_eps_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу EPS, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # iDEAL \| Wero {#pm_ideal} статья о работе с платёжным методом iDEAL \| Wero, который позволяет проводить платежи в евро с использованием банковских счетов в Нидерландах и для которого в платформе Ecommpay поддерживаются оплаты и возвраты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_ideal_overview} статья о работе с платёжным методом iDEAL \| Wero, который позволяет проводить платежи в евро с использованием банковских счетов в Нидерландах и для которого в платформе Ecommpay поддерживаются оплаты и возвраты ### Введение {#section_ql3_5fj_stb .section} iDEAL \| Wero — метод, позволяющий проводить платежи в евро с использованием банковских счетов в Нидерландах. Для этого метода в платёжной платформе Ecommpay поддерживаются оплатыи возвраты. В этой статье представлена информация о работе с методом iDEAL \| Wero: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[NL](references/ru/countries/NL.md)| |Валюты платежей|[EUR](references/ru/currencies/EUR.md)| |Конвертация валют|–| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|+| |Частичные возвраты|+| |Выплаты|–| |Опротестования|–| |Особенности|–| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [Ecommpay shop](https://ecommpay.com/shop/payment-methods/ovo-wallet/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода iDEAL \| Wero задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса iDEAL \| Wero. ![](images/pm/ru_ideal_wero_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода iDEAL \| Wero могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие ограничения. ||Суммы, [EUR](references/ru/currencies/EUR.md)| |Минимум|Максимум| |--|---------------------------------------------| |-------|--------| |Оплаты|0,01|–| |Полные возвраты|–|–| |Частичные возвраты|–|–| ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода iDEAL \| Wero осуществляется с перенаправлением пользователей к сервису iDEAL \| Wero, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса. ![](images/pm/ru_ideal_wero_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_ideal_wero_interfaces_gate.svg "Оплата через Gate") ![](images/pm/ru_ideal_wero_interfaces_gate_refund.svg "Возврат через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом iDEAL \| Wero соответствуют специфике этих возможностей. ## Оплаты через Payment Page {#ru_pm_ideal_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода iDEAL \| Wero со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_ideal_wero_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод iDEAL \| Wero. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода iDEAL \| Wero. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис iDEAL \| Wero. 10. В сервисе iDEAL \| Wero выполняется обработка запроса на оплату. 11. От сервиса iDEAL \| Wero к платёжной платформе передаются данные для перенаправления пользователя к сервису iDEAL \| Wero. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису iDEAL \| Wero. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе iDEAL \| Wero выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе iDEAL \| Wero. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса iDEAL \| Wero к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом iDEAL \| Wero через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода iDEAL \| Wero необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Валютой платежа может быть только [EUR](references/ru/currencies/EUR.md). 3. Дополнительно рекомендуется указывать имя и фамилию пользователя в параметрах `customer_first_name` и `customer_last_name`. Если параметрs отсутствуют в запросе, на Payment Page пользователю отображаются поля для ввода недостающих значений. Подробнее об уточнении параметров — в разделе [Дополнение информации о платежах](ru_pp_clarification.md). 4. Для предварительного выбора метода iDEAL \| Wero необходимо указывать код платёжного метода в параметре `force_payment_method` — `ideal`. 5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 6. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода iDEAL \| Wero должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "EUR", "customer_id": "customer1", "customer_first_name": "John", "customer_last_name": "Johnson", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода iDEAL \| Wero используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `238` была проведена оплата в размере `10,00 EUR`. ``` { "project_id": 238, "payment": { "id": "TEST_15452119890903333", "type": "purchase", "status": "success", "date": "2018-12-20T13:40:56+0000", "method": "ideal", "sum": { "amount": 1000, "currency": "EUR" }, "description": "ECT_TEST_1545211989090" }, "customer": { "id": "1" }, "operation": { "id": 18496000002369, "type": "sale", "status": "success", "date": "2018-12-20T13:40:56+0000", "created_date": "2018-12-20T13:40:15+0000", "request_id": "768e72d3284eb2b269e4f3", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "353827769", "date": "2018-12-20T13:40:56+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "ylWj/35wPzQRspdwDHjdWcCYMduHnXwxMxYZy17g==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ``` { "project_id": 1569, "payment": { "id": "145408-190628095914-cmY0LnByZ=", "type": "purchase", "status": "decline", "date": "2019-06-28T09:59:58+0000", "method": "ideal", "sum": { "amount": 300, "currency": "EUR" }, "description": "3 Tage Premium-Mitgliedschaft" }, "customer": { "id": "145408" }, "operation": { "id": 33841000003201, "type": "sale", "status": "decline", "date": "2019-06-28T09:59:58+0000", "created_date": "2019-06-28T09:59:16+0000", "request_id": "cef7a32aa22a4e4bc8", "sum_initial": { "amount": 300, "currency": "EUR" }, "sum_converted": { "amount": 300, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "474810276", "date": "2019-06-28T09:59:45+0000", "auth_code": "" }, "code": "20301", "message": "Account owner cancelled operation" }, "signature": "LifBDhURNHVkzL1UxRCp1JNbQ9M46TyotjGT5io17TSw==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_ideal_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода iDEAL \| Wero со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису iDEAL \| Wero. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_ideal_wero_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода iDEAL \| Wero. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис iDEAL \| Wero. 7. В сервисе iDEAL \| Wero выполняется обработка запроса на оплату. 8. От сервиса iDEAL \| Wero к платёжной платформе передаются данные для перенаправления пользователя к сервису iDEAL \| Wero. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису iDEAL \| Wero. 10. Пользователь перенаправляется к сервису iDEAL \| Wero. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе iDEAL \| Wero выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса iDEAL \| Wero к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом iDEAL \| Wero через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на оплату с применением метода iDEAL \| Wero необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/online-banking/ideal/sale`. Эта точка относится к группе интернет-банкинга [/v2/payment/online-banking/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/online-banking/post-v2-payment-online-banking-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для перенаправления пользователя на любом шаге оплаты. 3. Дополнительно рекомендуется указывать имя и фамилию пользователя в параметрах `first_name` и `last_name` объекта `customer`. Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение \(подробнее — в статье [Дополнение информации о платеже](ru_Gate_Clarification.md)\). 4. Валютой платежа может быть только [EUR](references/ru/currencies/EUR.md). 5. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода iDEAL \| Wero должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": "payment_id", "signature": "PJkV8ej\/UG0OMeSaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "customer": { "ip_address": "192.0.2.0", "first_name": "John", "last_name": "Johnson", "id": "123" }, "payment": { "amount": 1000, "currency": "EUR" }, "return_url": { "return": "http://example.com" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису iDEAL \| Wero при проведении каждого платежа с использованием метода iDEAL \| Wero необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода iDEAL \| Wero используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `238` была проведена оплата в размере `10,00 EUR`. ```language-json { "project_id": 238, "payment": { "id": "TEST_15452119890903333", "type": "purchase", "status": "success", "date": "2018-12-20T13:40:56+0000", "method": "ideal", "sum": { "amount": 1000, "currency": "EUR" }, "description": "ECT_TEST_1545211989090" }, "customer": { "id": "1" }, "operation": { "id": 18496000002369, "type": "sale", "status": "success", "date": "2018-12-20T13:40:56+0000", "created_date": "2018-12-20T13:40:15+0000", "request_id": "768e72d3284eb2b269e4f3", "sum_initial": { "amount": 1000, "currency": "EUR" }, "sum_converted": { "amount": 1000, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "353827769", "date": "2018-12-20T13:40:56+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "ylWj/35wPzQRspdwDHjdWcCYMduHnXwxMxYZy17g==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 1569, "payment": { "id": "145408-190628095914-cmY0LnByZ=", "type": "purchase", "status": "decline", "date": "2019-06-28T09:59:58+0000", "method": "ideal", "sum": { "amount": 300, "currency": "EUR" }, "description": "3 Tage Premium-Mitgliedschaft" }, "customer": { "id": "145408" }, "operation": { "id": 33841000003201, "type": "sale", "status": "decline", "date": "2019-06-28T09:59:58+0000", "created_date": "2019-06-28T09:59:16+0000", "request_id": "cef7a32aa22a4e4bc8", "sum_initial": { "amount": 300, "currency": "EUR" }, "sum_converted": { "amount": 300, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "474810276", "date": "2019-06-28T09:59:45+0000", "auth_code": "" }, "code": "20301", "message": "Account owner cancelled operation" }, "signature": "LifBDhURNHVkzL1UxRCp1JNbQ9M46TyotjGT5io17TSw==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Возвраты через Gate {#ru_pm_ideal_gate_refund} ### Общая информация {#section_lsx_3jl_ggb .section} Для выполнения возврата через Gate с использованием метода iDEAL \| Wero со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема выполнения возврата выглядит следующим образом. ![](images/pm/ru_ideal_wero_uml_gate_refund.svg) 1. Пользователь инициирует возврат. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на выполнение возврата. 3. Запрос на выполнение возврата поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис iDEAL \| Wero. 7. В сервисе iDEAL \| Wero выполняется обработка возврата. 8. От сервиса iDEAL \| Wero к платёжной платформе направляется информация о результате возврата. 9. От платёжной платформы к веб-сервису направляется оповещение о результате возврата. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате возврата. Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом iDEAL \| Wero через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на возврат с применением метода iDEAL \| Wero необходимо учитывать следующее: 1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/online-banking/ideal/refund`. Эта точка относится к группе точек для платежей с использованием интернет-банкинга [/v2/payment/online-banking/\{payment\_method\}/refund](https://api-developers.ecommpay.com/api-specification/online-banking/post-v2-payment-online-banking-payment-method-refund) 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, для которого необходимо выполнить возврат; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о возврате: - `description` — комментарий к возврату или его описание; - `amount` — сумма возврата в дробных единицах валюты \(является обязательной при частичном возврате\); - `currency` — код валюты возврата в формате ISO-4217 alpha-3\(является обязательным при частичном возврате\); - `customer` — объект, содержащий сведения о пользователе: - `ip_address` — IP-адрес пользователя, актуальный для инициируемого возврата. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на возврат с применением метода iDEAL \| Wero должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, код валюты и сумму возврата. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "EUR" }, "customer": { "ip_address": "192.0.2.0" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "description": "test refund", "amount": 1000, "currency": "EUR" }, "customer": { "ip_address": "192.0.2.0" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах возврата с применением метода iDEAL \| Wero используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `238` был выполнен возврат в размере `1,00 EUR`. ```language-json { "project_id": 238, "payment": { "id": "TEST_15611060328012", "type": "purchase", "status": "refunded", "date": "2019-06-21T11:15:40+0000", "method": "ideal", "sum": { "amount": 100, "currency": "EUR" }, "description": "" }, "provider_extra_fields": { "description": "Refund" }, "operation": { "id": 36084000003050, "type": "refund", "status": "success", "date": "2019-06-21T11:15:40+0000", "created_date": "2019-06-21T11:15:38+0000", "request_id": "ec1a34153dc43fe1bae7b6397", "sum_initial": { "amount": 100, "currency": "EUR" }, "sum_converted": { "amount": 100, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "105796085", "date": "2019-06-21T11:15:39+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "DtwI1Wbg6Wda71k/xdGWGE2qHhfA7naVeEk0wtfqg==" } ``` В следующем примере оповещение свидетельствует об отклонённом возврате. ```language-json { "project_id": 238, "payment": { "id": "TEST_15611060328012", "type": "purchase", "status": "success", "date": "2019-06-21T08:39:50+0000", "method": "ideal", "sum": { "amount": 100, "currency": "EUR" }, "description": "" }, "errors": [ { "code": "100", "message": "General decline", "description": "Gate. Operation was declined. General Gate error" } ], "operation": { "id": 36084000003046, "type": "refund", "status": "decline", "date": "2019-06-21T09:42:44+0000", "created_date": "2019-06-21T09:42:44+0000", "request_id": "5d0c7bf5304685ab9c9613a8e9a86", "sum_initial": { "amount": 100, "currency": "EUR" }, "sum_converted": { "amount": 100, "currency": "EUR" }, "provider": { "id": 1170, "payment_id": "" }, "code": "100", "message": "General decline" }, "signature": "AX+FugJdXeHaIUiIjCpaTk94+4gIvrhj/6n3PBA==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с возвратами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Возвраты средств после оплат](ru_Gate_Refund.md)— о том, как выполнять возвраты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_ideal_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу iDEAL \| Wero, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Indonesian Online Banking {#pm_indonesia} статья о работе с платёжным методом Indonesian Online Banking, который позволяет проводить платежи в индонезийских рупиях с использованием банковских счетов в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_indonesia_overview} статья о работе с платёжным методом Indonesian Online Banking, который позволяет проводить платежи в индонезийских рупиях с использованием банковских счетов в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты ### Введение {#section_ql3_5fj_stb .section} Indonesian Online Banking — метод, позволяющий проводить платежи в индонезийских рупиях с использованием банковских счетов в Индонезии. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и выплаты. В этой статье представлена информация о работе с методом Indonesian Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[ID](references/ru/countries/ID.md)| |Валюты платежей|[IDR](references/ru/currencies/IDR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|+| |Опротестования|–| |Особенности|- при работе с Payment Page поддерживаются разные варианты выбора банка, [подробнее](pm_indonesia.md#section_p5j_fgl_ggb) - При использовании этого метода все платежи в валюте [IDR](references/ru/currencies/IDR.md) являются целочисленными. В запросах с указанием валюты [IDR](references/ru/currencies/IDR.md) следует округлять суммы до целых чисел, иначе дробная часть отсекается при обработке платежа в платёжной платформе. При указании в запросах других валют сумма платежа конвертируется на стороне Ecommpay с округлением до 1 000,00 [IDR](references/ru/currencies/IDR.md) - в браузере Safari может не поддерживаться перенаправление на сервис банка. Подробности необходимо уточнять у курирующего менеджера Ecommpay | |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [Ecommpay shop](https://ecommpay.com/shop/payment-methods/online-banking-indonesia/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Indonesian Online Banking задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса одного из банков. ![](images/pm/ru_banks_indonesia_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Indonesian Online Banking могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\), а выплаты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [IDR](references/ru/currencies/IDR.md)|Время¹| |минимум|максимум|базовое|предельное| |--|---------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|100 000,00|25 000 000,00|\*|\*| |Выплаты|100 000,00|10 000 000,00|\*|\*| **Прим.:** 1. Ограничения по времени выполнения операций зависят от банков, поддерживающих оплату этим методом. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Indonesian Online Banking осуществляется с перенаправлением пользователей к сервису банка, проведение выплат — с уведомлением пользователей через веб-сервис мерчанта. Пользовательский сценарий оплаты через Payment Page \(в базовом варианте с выбором пользователем метода и банка и перенаправлением с итоговой страницы платёжной формы к веб-сервису\) выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_2.svg "Выбор метода") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_3.svg "Выбор банка") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_4.svg "Аутентификация") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_5.svg "Подтверждение платежа") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_6.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_indonesia_7.svg "Возвращение к веб-сервису") Общие сценарии проведения оплат и выплат можно представить следующим образом. ![](images/pm/ru_banks_overview_pp.svg "Оплата через Payment Page") ![](images/pm/ru_banks_overview_gate_purchase.svg "Оплата через Gate") ![](images/pm/ru_banks_overview_gate_payout.svg "Выплата через Gate") Вместе с тем, к особенностям работы с методом Indonesian Online Banking можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат и выплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе [Оплаты через Payment Page](pm_indonesia.md) этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, [Поддержка со стороны банков](pm_indonesia.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Indonesian Online Banking. |Банк|ID|Оплаты|Выплаты| |----|--|------|-------| |Bank Artha Graha|2871|–|+| |Bank Bukopin|549|–|+| |Bank Central Asia|140|+|+| |Bank CIMB Niaga|507|–|+| |Bank Commonwealth|567|–|+| |Bank Danamon Indonesia|398|–|+| |Bank HSBC|513|–|+| |Bank Mandiri|143|+|+| |Bank Maspion|2891|–|+| |Bank MayBank Indonesia|565|–|+| |Bank Mega|547|–|+| |Bank Mestika|2901|–|+| |Bank Negara Indonesia|141|+|+| |Bank OCBC NISP|509|–|+| |Bank Panin|506|–|+| |Bank Permata|396|–|+| |Bank Rakyat Indonesia|142|+|+| |Bank Rakyat Indonesia Syariah|545|–|+| |Bank Sinar Mas|2911|–|+| |Bank Sumut|525|–|+| |Bank Tabungan Pensiunan Nasional /BTPN|544|–|+| |Bank UOB Buana Indonesia|508|–|+| |OCBC Indonesia|2921|–|+| Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечным точкам `/v2/info/banks/indonesia/sale/list` \(для оплат\) и `/v2/info/banks/indonesia/payout/list` \(для выплат\), которые относятся к группе конечных точек [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) Gate API.В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений. ```language-json { "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 15000, "currency": "IDR" } } ``` ```language-json [ { "id": 507, // Индентификатор банка "abbr": "CIMB", // Служебная аббревиатура банка, используемая в платформе "name": "BANK CIMB NIAGA", // Основное (международное) название банка "nativeName": "Bank CIMB Niaga", // Локальное (национальное или региональное) название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 982, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "IDR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "360", // Цифровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 2 // Число дробных разрядов валюты } ] }, { "id": 2901, "abbr": "BMTK", "name": "Bank Mestika", "nativeName": "Bank Mestika", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] }, { "id": 2871, "abbr": "BAG", "name": "Bank Artha Graha", "nativeName": "Bank Artha Graha", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] } ] ``` С вопросами о работе с банками, поддерживающими метод Indonesian Online Banking, можно обращаться к курирующему менеджеру Ecommpay. ## Оплаты через Payment Page {#ru_pm_indonesia_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_banks_indonesia_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод Indonesian Online Banking. 8. Запрос на проведение оплаты через выбранный банк поступает в платёжную платформу. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис банка. 10. В сервисе банка выполняется обработка запроса на оплату. 11. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису банка. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе банка выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе банка. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Indonesian Online Banking, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page \(подробнее [Формат запросов](pm_indonesia.md#section_p5j_fgl_ggb)\), при этом допустимы следующие варианты: - 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк \(этот вариант используется по умолчанию\); - 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков; - 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков; - 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков; - 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением. ![](images/universal/pm/splits/ru_asian_banking_pp_1_indonesia.svg "1 — Выбор метода и банка") ![](images/universal/pm/splits/ru_asian_banking_pp_2_indonesia.svg "2 — Выбор банка среди доступных методов") ![](images/universal/pm/splits/ru_asian_banking_pp_4_indonesia.svg "3 — Выбор среди доступных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_5_indonesia.svg "4 — Выбор среди заданных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_6_indonesia.svg "5 — Перенаправление к сервису заданного банка") Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Online Banking через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода Indonesian Online Banking необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — округлённая до целого числа сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Вариант выбора банка может определяться следующим образом: 1. *Через выбор в Payment Page метода и банка \(1\)* — как вариант по умолчанию, применяемый, если не указываются параметр `force_payment_method` и объект `payment_methods_options`, упоминаемые в подпунктах *2–5*. 2. *Через выбор в Payment Page банка среди доступных методов \(2\)* — для этого в объекте `payment_methods_options` необходимо указывать объект `online_indonesian_banks`, содержащий параметр `split_banks` со значением `true`: ```language-json "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true}}" ``` 3. *Через выбор в Payment Page банка из числа доступных \(3\)* — для этого в параметре `force_payment_method` необходимо указывать код предварительного выбора метода `online-indonesian-banks`. 4. *Через выбор в Payment Page банка из числа заданных \(4\)* — для этого необходимо указывать: - код `online-indonesian-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_indonesian_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификаторы целевых банков: ```language-json "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [2901, 2871]}}" ``` 5. *Через подтверждение в Payment Page перенаправления к сервису заданного банка \(5\)* — для этого необходимо указывать: - код `online-indonesian-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `online_indonesian_banks`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификатор целевого банка: ```language-json "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [2901]}}" ``` 3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 4. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор пользователя и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "IDR", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` Вместе с тем, в случае с выбором из заданных банков \(4\), запрос на открытие Payment Page может содержать расширенный набор данных. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000000, "payment_currency": "THB", "customer_id": "customer1", "force_payment_method": "online-indonesian-banks", "payment_methods_options": "{\"online_indonesian_banks\": {\"split_banks\": true, \"banks_id\": [140, 141]}}", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `200 000,00 IDR`. ```language-json { "project_id": 200, "payment": { "id": "154383173598055", "type": "purchase", "status": "success", "date": "2022-09-03T10:50:29+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-09-03T10:50:29+0000", "created_date": "2022-09-03T10:40:20+0000", "request_id": "72cb91e7586004", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "date": "2022-09-03T10:44:27+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OimEkwmMBi1OfYpFyBErmi0OVw34WpHt5CzEA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "154356886034811111", "type": "purchase", "status": "decline", "date": "2022-09-10T14:11:13+0000", "method": "Indonesian banks", "sum": { "amount": 1000, "currency": "IDR" }, "description": "154356886034811111" }, "operation": { "id": 9830000002095, "type": "sale", "status": "decline", "date": "2022-09-10T14:11:13+0000", "created_date": "2022-09-10T14:11:06+0000", "request_id": "3b14e5b0fd1", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 10, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "cQbMiD0pON9eJc5ZugNK0iRmVyHzNTmOX6Zg5w==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Быстрый старт](ru_pp_quickstart.md) и [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_indonesia_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису банка. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_banks_indonesia_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Indonesian Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис банка. 7. В сервисе банка выполняется обработка запроса на оплату. 8. От сервиса банка к платёжной платформе передаются данные для перенаправления пользователя к сервису банка. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису банка. 10. Пользователь перенаправляется к сервису банка. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе банка выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса банка к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на оплату с применением метода Indonesian Online Banking необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/indonesia/sale`. Эта конечная точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — округлённая до целого числа сумма платежа в дробных единицах валюты, со стороны мерчанта необходимо предупреждать пользователей об округлении; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `account` — объект, содержащий сведения о банковском счёте пользователя: - `bank_id` — идентификатор банка. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, а также идентификатор банка и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 140 } } ``` ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 20000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0", }, "account":{ "bank_id": 140 } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису Indonesian Online Banking при проведении каждого платежа с использованием метода Indonesian Online Banking необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `200 000,00 IDR`. ```language-json { "project_id": 200, "payment": { "id": "154383173598055", "type": "purchase", "status": "success", "date": "2022-09-03T10:50:29+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "1543831735980" }, "customer": { "id": "1" }, "operation": { "id": 15788000002076, "type": "sale", "status": "success", "date": "2022-09-03T10:50:29+0000", "created_date": "2022-09-03T10:40:20+0000", "request_id": "72cb91e7586004", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "date": "2022-09-03T10:44:27+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "Cug4rIB6OimEkwmMBi1OfYpapSpZri0OVw34WpHt5CzEA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "154356886034811111", "type": "purchase", "status": "decline", "date": "2022-09-10T14:11:13+0000", "method": "Indonesian banks", "sum": { "amount": 1000, "currency": "IDR" }, "description": "154356886034811111" }, "operation": { "id": 9830000002095, "type": "sale", "status": "decline", "date": "2022-09-10T14:11:13+0000", "created_date": "2022-09-10T14:11:06+0000", "request_id": "3b14e5b0fd1", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 10, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "", "auth_code": "" }, "code": "20101", "message": "Decline due to amount or frequency limit" }, "signature": "cQbMiD0pON9eJc5ZugNK0iTVyHzNTmOX6Zg5w==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Быстрый старт](ru_gate_quickstart.md) и [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Выплаты через Gate {#ru_pm_indonesia_gate_payout} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate с использованием метода Indonesian Online Banking со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения выплаты выглядит следующим образом. ![](images/pm/ru_banks_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату через Indonesian Online Banking. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее — в разделе [Формат ответа](ru_gate_interaction_organisation.md). 6. В платёжной платформе обеспечиваются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис Indonesian Online Banking. 7. В сервисе Indonesian Online Banking выполняется обработка выплаты. 8. От сервиса Indonesian Online Banking к платёжной платформе направляется информация о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. На стороне веб-сервиса обеспечивается информирование пользователя о результате выплаты. Информация о форматах запросов и оповещений, используемых для проведения выплат методом Indonesian Online Banking через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_osx_3jl_ggb .section} При формировании запросов на выплату с применением метода Indonesian Online Banking необходимо учитывать следующее: 1. Для инициирования каждой выплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/indonesia/payout`. Эта точка относится к группе [/v2/payment/banks/\{payment\_method\}/payout](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-payout). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — округлённая до целого числа сумма выплаты в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемой выплаты; - `account` — объект, содержащий сведения о банковском счёте пользователя: - `number` — номер счёта; - `customer_name` — имя держателя банковского счета; - `bank_id` — идентификатор банка. 3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на выплату с применением метода Indonesian Online Banking должен содержать идентификатор проекта, базовые сведения о платеже \(его идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, информацию о счёте и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 140, "customer_name": "Putra account", "number": "314159265358979" } } ``` ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvaRfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "id":"2990", "ip_address": "192.0.2.0" }, "account":{ "bank_id": 140, "customer_name": "Putra account", "number": "314159265358979" } } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат с применением метода Indonesian Online Banking используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена выплата в размере `200 000,00 IDR`. ```language-json { "project_id": 200, "payment": { "id": "PAYOUT7891022555", "type": "payout", "status": "success", "date": "2022-09-12T13:28:58+0000", "method": "Indonesian banks", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "payout" }, "account": { "number": "6419422222", "bank_id": 140, "region_id": 236 }, "customer": { "id": "1" }, "operation": { "id": 15112000002236, "type": "payout", "status": "success", "date": "2022-09-12T13:28:58+0000", "created_date": "2022-09-12T13:22:15+0000", "request_id": "b54610e94a76", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "E80NPPQ6Z1YSYPZTPH0NBON42", "date": "2022-09-12T13:28:34+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "qV2FRs/wxoOaywQS0GrpMkoW80mynkaQfSAUJpfQ==" } ``` В следующем примере оповещение свидетельствует об отклонённой выплате. ```language-json { "project_id": 200, "payment": { "id": "PAYOUT789", "type": "payout", "status": "decline", "date": "2022-09-07T09:44:43+0000", "method": "Indonesian banks", "sum": { "amount": 5000, "currency": "IDR" }, "description": "" }, "account": { "number": "6419422222", "bank_id": 140, "region_id": 236 }, "customer": { "id": "1" }, "errors": [ { "code": "3104", "message": "Payment Constraint Invalid Payout Amount", "description": "Gate. Operation was declined. Maximum payout limit is exceeded" } ], "operation": { "id": 533000002202, "type": "payout", "status": "decline", "date": "2022-09-07T09:44:43+0000", "created_date": "2022-09-07T09:44:43+0000", "request_id": "205d3536a91f474d62a602dd42fa7d248258224fe3f6", "sum_initial": { "amount": 5000, "currency": "IDR" }, "sum_converted": { "amount": 5000, "currency": "IDR" }, "provider": { "id": 1153, "payment_id": "" }, "code": "3104", "message": "Payment Constraint Invalid Payout Amount" }, "signature": "j4cxKDvx0EaDe4zKHot6v83rzDMlinxE915lAWGHKVjurpQ==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с выплатами через Gate также могут быть полезны следующие материалы: - [Быстрый старт](ru_gate_quickstart.md) и [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Выплата](ru_platform_payout_model.md)— о том, как проводить выплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Выплаты через Dashboard {#ru_pm_dash_payout} При использовании интерфейса Dashboard можно проводить *одиночные* и *массовые*выплатыметодом Indonesian Online Banking с единичной и пакетной отправкой запросов, называемые соответственно *одиночными* и *массовыми*. - Для проведения одиночной выплаты необходимо открыть форму выплаты, задать все необходимые параметры \(включая метод\), отправить запрос и убедиться в проведении выплаты. - Для проведения массовой выплаты необходимо подготовить и загрузить файл с информацией обо всех целевых выплатах, отправить пакет запросов и убедиться в проведении выплат. При этомдолжен использоваться файл формата CSV, структура которого соответствует требованиям, представленным в разделе [Сведения о массовых платежах](ru_dbl_payments.md), а параметры выплат— требованиям, представленным в разделе [Выплаты через Gate](pm_indonesia.md) этой статьи \(за исключением пункта о подписи\). Более подробная информация о проведении выплат через Dashboard представлена в [отдельной статье](ru_dbl_payments.md). ## Тестирование {#ru_pm_indonesia_testing} ### Общая информация {#section_ujs_5q4_zjb .section} Для метода Indonesian Online Banking доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate. Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности следует обращаться к специалистам технической поддержки Ecommpay. При тестировании платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и Indonesian Online Banking могут отличаться от рабочих. ### Статусы тестовых платежей {#section_vjs_5q4_zjb .section} При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах: - `decline` — при указании суммы `40000` или `40400`, - `success` — при указании любой другой суммы. При тестировании выплат их итоговые статусы определяются исходя из сумм, указанных в запросах: - `decline` — при указании суммы `40000` или `40400`, - `success` — при указании любой другой суммы. ### Оплаты через Payment Page {#section_syj_bt4_xjb .section} Для проведения тестовой оплаты через Payment Page необходимо: 1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page. 2. Если в запросе не был указан метод `online-indonesian-banks` — выбрать метод Indonesian Online Banking на странице эмулятора. 3. Если для выбора доступно несколько банков, то выбрать банк; если для выбора доступен только один банк, то щёлкнуть кнопку **Оплатить**. 4. Щёлкнуть кнопку **Success** или **Decline** \(в зависимости от запрашиваемой суммы\). 5. Принять итоговое оповещение с информацией о результате оплаты. Более подробная информация о проведении оплат с использованием метода Indonesian Online Banking через Payment Page представлена в разделе [Оплаты через Payment Page](pm_indonesia.md) этой статьи. ### Оплаты через Gate {#section_ul5_gt4_xjb .section} Для проведения тестовой оплаты через Gate необходимо: 1. Отправить в платёжную платформу корректный тестовый запрос на оплату \(с указанием идентификатора банка в параметре `bank_id`, идентификатор следует уточнять у службы технической поддержки Ecommpay\). 2. Принять промежуточное оповещение с данными для перенаправления. 3. Перейти по полученному URL и щёлкнуть кнопку **Success** или **Decline** \(в зависимости от запрашиваемой суммы\) — на странице эмулятора. 4. Принять итоговое оповещение с информацией о результате оплаты. Более подробная информация о проведении оплат с использованием метода Indonesian Online Banking через Gate представлена в разделе [Оплаты через Gate](pm_indonesia.md) этой статьи. ### Выплаты через Gate {#section_n22_lt4_xjb .section} Для проведения тестовой выплаты через Gate необходимо отправить в платёжную платформу корректный тестовый запрос и принять итоговое оповещение с информацией о результате. Более подробная информация о проведении выплат с использованием метода Indonesian Online Banking представлена в разделе [Выплаты через Gate](pm_indonesia.md) этой статьи. ## Анализ результатов проведения платежей {#ru_pm_indonesia_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Indonesian Online Banking, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Indonesian Virtual Accounts {#pm_indonesia_va} статья о работе с платёжным методом Indonesian Virtual Accounts, который позволяет проводить платежи в индонезийских рупиях с использованием наличных, банковских счетов и платёжных карт в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_indonesia_va_overview} статья о работе с платёжным методом Indonesian Virtual Accounts, который позволяет проводить платежи в индонезийских рупиях с использованием наличных, банковских счетов и платёжных карт в Индонезии и для которого в платформе Ecommpay поддерживаются оплаты ### Введение {#section_ql3_5fj_stb .section} |Indonesian Virtual Accounts — метод, позволяющий проводить платежи в индонезийских рупиях с использованием наличных, банковских счетов и платёжных карт в Индонезии. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты. Этот метод является самым популярным альтернативным методов в Индонезии. При использовании этого метода пользователь переводит средства на виртуальный банковский счёт с помощью банкомата, мобильного приложения или сайта банка. Виртуальный счёт, номер которого состоит из 16 цифр, создаётся для каждого пользователя при оплате и используется для дифференциации платежей. Ecommpay создаёт виртуальные счёта в межбанковской сети, каждый из которых уникален и используется только для одного платежа. Средства, полученные при помощи платежей, проведённых с использованием разных виртуальных счетов, объединяются на одном счёте мерчанта. При оплате пользователь использует предоставленную информацию для того чтобы совершить банковский перевод на виртуальный счёт, пока не истечёт срок действия этого счёта. Для перевода пользователь может использовать: - банкомат, - мобильное приложение банка, - сайт банка. Большая часть \(80 %\) платежей в Индонезии проводятся с использованием виртуальных счетов. Ecommpay предоставляет проведение платежей с использованием виртуальных счетов при участии крупных банков, работающих в Индонезии — Mandiri, Permata, Danamon, CIMB. В этой статье представлена информация о работе с методом Indonesian Virtual Accounts: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. |![](images/pm/indonesia_va_payment_instructions.png)| ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|- наличные - банковские счета - платёжные карты | |Регионы использования|[ID](references/ru/countries/ID.md)| |Валюты платежей|[IDR](references/ru/currencies/IDR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|–| |Опротестования|–| |Особенности|при работе с Payment Page поддерживаются разные варианты выбора банка, [подробнее](pm_indonesia_va.md#section_x34_f1c_tlb)| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay; дополнительную информацию можно получить в [Ecommpay shop](https://ecommpay.com/shop/payment-methods/virtual-accounts-indonesia/)| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода Indonesian Virtual Accounts задействуются веб-сервис мерчанта, один из интерфейсови платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_indonesiava_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода Indonesian Virtual Accounts могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, [IDR](references/ru/currencies/IDR.md)¹|Время²| |Минимум|Максимум|базовое|предельное| |--|----------------------------------------------|------| |-------|--------|-------|----------| |Оплаты|\*|\*|–|48 часов| **Прим.:** 1. Информацию об ограничениях сумм необходимо уточнять у курирующего менеджера Ecommpay. 2. Базовое и предельное время определяются следующим образом: - Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время определяется для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя. Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа \([подробнее](ru_Gate_payment_status_request.md)\). - Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус `decline`. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки Ecommpay. ### Сценарии использования {#section_fgt_sdl_ggb .section} Проведение оплат с использованием метода Indonesian Virtual Accounts осуществляется с перенаправлением пользователей к сервису провайдера. ![](images/pm/ru_indonesiava_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_indonesiava_interfaces_gate.svg "Оплата через Gate") Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах.При использовании дополнительных возможностей \(таких как платёжные ссылки\) сценарии выполнения операций методом Indonesian Virtual Accounts соответствуют специфике этих возможностей. Вместе с тем, к особенностям работы с методом Indonesian Virtual Accounts можно отнести то, что для каждого платежа с использованием этого метода должен быть выбран конкретный банк. При работе через Payment Page, как правило, выбор банка осуществляется пользователем уже в платёжной форме, но при вызовах Payment Page с предварительным выбором метода и банка, а также при инициировании оплат через Gate банк должен быть выбран на стороне веб-сервиса и в запросах должен указываться идентификатор этого банка. Возможные варианты выбора банка при работе через Payment Page описаны в разделе [Оплаты через Payment Page](pm_indonesia_va.md) этой статьи, а способы работы с идентификаторами банков — в следующем подразделе, [Поддержка со стороны банков](pm_indonesia_va.md#section_rqp_zdl_ggb). ### Поддержка со стороны банков {#section_rqp_zdl_ggb .section} В следующей таблице в ознакомительных целях приведены названия и идентификаторы банков, поддерживающих работу с методом Indonesian Virtual Accounts. |Банк|ID| |:---|::| |Bank Sahabat Sampoerna VA|4391| |Permata Virtual Account|433| |Mandiri Virtual Account|434| |Maybank Virtual Account|2831| |BNI Virtual Account|2931| |BRI Virtual Account|499| |Sinarmas Virtual Account|562| Поскольку со временем состав доступных банков может меняться, для получения актуальной информации рекомендуется использовать POST-запрос к конечной точке `/v2/info/banks/indonesia-va/sale/list`, которая относится к группе конечных точек [/v2/info/banks/\{payment\_method\}/\{operationType\}/list](https://api-developers.ecommpay.com/api-specification/requests-for-information/post-v2-info-banks-payment-method-operation-type-list) Gate API.В этом запросе должны указываться идентификатор проекта, идентификатор, валюта и сумма платежа и подпись к этим данным; при этом рекомендуется передавать реальные данные о платеже, но допускается и указание произвольных значений. ```language-json { "general": { "project_id": 200, "payment_id": "ORDER_155860015", "signature": "K6jllym+PtObocZtr345st...==" }, "payment": { "amount": 1000000, "currency": "IDR" } } ``` ```language-json [ { "id": 433, // Индентификатор банка "abbr": "PMBVA", // Служебная аббревиатура банка, используемая в платформе "name": "Permata VA", // Основное (международное) название банка "nativeName": "Permata VA", // Локальное (национальное или региональное) название банка "currencies": [ // Массив с информацией о валютах, поддерживаемых банком { "id": 982, // Идентификатор валюты в платёжной платформе "alpha_3_4217": "IDR", // Буквенный код валюты платежа в формате ISO-4217 alpha-3 "number_3_4217": "360", // Цифровой код валюты платежа в формате ISO-4217 alpha-3 "exponent": 2 // Число дробных разрядов валюты } ] }, { "id": 434, "abbr": "MDRIVA", "name": "Mandiri VA", "nativeName": "Mandiri VA", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] }, { "id": 2931, "abbr": "BNIVA", "name": "BNI Virtual Account", "nativeName": "BNI VA", "currencies": [ { "id": 982, "alpha_3_4217": "IDR", "number_3_4217": "360", "exponent": 2 } ] } ] ``` С вопросами о работе с банками, поддерживающими метод Indonesian Virtual Accounts, можно обращаться к курирующему менеджеру Ecommpay. ## Оплаты через Payment Page {#ru_pm_indonesia_va_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода Indonesian Virtual Accounts со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате. При этом можно использовать различные варианты выбора метода и банка, указывая соответствующие параметры в запросах.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_indonesiava_uml_pp.svg "Проведение оплаты через Payment Page") 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает один из банков, поддерживающих работу с платёжным методом Indonesian Virtual Accounts. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода Indonesian Virtual Accounts. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. На стороне провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется на сайт провайдера, где ему отображается 16-значный код для оплаты и платёжная инструкция. 14. Согласно инструкции, пользователь вводит код на сайте банка либо с использованием банкомата или мобильного приложения банка, и подтверждает оплату. 15. В сервисе провайдера выполняется обработка платежа. 16. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 17. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 18. От платёжной платформы к Payment Page направляется информация о результате оплаты. 19. Информация о результате оплаты отображается пользователю на Payment Page. Как правило, после того как пользователь на стороне веб-сервиса подтверждает готовность перейти к оплате, он перенаправляется к Payment Page, выбирает платёжный метод и, в случае работы с методом Indonesian Virtual Accounts, дополнительно выбирает один из доступных банков. Вместе с тем, в некоторых ситуациях могут быть актуальны другие варианты выбора платёжного метода и банка. Например, при открытии Payment Page можно сразу перенаправлять пользователя к выбору банка либо ограничивать список поддерживаемых банков для отдельного платежа и отображать пользователю только кнопки выбора целевых банков. Конкретный вариант выбора платёжного метода и банка определяется через параметры, указанные в запросе на открытие Payment Page \(подробнее [далее](pm_indonesia_va.md#section_x34_f1c_tlb)\), при этом допустимы следующие варианты: - 1 — при открытии платёжной формы в ней последовательно отображаются отдельные страницы для выбора метода и банка, и пользователь выбирает сначала метод, а затем банк \(этот вариант используется по умолчанию\); - 2 — при открытии платёжной формы в ней отображается страница с кнопками выбора методов и банков для данного метода, и пользователь выбирает один из этих банков; - 3 — при открытии платёжной формы в ней отображается страница с кнопками выбора всех доступных банков для данного метода, и пользователь выбирает один из этих банков; - 4 — при открытии платёжной формы в ней отображается страница с кнопками выбора заданных банков для данного метода, и пользователь выбирает один из этих банков; - 5 — при открытии платёжной формы в ней отображается страница подтверждения перенаправления к сервису заданного банка, и пользователь соглашается с этим перенаправлением. ![](images/universal/pm/splits/ru_asian_banking_pp_1_indonesia_va.svg "1 — Выбор метода и банка") ![](images/universal/pm/splits/ru_asian_banking_pp_2_indonesia_va.svg "2 — Выбор банка среди доступных методов") ![](images/universal/pm/splits/ru_asian_banking_pp_4_indonesia_va.svg "3 — Выбор среди доступных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_5_indonesia_va.svg "4 — Выбор среди заданных банков") ![](images/universal/pm/splits/ru_asian_banking_pp_6_indonesia_va.svg "5 — Перенаправление к сервису заданного банка") Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Virtual Accounts через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md). ### Формат запросов {#section_x34_f1c_tlb .section} При формировании запросов на открытие платёжной формы с применением метода Indonesian Virtual Accounts необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции. - `payment_id` — идентификатор платежа, уникальный в рамках проекта. - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3. - `payment_amount` — сумма платежа в дробных единицах валюты. В запросах на оплаты с указанием валюты [IDR](references/ru/currencies/IDR.md) необходимо округлять суммы до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне Ecommpay в эквивалентную сумму в валюте [IDR](references/ru/currencies/IDR.md) и также округляется до целых чисел. При этом округление выполняется в б*о*льшую сторону \(например, если в результате конвертации получается сумма 200 000,05 [IDR](references/ru/currencies/IDR.md), то такая сумма округляется до 200 001,00 [IDR](references/ru/currencies/IDR.md)\). - `customer_id` — идентификатор пользователя в рамках проекта. 2. Вариант выбора банка может определяться следующим образом: 1. *Через выбор в Payment Page метода и банка \(1\)* — как вариант по умолчанию, применяемый, если не указываются параметр `force_payment_method` и объект `payment_methods_options`, упоминаемые в подпунктах *2–5*. 2. *Через выбор в Payment Page банка среди доступных методов \(2\)* — для этого в объекте `payment_methods_options` необходимо указывать объект `indonesia_va`, содержащий параметр `split_banks` со значением `true`: ```language-json "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true}}" ``` 3. *Через выбор в Payment Page банка из числа доступных \(3\)* — для этого в параметре `force_payment_method` необходимо указывать код предварительного выбора метода `online-indonesian-banks`. 4. *Через выбор в Payment Page банка из числа заданных \(4\)* — для этого необходимо указывать: - код `online-indonesian-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `indonesia_va`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификаторы целевых банков: ```language-json "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831, 2931]}}" ``` 5. *Через подтверждение в Payment Page перенаправления к сервису заданного банка \(5\)* — для этого необходимо указывать: - код `online-indonesian-banks` в параметре `force_payment_method`; - объект `payment_methods_options` с объектом `indonesia_va`, который должен содержать параметр `split_banks` со значением `true` и объект `banks_id` с массивом, включающим в себя идентификатор целевого банка: ```language-json "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831]}}" ``` 3. Дополнительно может потребоваться указывать имя и фамилию пользователя в параметрах `customer_first_name` и `customer_last_name`. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page \([подробнее](ru_PP_Parameters.md)\). 5. После указания всех целевых параметров необходимо составлять подпись \([подробнее](ru_platform_signature.md)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода Indonesian Virtual Accounts должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "John", "customer_first_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "John", "customer_first_name": "Doe", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` Вместе с тем, в случае с выбором из заданных банков \(4\), запрос на открытие Payment Page может содержать расширенный набор данных. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 1000, "payment_currency": "IDR", "customer_id": "customer1", "customer_first_name": "John", "customer_first_name": "Doe", "force_payment_method": "online-indonesian-banks", "payment_methods_options": "{\"indonesia_va\": {\"split_banks\": true, \"banks_id\": [2831, 2931]}}", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Indonesian Virtual Accounts используется типовой формат, описание которого представлено в статье [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `200 000,00 IDR`. ```language-json { "project_id": 200, "payment": { "id": "9770802", "type": "purchase", "status": "success", "date": "2020-02-22T22:44:46+0000", "method": "indonesia-va", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "test" }, "account": { "number": "8856113600001045" }, "customer": { "id": "1" }, "operation": { "id": 52084000029401, "type": "sale", "status": "success", "date": "2020-02-22T22:44:46+0000", "created_date": "2020-02-22T17:30:42+0000", "request_id": "59b48b4c2d0a2b6a-00052085", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "code": "0", "message": "Success", "provider": { "id": 1164, "payment_id": "644206", "auth_code": "", "date": "2020-02-22T22:44:45+0000" } }, "signature": "Hekd6+86S592dHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "9770802", "type": "purchase", "status": "decline", "date": "2020-02-22T22:44:46+0000", "method": "indonesia-va", "sum": { "amount": 1000, "currency": "IDR" }, "description": "test" }, "account": { "number": "8856113600001046" }, "customer": { "id": "1" }, "operation": { "id": 52084000029401, "type": "sale", "status": "decline", "date": "2020-02-22T22:44:46+0000", "created_date": "2020-02-22T17:30:42+0000", "request_id": "59b48b4c2d0a2b6a-00052085", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 1000, "currency": "IDR" }, "code": "20101", "message": "Decline due to amount or frequency limit", }, "signature": "Hekd6+86S592dGuYCHADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_indonesia_va_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода Indonesian Virtual Accounts со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису Indonesian Virtual Accounts. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_indonesiava_uml_gate.svg "Проведение оплаты через Gate") 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода Indonesian Virtual Accounts. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера, где ему отображается 16-значный код для оплаты и платёжная инструкция. 11. Согласно инструкции, пользователь вводит код на сайте банка либо с использованием банкомата или мобильного приложения банка, и подтверждает оплату. 12. В сервисе провайдера выполняется обработка платежа. 13. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 14. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 15. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом Indonesian Virtual Accounts через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md). ### Формат запросов {#section_kwt_dkc_tlb .section} При работе с запросами на оплаты с применением метода Indonesian Virtual Accounts необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/banks/indonesia-va/sale`. Эта конечная точка относится к группе [/v2/payment/banks/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/banks/post-v2-payment-banks-payment-method-sale). 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции. - `payment_id` — идентификатор платежа, уникальный в рамках проекта. - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md)\). - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты. В запросах на оплаты с указанием валюты [IDR](references/ru/currencies/IDR.md) необходимо округлять суммы до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне Ecommpay в эквивалентную сумму в валюте [IDR](references/ru/currencies/IDR.md) и также округляется до целых чисел. При этом округление выполняется в б*о*льшую сторону \(например, если в результате конвертации получается сумма 200 000,05 [IDR](references/ru/currencies/IDR.md), то такая сумма округляется до 200 001,00 [IDR](references/ru/currencies/IDR.md)\). - `currency` — код валюты платежав формате ISO-4217 alpha-3. - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта. - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа. - `account` — объект, содержащий сведения о банковском счёте пользователя: - `bank_id` — идентификатор банка. 3. Дополнительно может потребоваться указывать следующие объекты и параметры: - `customer` — объект, содержащий сведения о пользователе: - `first_name` — имя пользователя, - `last_name` — фамилия пользователя; - `return_url` — объект, содержащий URL для перенаправления пользователя в веб-сервис: - `return` — URL для перенаправления пользователя на любом шаге оплаты. Необходимость использования этих параметров следует уточнять у курирующего менеджера Ecommpay. 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода Indonesian Virtual Accounts должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), информацию о пользователе, URL для перенаправления, а также идентификатор банка и подпись. ```language-json { "general": { "project_id": 2990, "payment_id": payment_id, "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 35000000, "currency": "IDR" }, "customer": { "id": "12345", "ip_address": "192.0.2.0" "first_name": "John", "last_name": "Doe" }, "account":{ "bank_id": 2961 }, "return_url": { "return": "https://example.com/return" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_vjp_454_kxb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису Indonesian Virtual Accounts при проведении каждого платежа с использованием метода Indonesian Virtual Accounts необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": {}, "method": "GET", "url": "https://www.example.com/pay" } ``` ### Формат итоговых оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода Indonesian Virtual Accounts используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md). В следующем примере оповещение свидетельствует о том, что в рамках проекта `200` была проведена оплата в размере `200 000,00 IDR`. ```language-json { "project_id": 200, "payment": { "id": "9770802", "type": "purchase", "status": "success", "date": "2020-02-22T22:44:46+0000", "method": "indonesia-va", "sum": { "amount": 20000000, "currency": "IDR" }, "description": "test" }, "account": { "number": "8856113600001045" }, "customer": { "id": "1" }, "operation": { "id": 52084000029401, "type": "sale", "status": "success", "date": "2020-02-22T22:44:46+0000", "created_date": "2020-02-22T17:30:42+0000", "request_id": "59b48b4c2d0a2b6a-00052085", "sum_initial": { "amount": 20000000, "currency": "IDR" }, "sum_converted": { "amount": 20000000, "currency": "IDR" }, "code": "0", "message": "Success", "provider": { "id": 1164, "payment_id": "644206", "auth_code": "", "date": "2020-02-22T22:44:45+0000" } }, "signature": "Hekd6+86S592dGuYNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "project_id": 200, "payment": { "id": "9770802", "type": "purchase", "status": "decline", "date": "2020-02-22T22:44:46+0000", "method": "indonesia-va", "sum": { "amount": 1000, "currency": "IDR" }, "description": "test" }, "account": { "number": "8856113600001046" }, "customer": { "id": "1" }, "operation": { "id": 52084000029401, "type": "sale", "status": "decline", "date": "2020-02-22T22:44:46+0000", "created_date": "2020-02-22T17:30:42+0000", "request_id": "59b48b4c2d0a2b6a-00052085", "sum_initial": { "amount": 1000, "currency": "IDR" }, "sum_converted": { "amount": 1000, "currency": "IDR" }, "code": "20101", "message": "Decline due to amount or frequency limit", }, "signature": "Hekd6+86S592dADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_indonesia_va_dash_analysis} Для анализа информации о платежах и операциях, как в отдельности по методу Indonesian Virtual Accounts, так и в совокупности с другими методами, можно использовать: - инструментарийинтерфейса Dashboard, с различными реестрами и аналитическими панелями; - отчёты в формате CSV, выгружаемые\(как разово, так и периодически\) черезраздел **Отчёты** интерфейса Dashboard; - данные в формате JSON, получаемыепо программным запросам черезинтерфейс Data API. С вопросами по анализу информации можно обращаться к разделам документации \([Dashboard](ru_dbl_about.md) и [Использование Data API](ru_dbl_api_protocol.md)\) и специалистам Ecommpay. --- # Malaysian Online Banking {#pm_malaysia} статья о работе с платёжным методом Malaysian Online Banking, который позволяет проводить платежи в малайзийских ринггитах с использованием банковских счетов в Малайзии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты **На уровень выше:**[Банковские платежи](ru_pm_bankpayments.md) ## Обзор {#ru_pm_malaysia_overview} статья о работе с платёжным методом Malaysian Online Banking, который позволяет проводить платежи в малайзийских ринггитах с использованием банковских счетов в Малайзии и для которого в платформе Ecommpay поддерживаются оплаты и выплаты ### Введение {#section_ql3_5fj_stb .section} Malaysian Online Banking — метод, позволяющий проводить платежи в малайзийских ринггитах с использованием банковских счетов в Малайзии. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты и выплаты. В этой статье представлена информация о работе с методом Malaysian Online Banking: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|банковские платежи| |Платёжные инструменты|банковские счета| |Регионы использования|[MY](references/ru/countries/MY.md)| |Валюты платежей|[MYR](references/ru/currencies/MYR.md)| |Конвертация валют|на стороне Ecommpay| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|+| |Опротестования|–| |Особенности|- при работе с Payment Page поддерживаются разные варианты выбора банка, [подробнее](pm_malaysia.md#section_p5j_fgl_ggb) - в браузере Safari может не поддерживаться перенаправление на сервис банка. Подробности необходимо уточнять у курирующего менеджера Ecommpay | |Организация и стоимость подключения|по согласованию с курирующим менедж