# Платформа {#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_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_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_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 --- # Интеграция с использованием 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 для интеграции Payment Page с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе Android - **[SDK UI & Core для iOS](ru_sdk_ui_and_core_ios.md#)** статья о порядке применения SDK UI & Core для интеграции Payment Page с пользовательским интерфейсом от Ecommpay в мобильные приложения на платформе iOS - **[SDK Flutter для Android и iOS](ru_sdk_flutter.md#)** статья о порядке применения SDK Flutter для интеграции Payment Page в мобильные приложения на платформах Android и iOS - **[SDK React Native для Android и iOS](ru_sdk_react_native.md#)** статья о порядке применения SDK React Native для интеграции Payment Page в мобильные приложения на платформах Android и iOS - **[SDK Core для Android](ru_sdk_core_android.md#)** статья о порядке применения SDK Core для интеграции Payment Page с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе Android - **[SDK Core для iOS](ru_sdk_core_ios.md#)** статья о порядке применения SDK Core для интеграции Payment Page с возможностью использования собственного пользовательского интерфейса в мобильные приложения на платформе 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 для 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) --- # Встраивание облегчённой редакции 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) --- # Управление формой {#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) --- # Способы перенаправления пользователей к сторонним сервисам {#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_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) --- # Проверка 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_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_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_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) --- # Спецификация 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_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__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_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_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_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) --- # Дополнение информации о платеже {#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_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) --- # Проведение оплат 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) --- # Погашение задолженностей {#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_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) --- # 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 с описанием моделей и структур данных для формирования запросов к различным конечным точкам --- # Использование 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) --- # 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#)** - **[Visa Instalments](pm_instalments.md#)** **На уровень выше:**[Платёжные методы](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) --- # Банковские платежи {#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#) - [Singapore Online Banking](pm_singapore.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#)** - **[Banks of Hong Kong](pm_hk_banks.md#)** - **[Banks of the Philippines](pm_philippines.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 Online Banking](pm_indonesia.md#)** - **[Indonesian Virtual Accounts](pm_indonesia_va.md#)** - **[Malaysian Online Banking](pm_malaysia.md#)** - **[Mexico Online Banking](pm_mexico_ob.md#)** - **[Multibanсo](pm_multibanco.md#)** - **[MyBank](pm_mybank.md#)** - **[Open Banking \(группа методов\)](pm_openbanking.md#)** - **[Open Banking in Austria](pm_austria.md#)** - **[Open Banking in Belgium](pm_belgium.md#)** - **[Open Banking in Denmark](pm_denmark.md#)** - **[Open Banking in Estonia](pm_estonia.md#)** - **[Open Banking in Finland](pm_finland.md#)** - **[Open Banking in France](pm_france.md#)** - **[Open Banking in Germany](pm_germany.md#)** - **[Open Banking in Hungary](pm_hungary.md#)** - **[Open Banking in Italy](pm_italy.md#)** - **[Open Banking in Ireland](pm_ireland.md#)** - **[Open Banking in Latvia](pm_latvia.md#)** - **[Open Banking in Lithuania](pm_lithuania.md#)** - **[Open Banking in Luxembourg](pm_luxembourg.md#)** - **[Open Banking in the Netherlands](pm_netherlands.md#)** - **[Open Banking in Norway](pm_norway.md#)** - **[Open Banking in Poland](pm_poland.md#)** - **[Open Banking in Portugal](pm_portugal.md#)** - **[Open Banking in Romania](pm_romania.md#)** - **[Open Banking in Spain](pm_spain.md#)** - **[Open Banking in Sweden](pm_sweden.md#)** - **[Open Banking in the UK](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#)** - **[Thai Online Banking](pm_thailand.md#)** - **[Vietnamese Online Banking](pm_vietnam.md#)** - **[«Выплаты на банковские счета в ЕЗПЕ \(SEPA\)»](pm_bankpayout_sepa.md#)** - **[«Локальные выплаты на банковские счета в Великобритании»](pm_bankpayout_uk.md#)** **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # Платежи с использованием электронных кошельков {#ru_pm_ewallet} статьи о платёжных методах группы платежей с использованием электронных кошельков, в которых для переводов средств со стороны пользователей задействуются электронные кошельки соответствующих операторов *Платежи с использованием электронных кошельков* — это платежи, в рамках которых со стороны пользователя задействуется электронный кошелёк, предоставляемый соответствующим оператором. При этом в качестве платёжного инструмента может выступать непосредственно электронный кошелёк\(например, в таких методах, как PayPal иNeteller\) или платёжная карта пользователя\(например, в таких методах, как Apple Pay иGoogle Pay\), а пользовательские сценарии могут широко варьироваться с учётом специфики разных кошельков. К таким платёжным методам относятся: - [Alipay](pm_alipay.md#) - [Apple Pay](pm_applepay.md#) - [AstroPay](pm_astropay.md#) - [Bancomat Pay](pm_bancomatpay.md#) - [Boost Wallet](pm_boost.md#) - [Coins.ph](pm_coinsph.md#) - [DOKU Wallet](pm_doku.md#) - [GCash](pm_gcash.md#) - [Google Pay](pm_googlepay.md#) - [GrabPay](pm_grabpay.md#) - [Maya](pm_maya.md#) - [MBWay](pm_mbway.md#) - [MoMo Wallet](pm_momoqr.md#) - [Neteller](pm_neteller.md#) - [OVO Wallet](pm_ovo.md#) - [PayPal](pm_paypal.md#) - [PayPal Pay Later](pm_paypal_pay_later.md#) - [Satispay](pm_satispay.md#) - [Shopee](pm_shopee.md#) - [Skrill Wallet](pm_skrill.md#) - [Touch&Go](pm_touchngo.md#) - [TWINT](pm_twint.md#) - [WeChat](pm_wechat.md#) - **[Alipay](pm_alipay.md#)** - **[Apple Pay](pm_applepay.md#)** - **[AstroPay](pm_astropay.md#)** - **[Bancomat Pay](pm_bancomatpay.md#)** - **[Boost Wallet](pm_boost.md#)** - **[Coins.ph](pm_coinsph.md#)** - **[DOKU Wallet](pm_doku.md#)** - **[GCash](pm_gcash.md#)** - **[Google Pay](pm_googlepay.md#)** - **[GrabPay](pm_grabpay.md#)** - **[Maya](pm_maya.md#)** - **[MBWay](pm_mbway.md#)** - **[MoMo Wallet](pm_momoqr.md#)** - **[Neteller](pm_neteller.md#)** - **[OVO Wallet](pm_ovo.md#)** - **[PayPal](pm_paypal.md#)** - **[PayPal Pay Later](pm_paypal_pay_later.md#)** - **[Satispay](pm_satispay.md#)** - **[Shopee](pm_shopee.md#)** - **[Skrill Wallet](pm_skrill.md#)** - **[Touch&Go](pm_touchngo.md#)** - **[TWINT](pm_twint.md#)** - **[WeChat](pm_wechat.md#)** **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # Платежи с помощью QR-кодов {#ru_pm_qr} статьи о платёжных методах группы платежей с помощью QR-кодов, в которых для переводов средств со стороны пользователей необходимо сканировать специализированные QR-коды *Платежи с помощью QR-кодов* — это платежи, для проведения которых пользователю каждый разнеобходимо сканировать специализированный QR-коди в некоторых случаях выполнять определённые действия после этого. В качестве платёжного инструмента при этом может использоваться банковский счёт или электронный кошелёк. К таким платёжным методам относятся: - [Hong Kong FPS QR](pm_hk_qr.md#) - [Promptpay](pm_promptpay.md#) - [QRIS](pm_qris.md#) - [QR Ph](pm_qrph.md#) - [TrueMoney](pm_truemoney.md#) - **[Hong Kong FPS QR](pm_hk_qr.md#)** - **[Promptpay](pm_promptpay.md#)** - **[QRIS](pm_qris.md#)** - **[QR Ph](pm_qrph.md#)** - **[TrueMoney](pm_truemoney.md#)** **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # Возможности тестирования {#ru_pm_testing} статья с информацией о возможностях тестирования разных типов платежей и операций для различных платёжных методов При подключении платёжных методов одним из насущных вопросов является тестирование, как пользовательских сценариев, так и корректности технической интеграции. Чтобы облегчить эти процессы, в платёжной платформе Ecommpay поддерживается и постоянно развивается работа с эмуляторами различных платёжных систем и платёжных операций.На сегодня с помощью эмуляторов можно тестировать следующие платежи и операции: |Метод|Оплаты|Возвраты|Выплаты| |-----|:----:|:------:|:-----:| |[Alipay](pm_alipay.md#)|+|+|–| |[Apple Pay](pm_applepay.md#)|+|–|–| |[Indonesian Online Banking](pm_indonesia.md#)|+|–|+| |[Vietnamese Online Banking](pm_vietnam.md#)|+|–|+| |[Malaysian Online Banking](pm_malaysia.md#)|+|–|+| |[Thai Online Banking](pm_thailand.md#)|+|–|+| |[DOKU Wallet](pm_doku.md#)|+|–|+| |[Google Pay](pm_googlepay.md#)|+|–|–| |[Neteller](pm_neteller.md#)|+|–|+| |[Skrill Wallet](pm_skrill.md#)|+|+|+| Информацию о тестировании указанных платежей и операций можно найти в описании соответствующих методов, информация о тестировании платежей с прямым использованием платёжных карт представлена в справочнике [Номера тестовых карт](ru_test_cards.md). С дополнительными вопросами о тестировании как указанных, так и иных платежей и операций можно обращаться к специалистам технической поддержки Ecommpay. **На уровень выше:**[Платёжные методы](ru_pm_about.md) --- # B2B-выплаты {#ru_b2bremit_about} раздел с материалами о проведении выплат на счета юридических лиц компаний-партнёров для расчётов с поставщиками услуг и другими организациями В этом разделе представлена информация о проведении выплат на счета юридических лиц компаний-партнёров— для расчётов с поставщиками услуг и другими организациями, что может быть удобным для выстраивания комплексной работы с платежами. - [Общая информация](ru_b2bremit_overview.md#)— о назначении и порядке работы с выплатами партнёрам. - [Работа через Dashboard](ru_b2bremit_db.md)— о работе с карточками партнёров и выплатами партнёрам через пользовательский интерфейс Dashboard. - [Работа через Gate API](ru_b2bremit_api.md)— о работе с карточками партнёров и выплатами партнёрам через программный интерфейс Gate API. - **[Общая информация](ru_b2bremit_overview.md#)** статья с вводной информацией о b2b-выплатах и описанием общего порядка работы с карточками партнёров и выплатами партнёрам - **[Работа через Dashboard](ru_b2bremit_db.md)** статья о порядке работы с карточками партнёров и выплатами партнёрам через интерфейс Dashboard - **[Работа через Gate API](ru_b2bremit_api.md)** статья о порядке работы с карточками партнёров и выплатами партнёрам через интерфейс Gate API - **[B2B API](b2b_api.md)** спецификация B2B API с описанием моделей и структур данных для формирования запросов к различным конечным точкам --- # Работа через Dashboard {#ru_b2bremit_db} статья о порядке работы с карточками партнёров и выплатами партнёрам через интерфейс Dashboard ## Общая информация {#section_mlx_1dy_dtb .section} Dashboard позволяет создавать карточки партнёров и управлять ими, создавать заявки на одиночные и массовые выплаты партнёрам и отслеживать информацию о проводимых и уже проведённых выплатах. При этом должны соблюдаться следующие условия: - Для создания поручений на выплаты, а также отправки карточек партнёров на согласование через Dashboard должна применяться двухфакторная аутентификация при доступе к интерфейсу. - У используемой учётной записи должны быть права на выполнение необходимых действий. Полный набор прав для работы с функциональностью выплат партнёрам доступен для ролей Operations и Merchant Admin.Для ролей Finance и Support доступно только право просматривать информацию в разделе **Расчёты с партнёрами**. С информацией о порядке доступа к этому разделу в интерфейсе Dashboard можно ознакомиться в статье [Основные возможности и ролевая модель](ru_dbl_roles_overview.md#). В разделе **Расчёты с партнёрами** информация о всех созданных карточках партнёров отображается в реестре **Карточки получателя**, а информация о проводимых и уже проведённых выплатах партнёрам — в реестре **Все расчёты с партнёрами**, а также в карточках с детальной информацией о платежах. Проведение группы выплат можно отслеживать в реестре **Массовые запросы на расчёты с партнёрами**. ## Создание и редактирование карточки партнёра {#section_jf1_d2y_dtb .section} Чтобы создать карточку, следует: 1. Открыть панель **Новая карточка получателя**. Для этого необходимо щёлкнуть кнопку **Создать карточку получателя** в реестре карточек. 2. Задать информацию о партнёре-получателе платежей. Для этого необходимо заполнить поля в следующих вкладках **Основная информация**, **Получатель**, **Адрес компании** и **Информация о переводах**. При заполнении полей стоит учитывать ряд особенностей: - За исключением трёх необязательных полей \(адрес и страна банка получателя, а также почтовый индекс\), все остальные поля должны быть заполнены. - Если какое-либо из обязательных полей оставлено пустым или заполнено некорректно, сохранить черновик карточки или отправить её на рассмотрение не удастся. При щелчке кнопки **Сохранить как черновик** соответствующие поля выделяются красным цветом с подсказкой, какая информация ожидается в каждом из незаполненных полей, а кнопка **Отправить на рассмотрение** при этом не активна. Помимо этого, вкладки, в которых не хватает информации, отмечаются значком ![](images/universal/dbl/icon_error_field.svg), а корректно заполненные вкладки — значком ![](images/universal/dbl/icon_complete.svg). - Если сохранить карточку как черновик, к её заполнению можно вернуться позже. Черновик доступен для редактирования в течение 30 дней. При необходимости карточку со статусом **Draft** можно удалить, используя кнопку ![](images/universal/dbl/icon_trashbin.svg) в соответствующей строке реестра карточек. 3. Отправить карточку на рассмотрение в Ecommpay. Кнопка **Отправить на рассмотрение** активна, если все обязательные поля заполнены корректно. После отправки на рассмотрение карточка обозначается статусом **Created** в реестре и внести изменения в неё уже невозможно. ![](images/ecommpay/dbl/ru_dbl_newaccount_generalinfo.svg "Панель создания карточки") ![](images/ecommpay/dbl/ru_dbl_newaccount_incomplete.svg "Пример неполного заполнения полей") ![](images/ecommpay/dbl/ru_dbl_newaccount_saveasdraft.svg "Сохранение черновика") ![](images/ecommpay/dbl/ru_dbl_newaccount_sendforapproval.svg "Отправка карточки на согласование") ## Удаление карточки партнёра {#section_nd1_mfy_dtb .section} Чтобы удалить карточку, следует: 1. При необходимости найти карточку, которую требуется удалить. Для этого следует перейти в реестр карточек и воспользоваться фильтрами. 2. Выбрать действие удаления карточки, используя кнопку ![](images/universal/dbl/icon_trashbin.svg) в соответствующей строке реестра. Важно помнить, что удалить карточку со статусом **Created** невозможно, поэтому кнопка удаления для такой карточки в строке реестра не активна. 3. Подтвердить удаление в появившемся модальном окне. ## Создание платёжного поручения на одиночную выплату {#section_zsr_wfy_dtb .section} Чтобы создать заявку на одиночную выплату юридическому лицу в рамках проведения расчётов с партнёрами, следует: 1. Открыть панель отправки запроса на одиночную выплату. Для этого необходимо открыть раздел **Расчёты с партнёрами**, щёлкнуть кнопку**Создать перевод** в левой части панели фильтрации и перейти на вкладку **Одиночный перевод** в открывшемся окне. 2. Задать параметры заявки на выплату и отправить запрос. Для этого необходимо заполнить поля и щёлкнуть кнопку **Отправить запрос**. В отдельных случаях подтвердить отправку запроса, введя в появившемся окне код из SMS-сообщения. При заполнении полей стоит учитывать ряд особенностей: - При выборе идентификатора карточки партнёра в выпадающем списке показаны карточки, которым присвоен статус **Active**. Заявку на выплату можно создать только для получателей, карточки которых были одобрены и срок действия которых не истёк. - Поле **Валюта** недоступно для редактирования, так как значение в этом поле соответствует значению, указанному в карточке. - Поле **Описание перевода** не является обязательным. - Кнопка **Отправить запрос** становится активной, когда корректно указаны обязательные параметры. ![](images/ecommpay/dbl/ru_dbl_sendremit_request.svg "Пример заполнения заявки на выплату с активной кнопкой отправки запроса") 3. Убедиться, что выплата проведена. Для этого можно проверить статус этой выплаты в реестре **Все расчёты с партнёрами** — он должен принять значение `success`. ## Создание платёжного поручения на массовые выплаты {#section_zrg_lh1_v5b .section} Чтобы создать заявку на проведение группы выплат с отправкой запросов одним пакетом, следует: 1. Подготовить файл заданного формата с информацией о целевых выплатах. Необходимо помнить, что заявку на выплаты можно создать только для получателей, карточки которых были одобрены и срок действия которых не истёк, поэтому при указании идентификаторов карточек следует обращать внимание на их статус — им должен быть присвоен статус **Active**. Шаблон файла доступен для скачивания в интерфейсе Dashboard, a с информацией об основных требованиях к таким файлам можно ознакомиться в статье [Сведения о массовых платежах](ru_dbl_payments.md#). 2. Перейти на вкладку **Массовые переводы** панели отправки запросов на выплаты. Для этого необходимо открыть раздел **Расчёты с партнерами**, щёлкнуть кнопку**Создать перевод** в левой части панели фильтрации и перейти на соответствующую вкладку в панели **Новый перевод**. 3. Загрузить подготовленный файл со списком выплат и отправить пакет запросов на выполнение. Для загрузки можно перетащить файл в область загрузки или использовать ссылку **Выберите файл для загрузки**. После загрузки файла необходимо убедиться в том, что кнопка **Отправить запрос** стала активной, щёлкнуть её и в отдельных случаях подтвердить отправку, введя в появившемся окне код из SMS-сообщения. ![](images/ecommpay/dbl/ru_dbl_mass_remittances.svg) Если файл некорректен, кнопка **Отправить запрос** не становится активной и отображается сообщение об ошибках. В такой ситуации можно изучить информацию о них \(используя переключатель для предварительного просмотра и далее кнопку **Информация о файле**\), скорректировать файл и загрузить его повторно. 4. Убедиться в выполнении запросов. При отправке запросов в интерфейсе отображается сообщение об их приёме, после чего важно убедиться в проведении выплат, проверив статус пакета в реестре массовых запросов — он должен принять значение `Done`. Стоит учитывать, что время, необходимое для проведения выплат и отображения информации об их статусах, может существенно варьироваться в зависимости от количества выплат в файле и их сумм. Также при работе с реестром массовых запросов дополнительно можно ориентироваться на статусы отдельных выплат с помощью параметров Indicator. **На уровень выше:**[B2B-выплаты](ru_b2bremit_about.md) --- # Работа через Gate API {#ru_b2bremit_api} статья о порядке работы с карточками партнёров и выплатами партнёрам через интерфейс Gate API ## Общая информация {#section_dhv_vgy_dtb .section} Для использования функциональности выплат на счета юридических лиц в Gate API доступны следующие конечные точки: - [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list) — для получения данных из карточек партнёров; - [/v2/recipient-account/create](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-create) — для создания карточки партнёра — получателя выплаты; - [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update) — для изменения данных в черновике карточки партнёра; - [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval) — для отправки карточки партнёра на рассмотрение в Ecommpay; - [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete) — для удаления карточки партнёра; - [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external) — для отправки запроса на выплату. Запросы категории `recipient-account` для работы с данными о получателях выплат выполняются в рамках синхронной схемы взаимодействия, а запросы категории `remittance` на создание платёжных поручений на выплаты — в рамках асинхронной. Информация о работе по этим схемам представлена в статье [Организация взаимодействия](ru_gate_interaction_organisation.md#), а информация о формировании подписи — в статье [Работа с подписью к данным](ru_platform_signature.md#). В этом разделе описаны особенности запросов к указанным конечным точкам. ## Получение данных о партнёрах {#section_rfv_mhy_dtb .section} Для получения данных из карточек партнёров следует отправлять запросы к конечной точке [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list). В этих запросах должны указываться параметры `project_id` \(идентификатор проекта, полученный при интеграции\) и `signature` \(подпись\). В ответах на такие запросы содержатся сведения из всех имеющихся карточек партнёров в соответствии с моделью [RecipientAccount](https://api-developers.ecommpay.com/api.html#/c2NoOjUxMTkxMjY1-recipient-account). Для фильтрации данных карточек с учётом их идентификаторов, присвоенных статусов, а также валют платежей используются массивы `id`, `status` и `currency`. По умолчанию, если в запросе не указаны эти массивы, в ответе отправляются данные из всех имеющихся карточек партнёров. В качестве элементов массивов `id`, `status` и `currency` следует указывать идентификаторы карточек, по которым требуется информация, а также все требуемые типы статусов и валют соответственно, через запятую с пробелом, если необходимо указать несколько значений. Если необходимо указать одно значение, его следует передавать в аналогичных параметрах `id`, `status` и `currency` строкового типа. ``` // Тело запроса { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" } // Тело ответа [ { "general": { "project_id": 21261 }, "info": { "id": 3, "title": "Galaxy catering", "status": "expired", "exp_date": "2021-10-31", "created_date": "2021-09-27 15:24:00", "updated_date": "2021-09-27 15:24:00" }, "recipient_info": { "beneficiary_account": "1242424225621221", "currency": "GBP", "remittance_description": "Catering Pluto locations", "beneficiary_name": "Grebulon", "beneficiary_bank_name": "Taurus bank", "beneficiary_bank_code": "3244232", "beneficiary_bank_country": "PL", "recipient_bank_address": "Tombaugh Regio, Astrid colles, 457" }, "remittance_details": { "monthly_min_amount": 22000, "transfer_max_amount": 2000, "remittance_velocity": 10, "during_days": 30 }, "payment_methods": [ "bank-transfer/world" ], "company_info": { "legal_address": "Rupert", "legal_country": "RP", "legal_city": "Rupert", "zip_code": "101010" } }, { "general": { "project_id": 21261 }, "info": { "id": 7, "title": "Galaxy catering", "status": "created", "exp_date": "0000-00-00", "created_date": "2021-09-01 10:58:36", "updated_date": "2021-09-01 10:58:36" }, "recipient_info": { "beneficiary_account": "1242424225621221", "currency": "EUR", "remittance_description": "Catering Rupert locations", "beneficiary_name": "Grebulon", "beneficiary_bank_name": "Random bank", "beneficiary_bank_code": "13243532", "beneficiary_bank_country": "RP", "recipient_bank_address": "Lila ice plain, 324" " }, "remittance_details": { "monthly_min_amount": 2099, "transfer_max_amount": 3099, "remittance_velocity": 30, "during_days": 30 }, "payment_methods": [ "bank-transfer/world" ], "company_info": { "legal_address": "Rupert", "legal_country": "RP", "legal_city": "Rupert" } } ] ``` ## Создание карточки партнёра {#section_fwq_23y_dtb .section} Для создания карточек партнёров следует отправлять запросы к конечной точке [/v2/recipient-account/create](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-create). В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `title` \(название создаваемой карточки\) в объекте `info`. Также в таких запросах можно указывать остальные сведения о партнёре — получателе выплаты\(сведения о компании, реквизиты и прочие финансовые детали, необходимые для проведения выплаты юридическому лицу\). В ответе на каждый из таких запросов содержится идентификатор созданной карточки партнёра в объекте `info`. ``` // Тело запроса { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "title": "Galaxy catering" }, "recipient_info": { "beneficiary_account": "1242424225621221", "currency": "EUR", "remittance_description": "Catering Rupert locations", "beneficiary_name": "Grebulon", "beneficiary_bank_name": "Random bank", "beneficiary_bank_code": "13243532" }, "remittance_details": { "monthly_min_amount": 2099, "transfer_max_amount": 3099, "remittance_velocity": 30, "during_days": 30 }, "company_info": { "legal_address": "Rupert", "legal_country": "RP", "legal_city": "Rupert" } } // Тело ответа { "info": { "id": 7 } } ``` ## Изменение данных в черновике карточки партнёра {#section_jfm_43y_dtb .section} Для обновления данных в карточках со статусом **Draft** следует отправлять запросы к конечной точке [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update). В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` \(идентификатор карточки, присвоенный при её создании\) в объекте `info`. Также в таких запросах следует указывать данные о получателе выплаты\(сведения о компании, а также реквизиты и прочие финансовые детали, необходимые для проведения выплаты юридическому лицу\), которые необходимо изменить. После обновления данных в карточке партнёра отправляется ответ с кодом `200 OK`. ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7, "title": "Galaxy catering new" } } ``` ## Отправка карточки партнёра на рассмотрение {#section_ohm_h1p_3tb .section} Для отправки карточек на рассмотрение в Ecommpay следует отправлять запросы к конечной точке [/v2/recipient-account/send-for-approval](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-send-for-approval) . В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` в объекте `info`. На рассмотрение следует отправлять карточки со всеми данными, указание которых является обязательным. При этом сведения о валюте выплат и стране получателя должны передаваться в форматах, указанных в [Справочниках](ru_directory.md). - В объекте `info` должен быть передан параметр `title` с названием карточки. - В объекте `recipient_info` должны быть переданы следующие параметры: - `beneficiary_account` — номер счёта компании-партнёра; - `currency` — код валюты для проведения платежей \(в формате ISO-4217 alpha-3\); - `remittance_description` — назначение платежей; - `beneficiary_name` — название компании-партнёра; - `beneficiary_bank_name` — название банка, в котором открыт счёт компании-партнёра; - `beneficiary_bank_code` — код банка, в котором открыт счёт компании-партнёра. - В объекте `remittance_details` должны быть переданы следующие параметры: - `monthly_min_amount` — минимальная сумма выплат в месяц; - `transfer_max_amount` — максимальная сумма разовой выплаты; - `remittance_velocity` — планируемое количество выплат в течение 30 дней. **Прим.:** При существенном превышении максимальной суммы разовой выплаты и запланированного количества выплат для проведения платежа может требоваться до 14 рабочих дней. Во избежание процедуры дополнительного одобрения со стороны Ecommpay рекомендуется устанавливать ограничения с соответствующими запасами. - В объекте `company_info` должны быть переданы следующие параметры: - `legal_address` — юридический адрес компании-партнёра; - `legal_country` — код страны, где зарегистрирована компания-партнёр \(в формате ISO 3166-1 alpha-2\); - `legal_city` — название города, в котором зарегистрирована компания-партнёр. Если полученный запрос на отправку карточки корректен, от платформы возвращается ответ с кодом `200 OK`. Если данные представлены в карточке не полностью, в ответе на запрос отправки карточки на рассмотрение в массиве `errors` содержится список недостающих параметров. Если в карточке содержатся некорректные данные, в ответе на такой запрос в массиве `errors` передаётся информация о неверно указанном параметре. В таких случаях можно указать недостающие параметры или передать корректную информацию, используя запрос к конечной точке [/v2/recipient-account/update](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-update), и повторно отправить карточку на рассмотрение.Информацию о передаваемых кодах ответов на запросы следует уточнять в статье [Работа с информацией об операциях](ru_platform_payment_info_codes.md). ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7 } } ``` ``` HTTP/1.1 400 Bad Request //стартовая строка ответа ... //поля заголовка { "status":"error", //статус обработки запроса "errors":[ //массив со списком необходимых параметров { "code":"2003", "message":"Must be at least 4 characters long", "field":"recipient_info.beneficiary_account", "constraint":"" }, { "code":"2003", "message":"Must have a minimum value of 1", "field":"remittance_details.monthly_min_amount", "constraint":"" } ] } ``` ``` HTTP/1.1 400 Bad Request //стартовая строка ответа ... //поля заголовка { "status":"error", //статус обработки запроса "errors":[ //информация о некорректных данных { "code":"2003", "message":"Invalid value for field recipient_info.currency", "field":"recipient_info.currency", "constraint":"" } ] } ``` ## Удаление карточки партнёра {#section_dv2_1jy_dtb .section} Для удаления карточек с любым из присвоенных статусов, кроме статуса **Created**, следует отправлять запросы к конечной точке [/v2/recipient-account/delete](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-delete). В каждом из таких запросов должны указываться параметры `project_id` и `signature` в объекте `general` и параметр `id` в объекте `info`. По удалении карточки партнёра отправляется ответ с кодом `200 OK`. ``` { "general": { "project_id": 21261, "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "info": { "id": 7 } } ``` ## Отправка запроса на выплату {#section_zkk_njy_dtb .section} Чтобы создавать платёжные поручения на выплаты юридическим лицам, следует отправлять запросы к конечной точке [/v2/payment/remittance/external](https://api-developers.ecommpay.com/remittances/post-v2-payment-remittance-external). Необходимо помнить, что заявки на выплату можно создавать только для получателей, карточки которых одобрены и их срок действия не истёк\(что подтверждается статусом **Active**\). В каждом из таких запросов должны указываться: - параметр `id` \(идентификатор карточки получателя платежа\) в объекте `recipient`; - параметры `project_id`, `payment_id` и `signature` в объекте `general`; - параметры `amount`, `currency` и `payment_method_alias` \(сумма и валюта платежа, а также идентификатор платёжного метода из массива `payment_methods`, переданного в ответе на запрос категории [/v2/recipient-account/list](https://api-developers.ecommpay.com/remittances/post-v2-recipient-account-list)\) в объекте `payment`. ``` { "general": { "project_id": 21261, "payment_id": "galaxy_catering_0001", "signature": "UGVhY2UgdG8gdGhlIHdvcmxkIA==" }, "payment": { "amount": 234, "currency": "EUR", "payment_method_alias": "bank-transfer/world", "description": "Catering Mars locations" }, "recipient": { "id": 7 } } ``` Информация о результатах проведения выплат передаётся в оповещениях типового формата, описание которых представлено в статье [Работа с оповещениями](ru_platform_callbacks.md#). **На уровень выше:**[B2B-выплаты](ru_b2bremit_about.md) --- # B2B API {#b2b_api} **На уровень выше:** [B2B-выплаты](ru_b2bremit_about.md) { "openapi": "3.0.2", "info": { "title": "Remittances", "description": "Requests for making B2B payments and working with recipient accounts", "version": "3.34.5" }, "servers": [ { "url": "https://api.ecommpay.com" } ], "paths": { "/v2/payment/remittance/external": { "post": { "summary": "/v2/payment/remittance/external", "description": "Request to send money from merchant to legal entities (merchant partners)", "operationId": "POST_v2-payment-remittance-external", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "payment", "recipient" ], "type": "object", "properties": { "general": { "$ref": "#/components/schemas/GeneralInfo" }, "payment": { "type": "object", "description": "Object that contains payment information", "required": [ "amount", "currency", "payment_method_alias" ], "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 in the ISO 4217 alpha-3 format" }, "payment_method_alias": { "type": "string", "description": "Alias of payment method" }, "description": { "type": "string", "maxLength": 255, "description": "Payment description or comment for additional data analisys by using Dashboard" } } }, "recipient": { "type": "object", "description": "Object that contains the data of the recipient", "required": [ "id" ], "properties": { "id": { "type": "integer", "description": "Identifier of recipient account card" } } }, "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" } } } } } } }, "/v2/recipient-account/list": { "post": { "summary": "/v2/recipient-account/list", "operationId": "POST_v2-recipient-account-list", "requestBody": { "content": { "application/json": { "schema": { "required": [ "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "currency": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{3}$" }, "description": "Array of currencies in the ISO 4217 alpha-3 format" }, { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency in the ISO 4217 alpha-3 format" } ] }, "status": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "description": "Array of statuses of recipient account entity" }, { "type": "string", "description": "Status of recipient account entity" } ] }, "id": { "anyOf": [ { "type": "array", "items": { "type": "integer", "minimum": 1 }, "description": "Array of ID" }, { "type": "integer", "minimum": 1, "description": "ID of recipient account" } ] }, "signature": { "type": "string", "minLength": 1, "maxLength": 255 } } } } }, "required": true }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "array", "description": "Array that contains remittance recipient accounts", "items": { "$ref": "#/components/schemas/RecipientAccount" } } } } }, "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" } } } } }, "description": "Request for retrieving remittance recipient accounts" } }, "/v2/recipient-account/create": { "post": { "summary": "/v2/recipient-account/create", "operationId": "POST_v2-recipient-account-create", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "info" ], "type": "object", "properties": { "general": { "type": "object", "required": [ "project_id", "signature" ], "properties": { "project_id": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature generated on the basis of request parameters by using the project secret key. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "info": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 64 } } }, "recipient_info": { "type": "object", "properties": { "beneficiary_account": { "type": "string", "minLength": 4, "maxLength": 32 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency in the ISO 4217 alpha-3 format" }, "remittance_description": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_name": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_bank_name": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_bank_code": { "type": "string", "minLength": 4, "maxLength": 64 }, "beneficiary_bank_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "recipient_bank_address": { "type": "string", "minLength": 4, "maxLength": 128 } } }, "remittance_details": { "type": "object", "properties": { "monthly_min_amount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "transfer_max_amount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "remittance_velocity": { "type": "integer", "minimum": 1 } } }, "company_info": { "type": "object", "properties": { "legal_address": { "type": "string", "minLength": 4, "maxLength": 128 }, "legal_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "legal_city": { "type": "string", "minLength": 1, "maxLength": 128 }, "zip_code": { "type": "string", "maxLength": 64 } } } } } } }, "required": true }, "responses": { "200": { "description": "ID of created recipient account", "content": { "application/json": { "schema": { "type": "object", "required": [ "info" ], "properties": { "info": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" } } } } } } } }, "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" } } } } }, "description": "Request for creating a remittance recipient account" } }, "/v2/recipient-account/update": { "post": { "summary": "/v2/recipient-account/update", "operationId": "POST_v2-recipient-account-update", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "info" ], "type": "object", "properties": { "general": { "type": "object", "required": [ "project_id", "signature" ], "properties": { "project_id": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature generated on the basis of request parameters by using the project secret key. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "info": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string", "maxLength": 64 } } }, "recipient_info": { "type": "object", "properties": { "beneficiary_account": { "type": "string", "minLength": 4, "maxLength": 32 }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency in the ISO 4217 alpha-3 format" }, "remittance_description": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_name": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_bank_name": { "type": "string", "minLength": 4, "maxLength": 128 }, "beneficiary_bank_code": { "type": "string", "minLength": 4, "maxLength": 64 }, "beneficiary_bank_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "recipient_bank_address": { "type": "string", "minLength": 4, "maxLength": 128 } } }, "remittance_details": { "type": "object", "properties": { "monthly_min_amount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "transfer_max_amount": { "type": "integer", "minimum": 1, "maximum": 100000000 }, "remittance_velocity": { "type": "integer", "minimum": 1 } } }, "company_info": { "type": "object", "properties": { "legal_address": { "type": "string", "minLength": 4, "maxLength": 128 }, "legal_country": { "type": "string", "pattern": "^[A-Z]{2}$" }, "legal_city": { "type": "string", "minLength": 1, "maxLength": 128 }, "zip_code": { "type": "string", "maxLength": 64 } } } } } } }, "required": true }, "responses": { "200": { "description": "Recipient account was updated" }, "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" } } } } }, "description": "Request for updating a remittance recipient account" } }, "/v2/recipient-account/send-for-approval": { "post": { "summary": "/v2/recipient-account/send-for-approval", "operationId": "POST_v2-recipient-account-send-for-approval", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "info" ], "type": "object", "properties": { "general": { "type": "object", "required": [ "project_id", "signature" ], "properties": { "project_id": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature generated on the basis of request parameters by using the project secret key. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "info": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" } } } } } } }, "required": true }, "responses": { "200": { "description": "Recipient account was sent to approval" }, "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" } } } } }, "description": "Request for sending a remittance recipient account for approval" } }, "/v2/recipient-account/delete": { "post": { "summary": "/v2/recipient-account/delete", "operationId": "POST_v2-recipient-account-delete", "requestBody": { "content": { "application/json": { "schema": { "required": [ "general", "info" ], "type": "object", "properties": { "general": { "type": "object", "required": [ "project_id", "signature" ], "properties": { "project_id": { "type": "integer", "minimum": 1, "maximum": 4294967295 }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature generated on the basis of request parameters by using the project secret key. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" } } }, "info": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" } } } } } } }, "required": true }, "responses": { "200": { "description": "Recipient account was deleted" }, "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" } } } } }, "description": "Request for deleting a remittance recipient account" } } }, "components": { "schemas": { "GeneralInfo": { "required": [ "payment_id", "project_id", "signature" ], "type": "object", "properties": { "project_id": { "type": "integer", "description": "Identifier of merchant project received from Ecommpay", "minimum": 1, "maximum": 4294967295 }, "payment_id": { "type": "string", "minLength": 1, "maxLength": 255, "strict": true, "description": "Identifier of the payment, must be unique within the project. Any letters, digits, and symbols in UTF-8 encoding can be used, except when certain characters occur at the beginning and/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" }, "signature": { "type": "string", "minLength": 1, "maxLength": 255, "description": "Digital signature generated on the basis of request parameters by using the project secret key. For more information, see [Signature generation and verification](https://developers.ecommpay.com/en/en_Gate_Authentication.html)" }, "terminal_callback_url": { "type": "string", "maxLength": 255, "description": "URL for callbacks receivied by Payment Page" }, "referrer_url": { "type": "string", "maxLength": 255, "description": "Site URL from which a customer was redirected to Payment Page" }, "merchant_callback_url": { "type": "string", "minLength": 1, "maxLength": 255, "description": "URL for callbacks receivied by Merchant" } }, "description": "Object that contains general request details" }, "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" ] }, "GateSuccessResponse": { "required": [ "payment_id", "project_id", "request_id", "status" ], "type": "object", "properties": { "status": { "type": "string", "maxLength": 255, "description": "Request registration status" }, "request_id": { "type": "string", "maxLength": 100, "description": "Identifier of the request in the payment platform" }, "project_id": { "type": "integer", "description": "Identifier of merchant project received from Ecommpay" }, "payment_id": { "type": "string", "maxLength": 255, "description": "Identifier of the payment, must be unique within project. Any letters, digits, and symbols in UTF-8 encoding can be used" } }, "description": "Object that contains information about request acceptance or execution in the payment platform" }, "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" }, "RecipientAccount": { "type": "object", "required": [ "general", "info" ], "properties": { "general": { "type": "object", "required": [ "project_id" ], "properties": { "project_id": { "type": "integer", "description": "Identifier of merchant project received from Ecommpay" } } }, "info": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "status": { "type": "string" }, "exp_date": { "type": "string" }, "created_date": { "type": "string" }, "updated_date": { "type": "string" } } }, "recipient_info": { "type": "object", "properties": { "beneficiary_account": { "type": "string" }, "currency": { "type": "string" }, "remittance_description": { "type": "string" }, "beneficiary_name": { "type": "string" }, "beneficiary_bank_name": { "type": "string" }, "beneficiary_bank_code": { "type": "string" }, "beneficiary_bank_country": { "type": "string" }, "recipient_bank_address": { "type": "string" } } }, "recipient_details": { "type": "object", "properties": { "monthly_min_amount": { "type": "integer" }, "transfer_max_amount": { "type": "integer" }, "remittance_velocity": { "type": "integer" }, "during_days": { "type": "integer" } } }, "payment_methods": { "type": "array", "items": { "type": "string" } }, "company_info": { "type": "object", "properties": { "legal_address": { "type": "string" }, "legal_country": { "type": "string" }, "legal_city": { "type": "string" }, "zip_code": { "type": "string" } } } } } } }, "tags": [ { "name": "Remittances" } ] } --- # Gate2Asia {#ru_gate2asia_info} раздел с материалами о пакетном решении от Ecommpay для ведения бизнеса в Юго-Восточной Азии, с наиболее востребованными в странах этого региона платёжными методами и специфическими возможностями для адаптации к местному платёжному ландшафту ## Общая информация {#section_ztz_grr_5dc .section} Gate2Asia — это пакетное решение от Ecommpay, призванное облегчить ведение бизнеса в Юго-Восточной Азии — в регионе с глубокой интеграцией электронных платежей во все социальные сферы и мощным потенциалом экономического роста. В рамках решения Gate2Asia Ecommpay предоставляет наиболее востребованные в странах этого региона платёжные методы и специфические возможности, так, чтобы обеспечить максимальную адаптацию к местному платёжному ландшафту. Gate2Asia позволяет покрывать следующие страны и специальные административные регионы. | |Страна|Население|ВВП \(млн USD\) |E-commerce \(млн USD\) | |--|------|---------|--------------------|---------------------------| |![](images/pm/flags/vietnam.svg)|[Вьетнам](ru_gate2asia_vietnam.md)|`98` `186` `000`|`429` `717`|`20` `000`| |![](images/pm/flags/hongkong.svg)|[Гонконг](ru_gate2asia_hongkong.md)|`7` `346` `000`|`382` `055`|`20` `300`| |![](images/pm/flags/indonesia.svg)|[Индонезия](ru_gate2asia_indonesia.md)|`275` `501` `000`|`1` `371` `171`|`45` `000`| |![](images/pm/flags/china.svg)|[Китай](ru_gate2asia_china.md)|`1` `412` `175` `000`|`17` `794` `782`|`2` `200` `000`| |![](images/pm/flags/malaysia.svg)|[Малайзия](ru_gate2asia_malaysia.md)|`33` `938` `000`|`399` `649`|`10` `100`| |![](images/pm/flags/thailand.svg)|[Таиланд](ru_gate2asia_thailand.md)|`71` `697` `000`|`514` `945`|`22` `000`| |![](images/pm/flags/philippines.svg)|[Филиппины](ru_gate2asia_philippines.md)|`115` `559` `000`|`437` `146`|`20` `000`| **Прим.:** В таблице приведена информация из источников [The Global Payments Report](https://worldpay.globalpaymentsreport.com/en) и [World Bank World Development Indicators](https://datacatalog.worldbank.org/search/dataset/0037712) \(за 2023 год\) по каждой из стран. - Население — общая численность населения. - ВВП — валовой внутренний продукт. - E-commerce — объём электронных платежей. ## Подключение и настройка {#section_xvd_3rr_5dc .section} При подключении Gate2Asia можно выбирать интересующие страны, методы и валюты платежей и оперативно настраивать вместе со специалистами Ecommpay те способы работы платёжной формы и проведения платежей, которые в наибольшей степени соответствуют специфике выбранных стран и задач мерчанта. Тонкая настройка при этом может затрагивать любую функциональность платёжной платформы Ecommpay, однако, прежде всего, актуальными и специфичными для работы в странах Юго-Восточной Азии обычно оказываются возможности использования параметрической фильтрации методов и дополнительных правил оценки рисков. *Параметрическая фильтрация платёжных методов* позволяет предоставлять пользователям для выбора те методы, которые оптимальны для каждой конкретной оплаты, исходя из указанной в запросе валюты или страны. При использовании большого числа локальных методов для разных стран \(что актуально в этом регионе\) такая фильтрация может существенно повышать удобство и скорость работы пользователей с платёжной формой. Более подробная информация о параметрической фильтрации представлена в статье [Фильтрация платёжных методов](ru_pp_methods_availability.md#). *Применение дополнительных правил оценки рисков при использовании локальных платёжных методов* позволяет настраивать и поддерживать расширенный набор правил, базирующихся на информации о пользователях, их устройствах и платёжных профилях и адаптированных к региональной специфике. Это позволяет повышать уровень защиты от мошеннических операций при работе в конкретных странах. Общая информация о работе с рисками при проведении платежей через платформу представлена [в отдельной статье](ru_dbl_risks.md#). С вопросами об условиях и порядке подключения решения Gate2Asia вместе с настройкой актуальных возможностей можно обращаться к курирующему менеджеру Ecommpay. Если ваша организация ещё не является клиентом Ecommpay, можно подать [соответствующую заявку](https://ecommpay.com/apply-now/). - **[Вьетнам](ru_gate2asia_vietnam.md)** статья с общей информацией об электронных платежах во Вьетнаме и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia - **[Гонконг](ru_gate2asia_hongkong.md)** статья с общей информацией об электронных платежах в Гонконге и о платёжных методах, доступных для проведения платежей в этом специальном административном регионе в рамках решения Gate2Asia - **[Индонезия](ru_gate2asia_indonesia.md)** статья с общей информацией об электронных платежах в Индонезии и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia - **[Китай](ru_gate2asia_china.md)** статья с общей информацией об электронных платежах в Китае и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia - **[Малайзия](ru_gate2asia_malaysia.md)** статья с общей информацией об электронных платежах в Малайзии и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia - **[Таиланд](ru_gate2asia_thailand.md)** статья с общей информацией об электронных платежах в Таиланде и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia - **[Филиппины](ru_gate2asia_philippines.md)** статья с общей информацией об электронных платежах на Филиппинах и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia --- # Вьетнам {#ru_gate2asia_vietnam} статья с общей информацией об электронных платежах во Вьетнаме и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/vietnam.svg)Вьетнам — страна с населением около 98,1 миллиона человек и ВВП на душу населения около 4 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи во Вьетнаме распределились следующим образом. - Карточные платежи — 25 %. - Банковские платежи — 20 %. - Платежи через кошельки — 36 %. - Другие типы платежей — 19 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом и электронными кошельками. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_momoqr.svg)|[MoMo Wallet](pm_momoqr.md#)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_vietnam.svg)|[Vietnamese Online Banking](pm_vietnam.md#)|банковские платежи|+|+| С вопросами об условиях и порядке подключения вьетнамских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Гонконг {#ru_gate2asia_hongkong} статья с общей информацией об электронных платежах в Гонконге и о платёжных методах, доступных для проведения платежей в этом специальном административном регионе в рамках решения Gate2Asia ![](images/pm/flags/hongkong.svg)Гонконг — специальный административный регион Китая с населением около 7,3 миллиона человек и ВВП на душу населения около 50 тысяч USD. Его экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи в Гонконге распределились следующим образом. - Карточные платежи — 44 %. - Банковские платежи — 15 %. - Платежи через кошельки — 32 %. - Другие типы платежей — 9 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в регионе методы, прежде всего для работы с интернет-банкингом. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_hk_banks.svg)|[Banks of Hong Kong](pm_hk_banks.md#)|банковские платежи|–|+| |![](images/pm/methods_icon/pm_hk_qr.svg)|[Hong Kong FPS QR](pm_hk_qr.md#)|банковские платежи|+|–| С вопросами об условиях и порядке подключения гонконгских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Индонезия {#ru_gate2asia_indonesia} статья с общей информацией об электронных платежах в Индонезии и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/indonesia.svg)Индонезия — страна с населением около 275,5 миллиона человек и ВВП на душу населения около 5 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи в Индонезии распределились следующим образом. - Карточные платежи — 17 %. - Банковские платежи — 28 %. - Платежи через кошельки — 40 %. - Другие типы платежей — 15 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом, электронными кошельками и платежами с помощью QR-кодов. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_doku.svg)|[DOKU Wallet](pm_doku.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_ovo.svg)|[OVO Wallet](pm_ovo.md#)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_qris.svg)|[QRIS](pm_qris.md#)|платежи с помощью QR-кодов|+|–| С вопросами об условиях и порядке подключения индонезийских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Китай {#ru_gate2asia_china} статья с общей информацией об электронных платежах в Китае и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/china.svg)Китай — страна с населением около 1,4 миллиарда человек и ВВП на душу населения около 12 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи в Китае распределились следующим образом. - Карточные платежи — 10 %. - Банковские платежи — 2 %. - Платежи через кошельки — 82 %. - Другие типы платежей — 6 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом и электронными кошельками. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_alipay.svg)|[Alipay](pm_alipay.md#)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_unionpay.svg)|[China UnionPay](pm_unionpay.md#)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_wechat.svg)|[WeChat](pm_wechat.md#)|платежи с использованием электронных кошельков|+|–| С вопросами об условиях и порядке подключения китайских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Малайзия {#ru_gate2asia_malaysia} статья с общей информацией об электронных платежах в Малайзии и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/malaysia.svg)Малайзия — страна с населением около 33,9 миллиона человек и ВВП на душу населения около 12 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи в Малайзии распределились следующим образом. - Карточные платежи — 27 %. - Банковские платежи — 39 %. - Платежи через кошельки — 24 %. - Другие типы платежей — 10 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом и электронными кошельками. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_boost.svg)|[Boost Wallet](pm_boost.md#)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_grabpay.svg)|[GrabPay](pm_grabpay.md#)\*|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_malaysia.svg)|[Malaysian Online Banking](pm_malaysia.md#)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_shopee.svg)|[Shopee](pm_shopee.md#)|платежи с использованием электронных кошельков|+|–| |![](images/pm/methods_icon/pm_touchngo.svg)|[Touch&Go](pm_touchngo.md#)|платежи с использованием электронных кошельков|+|+| Работа с каждым из этих методов описана в соответствующей статье. При этом можно отметить, что [GrabPay](pm_grabpay.md#) позволяет проводить выплаты на Филиппинах, в филиппинских песо. С вопросами об условиях и порядке подключения малазийских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Таиланд {#ru_gate2asia_thailand} статья с общей информацией об электронных платежах в Таиланде и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/thailand.svg)Таиланд — страна с населением около 71,6 миллиона человек и ВВП на душу населения около 7 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи в Таиланде распределились следующим образом. - Карточные платежи — 18 %. - Банковские платежи — 44 %. - Платежи через кошельки — 27 %. - Другие типы платежей — 11 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом и платежами с помощью QR-кодов. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_promptpay.svg)|[Promptpay](pm_promptpay.md#)|платежи с помощью QR-кодов|+|–| |![](images/pm/methods_icon/pm_thailand.svg)|[Thai Online Banking](pm_thailand.md#)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_truemoney.svg)|[TrueMoney](pm_truemoney.md#)|платежи с помощью QR-кодов|+|–| С вопросами об условиях и порядке подключения тайских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Филиппины {#ru_gate2asia_philippines} статья с общей информацией об электронных платежах на Филиппинах и о платёжных методах, доступных для проведения платежей в этой стране в рамках решения Gate2Asia ![](images/pm/flags/philippines.svg)Филиппины — страна с населением около 115,5 миллиона человек и ВВП на душу населения около 3,5 тысяч USD. Её экономика, а вместе с ней и сфера электронных платежей активно развиваются. На 2024 год \(по данным [Global Payments Report 2024](https://worldpay.globalpaymentsreport.com/)\) электронные платежи на Филиппинах распределились следующим образом. - Карточные платежи — 31 %. - Банковские платежи — 16 %. - Платежи через кошельки — 34 %. - Другие типы платежей — 19 %. В рамках решения Gate2Asia в платёжной платформе Ecommpay можно подключать наиболее востребованные в стране методы, прежде всего для работы с интернет-банкингом и электронными кошельками. | |Метод|Тип|Оплаты|Выплаты| |--|-----|---|:----:|:-----:| |![](images/pm/methods_icon/pm_maya.svg)|[Maya](pm_maya.md#)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_philippines_atm.svg)|[Philippines Over the Counter & ATM](pm_philippines_atm.md#)|банковские платежи|+|–| |![](images/pm/methods_icon/pm_philippines.svg)|[Banks of the Philippines](pm_philippines.md#)|банковские платежи|+|+| |![](images/pm/methods_icon/pm_coinsph.svg)|[Coins.ph](pm_coinsph.md#)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_gcash.svg)|[GCash](pm_gcash.md#)|платежи с использованием электронных кошельков|+|+| |![](images/pm/methods_icon/pm_grabpay.svg)|[GrabPay](pm_grabpay.md#)|платежи с использованием электронных кошельков|+|+| С вопросами об условиях и порядке подключения филиппинских методов, как и с вопросами о других методах Gate2Asia, можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[Gate2Asia](ru_gate2asia_info.md) --- # Интеграция с платформой Xero {#ru_xero} раздел с материалами о работе с веб-приложением от Ecommpay для интеграции с платформой Xero В этом разделе представлена информация о работе с веб-приложением от Ecommpay для интеграции с платформой Xero. - [Общая информация](ru_xero_overview.md)— вводная статья об основных возможностях и ограничениях, применимых при интеграции с платформой Xero. - [Организация взаимодействия](ru_xero_integration.md#)— статья с инструкциями по подключению и настройке основных функциональных возможностей приложения от Ecommpay. - [Настройка и использование счетов Xero](ru_xero_accounts.md#)— статья об организации работы с внутренними счетами в платформе Xero, используемыми для взаимодействия с платформой Ecommpay. - [Проведение оплат](ru_xero_invoices.md#)— статья с описанием возможностей, сценариев и процедур проведения разовых и повторяемых оплат, которые можно инициировать через платформу Xero и проводить через платформу Ecommpay. - **[Общая информация](ru_xero_overview.md)** статья с вводной информацией об основных возможностях и ограничениях, применимых при интеграции с платформой Xero - **[Организация взаимодействия](ru_xero_integration.md#)** статья с инструкциями по подключению и настройке основных функциональных возможностей приложения Ecommpay для работы с платформой Xero - **[Настройка и использование счетов Xero](ru_xero_accounts.md#)** статья об организации работы с внутренними счетами в платформе Xero, используемыми для взаимодействия с платформой Ecommpay - **[Проведение оплат](ru_xero_invoices.md#)** статья с описанием возможностей, сценариев и процедур проведения разовых и повторяемых оплат, инициируемых через платформу Xero и проводимых через платформу Ecommpay --- # Общая информация {#ru_xero_overview} статья с вводной информацией об основных возможностях и ограничениях, применимых при интеграции с платформой Xero При работе с платформой Ecommpay поддерживается возможность интеграции с облачной платформой бухгалтерского и финансового учёта Xero. Для этого предусмотрено отдельное веб-приложение от Ecommpay, обеспечивающее автоматический обмен информацией между платформами. В результате интеграции с платформой Xero в её интерфейсе становятся доступными следующие возможности: - Финансовые сверки— с возможностями настраивать правила сверок и сопоставлять информацию об операциях из платформы Ecommpay с информацией в платформе Xero \(подробнее — [в отдельной инструкции](ru_xero_accounts.md#section_agj_y2c_wfc)\). - Автоматическое формирование возвратных чеков \(credit notes\)— с автоматическим сопоставлением выполняемых возвратов с оплатами, к которым эти возвраты относятся \(подробнее — [в документации Xero](https://central.xero.com/s/article/Add-a-credit-note-to-a-customers-invoice)\). - Проведение оплат по платёжным ссылкам— с формированием и отправкой пользователям ссылок на оплаты через платёжную форму Payment Page и с отображением статусов и финансовых результатов этих оплат \(подробнее — [в отдельной статье](ru_xero_invoices.md#)\). **Внимание:** Стоит учитывать, что веб-приложение от Ecommpay является сторонним для платформы Xero \(так как оно не размещено [в официальном магазине веб-приложений Xero](https://apps.xero.com/)\). Поскольку в этой платформе допускается работать не более чем с двумя сторонними веб-приложениями одновременно, для подключения решения от Ecommpay может потребоваться отключить одно из других сторонних приложений. Перед отключением любого из приложений желательно убедиться, что это не приведёт к потере критически значимой информации. **На уровень выше:**[Интеграция с платформой Xero](ru_xero.md) --- # FAQ {#ru_faq} раздел с ответами на различные вопросы, которые могут возникать при работе с платформой В этом разделе приводятся ответы на вопросы, которые обычно возникают у технических специалистов мерчантов. Эти вопросы разбиты на следующие группы: - [Интеграция с платформой](ru_faq_integration.md) — о подключении к платформе и настройке и тестировании различной функциональности. - [Проведение платежей](ru_faq_payment_processing.md) — о порядке проведения разных видов платежей и выполнения разных операций и процедур, а также о правилах указания различных параметров в запросах. - [Приём оповещений](ru_faq_callbacks.md) — о работе с программными оповещениями от платёжной платформы, в том числе о параметрах и настройках этих оповещений. - [Контроль результатов](ru_faq_payment_result.md) — о контроле и интерпретации результатов различных платежей, операций и процедур, выполняемых в платформе. - [Работа с опротестованиями](ru_faq_chargebacks.md) — о работе с опротестованиями по платежам, проведённым через платёжную платформу, прежде всего, в тех случаях, когда Ecommpay выступает в качестве эквайера. Если информации, представленной в этом и других разделах документации, оказывается недостаточно для решения ваших задач, следует обращаться к нашим специалистам: - с деловыми и финансовыми вопросами \(о стоимости услуг, расчёте комиссий, работе с балансами и так далее\) — к курирующему менеджеру; - с техническими вопросами \(о работе с разными интерфейсами, составлении запросов и тому подобном\) — к сотрудникам технической поддержки \([support@ecommpay.com](mailto:support@ecommpay.com)\). - **[Интеграция с платформой](ru_faq_integration.md)** статья с ответами на вопросы о подключении к платформе, настройке и тестировании различной функциональности - **[Проведение платежей](ru_faq_payment_processing.md)** статья с ответами на вопросы о порядке проведения разных видов платежей и выполнения операций и процедур, а также о правилах указания отдельных параметров в запросах - **[Приём оповещений](ru_faq_callbacks.md)** статья с ответами на вопросы о работе с программными оповещениями от платёжной платформы Ecommpay - **[Контроль результатов](ru_faq_payment_result.md)** статья с ответами на вопросы о контроле и интерпретации результатов платежей, операций и процедур, выполняемых в платформе Ecommpay - **[Работа с опротестованиями](ru_faq_chargebacks.md)** статья с ответами на вопросы о работе с опротестованиями по платежам, проведённым через платёжную платформу Ecommpay, прежде всего в тех случаях, когда Ecommpay выступает в качестве эквайера --- # Интеграция с платформой {#ru_faq_integration} статья с ответами на вопросы о подключении к платформе, настройке и тестировании различной функциональности В этом подразделе представлены ответы на вопросы о подключении к платформе и настройке и тестировании различной функциональности. Payment Card Industry Data Security Standard \([PCI DSS](https://www.pcisecuritystandards.org/pci_security/)\) — это стандарт по надлежащей защите данных платёжных карт. Он разработан Советом по стандартам безопасности индустрии платёжных карт \(PCI SSC\) и устанавливает требования для всех организаций, применяющих в своей деятельности обработку, хранение или передачу данных платёжных карт. Соблюдать требования этого стандарта обязаны все стороны, задействованные в проведении платежей с использованием платёжных карт — без соблюдения этих требований проводить такие платежи нельзя. Чтобы подтверждать соответствие требованиям PCI DSS и иметь возможность проводить платежи с использованием платёжных карт, со стороны мерчанта необходимо своевременно предоставлять соответствующие документы платёжным системам \(таким как Visa, Mastercard и Amex\), напрямую или через провайдеров. Разные платёжные системы могут предъявлять разные требования к таким документам, в том числе с учётом фактов компрометации данных и прочих факторов, поэтому необходимость предоставления конкретным мерчантом тех или иных документов рассматривается индивидуально. В случаях с платёжными системами Visa и Mastercard документы о соответствии PCI DSS следует предоставлять Ecommpay. К таким документам относятся: - Для всех мерчантов — отчёт о результатах [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. После проверки всех требуемых документов можно проводить платежи с использованием карт этих платёжных систем — об этом, как и об истечении сроков действия отдельных документов, мерчанта оповещает курирующий менеджер Ecommpay. В случаях с другими платёжными системами, как правило, документы о соответствии PCI DSS следует предоставлять напрямую этим платёжным системам, но можно уточнять необходимость их предоставления Ecommpay у курирующего менеджера. Обычно при подключении к платёжной платформе мерчанту предоставляется доступ сначала к тестовой среде, а после — к рабочей. Чтобы протестировать основные сценарии работы без проведения реальных платежей и выводить в свет настроенные и проверенные решения. Для этого специалисты технической поддержки Ecommpay создают и настраивают в платформе два проекта взаимодействия с подключаемым веб-сервисом — тестовый и рабочий, с отдельным идентификатором для каждого из них. И как раз при смене в запросах этого идентификатора \(`project_id`\) происходит магия — всё тестовое превращается в настоящее. Поскольку и адреса для приёма запросов, и наборы параметров в тестовой и рабочей средах идентичны, важно не путать идентификаторы проектов и обращаться с ними должным образом. По умолчанию создаётся один тестовый проект, но при необходимости можно запросить у технической поддержки дополнительные. Также стоит учитывать, что в тестовой среде ограничено количество платёжных методов и сценариев работы. Подробности можно найти в соответствующих разделах о тестировании при прямом использовании платёжных карт \([Номера тестовых карт](ru_test_cards.md)\)и при работе с альтернативными платёжными методами \(например, [тестирование Google Pay](pm_googlepay.md#)\). Все тестовые платежи, как и настоящие, учитываются в платформе, и информация о них отображается в интерфейсе Dashboard, а используемые при тестировании реквизиты платёжных инструментов обрабатываются и защищаются, как и реальные, но никаких реальных списаний средств при этом не выполняется. Поэтому при тестировании можно получать полноценное представление о работе с платежами и не бояться использовать разные данные, в том числе данные реальных платёжных карт, кошельков и других инструментов. И да, что же такое среда в каждом из этих случаев? Это совокупность внутренних программных компонентов платформы, которые в одном случае сконфигурированы для эмулирования процессов проведения платежей, а в другом — для их реального проведения. Вот и всё :\) Платёжная платформа Ecommpay устроена таким образом, что для каждого из её интерфейсов используется свой базовый адрес. Это важно учитывать в тех случаях, когда, например, для одних действий используется Payment Page, а для других — Gate.Так, для формирования токена через Payment Page и проведения выплаты по этому токену через Gate потребуются два запроса на два разных адреса: `https://paymentpage.ecommpay.com` и `https://api.ecommpay.com`. А для получения через Data API информации о балансе средств после проведения этой выплаты — запрос на третий адрес: `https://data.ecommpay.com/v1`. Такое изобилие адресов, конечно, может вызвать путаницу, но всё-таки мы верим, что оно вполне поддаётся пересчёту и осмыслению. Информация о базовых адресах, структурах запросов и прочих особенностях каждого из интерфейсов нашей платформы представлена в описании работы с этими интерфейсами, а полный список адресов для программных и пользовательских действий выглядит следующим образом: - `https://api.ecommpay.com` для взаимодействия через Gate. Например, адрес для запроса на получение статуса платежа выглядит как `https://api.ecommpay.com/v2/payment/status`. Подробная информация о работе с запросами к Gate API представлена в разделе [Формат запроса](ru_gate_interaction_organisation.md#). - `https://paymentpage.ecommpay.com` для взаимодействия через Payment Page. Например, GET-запрос на проведение платежа выглядит как `GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&... HTTP/1.1 Host: https://paymentpage.ecommpay.com`. Подробная информация о работе с запросами к Payment Page API представлена в разделе [Формат запроса](ru_pp_interaction_organisation.md#). - `https://data.ecommpay.com/v1` для взаимодействия через Data API. Например, адрес для запроса на получение балансов выглядит как `https://data.ecommpay.com/v1/balance/get`. Подробная информация о работе с запросами к Data API представлена в разделе [Использование Data API](ru_dbl_api_protocol.md)для Dashboard. - [dashboard.ecommpay.com](https://dashboard.ecommpay.com) для доступа сотрудников мерчантов к веб-интерфейсу Dashboard. *Платёж* в контексте платформы — некоторая цельная история одного расчёта между мерчантом и пользователем.При этом в рамках одного платежа может происходить как однократное движение денежных средств \(от пользователя к мерчанту при оплате или в обратную сторону при выплате\), так и неоднократное \(например, при оплате с последующим возвратом или при серии списаний в рамках одной оплаты\). Платёж считается завершённым, когда завершены расчёты между мерчантом и пользователем в рамках оказания соответствующей услуги \(и соответствующей исходной заявки мерчанта на проведение платежа\).И, как и в жизни, может менять конечное состояние: например, оплата может быть успешно проведённой \(`success`\), а спустя некоторое время — частично возвращённой \(`partially refunded`\). *Операция* в контексте платформы — это однократное действие над денежными средствами в рамках проведения платежа.Это может быть, в частности, блокировка средств для их последующего списания, само списание, возврат или выплата. Для проведения одного платежа, с учётом его специфики, могут требоваться как одна, так и множество операций, но в любом случае такое разделение помогает контролировать расчёты на уровне цельных историй-платежей и конкретных действий-операций. Для каждого платежа в платформе используется его идентификатор \(`payment_id`\), который задаётся со стороны мерчанта, передаётся в запросах в платёжную платформу и однозначно идентифицирует платёж в рамках проекта. Такие идентификаторы могут состоять из цифр, букв латинского алфавита и других символов в кодировке UTF-8 и не должны превышать 255 знаков: например, *payment-123*или *cosmoshop.sale\_456*. При получении корректного запроса в платформе регистрируется платёж и инициируется выполнение операции по этому платежу. Каждой операции в платформе присваивается идентификатор \(`operation_id`\), уникальный в рамках платформы. Эти идентификаторы передаются в оповещениях и отображаются в интерфейсе Dashboard. Также следует учитывать, что у платежа и операции могут отличаться статусы, например у платежа со статусом `refunded` операция возврата будет иметь статус `success`. Подробнее о различиях и особенностях этих понятий можно почитать в разделе [Проведение платежей](ru_platform_payment_model.md). Давайте уточним: - [Оплата](ru_Gate_purchase.md) — это платёж с переводом денег от пользователя к мерчанту. Оплатой может быть покупка товаров и услуг, внесение предоплаты за бронирование, платёж по подписке и так далее. И оплаты могут быть как разовыми, так и повторяющимися. А ещё по ним могут выполняться возвраты. - [Возврат](ru_Gate_Refund.md) — это операция возвращения от мерчанта к пользователю денег по проведённой оплате. Возвратом может быть, например, отмена бронирования или возвращение товара. И возвраты могут быть на всю сумму оплаты \(полными\) или на часть суммы \(частичными\). - [Выплата](ru_Gate_payout.md) — это платёж с переводом денег от мерчанта к пользователю. Выплатой может быть получение пользователем выигрыша, бонуса или компенсации расходов и так далее. Проведение оплат возможно через любой из доступных в платёжной платформе интерфейсов. Выплаты и возвраты в платёжной платформе осуществляются через Gate API и Dashboard.Однако следует учитывать, что для альтернативных платёжных методов могут поддерживаться не все эти возможности, в то время как для карточных все они поддерживаются в полной мере. Актуальную информацию о работе с каждым из методов можно получать в разделе с его описанием. Если кратко, то отличия в том, насколько быстро списываются деньги и насколько легко и быстро их потом можно полностью или частично вернуть пользователю. Смысл оплаты в одну стадию в том, что деньги списываются без задержек — с той скоростью, с которой это осуществляется на уровне платёжных систем. Это удобно для оплаты товаров и фактически оказанных услуг, когда сумма оплаты уже определена и не подлежит изменению. Если же после проведения такой оплаты надо вернуть деньги пользователю, для этого требуется выполнить полный или частичный возврат средств.Оплаты в одну стадию поддерживаются при работе с разными платёжными методами и применяются в том числе для погашения кредитов и займов в микрофинансовых организациях. Подробная информация о проведении этих оплат представлена в разделе [Оплата в одну стадию](ru_gate_payment_sale.md#). Смысл оплаты в две стадии в том, что деньги сначала блокируются и позднее, при подтверждении, списываются или возвращаются пользователю — с учётом того, какой оказывается итоговая сумма оказанных услуг. Это удобно при разных видах бронирования и аренды, сервисов с предоплатой и страховыми взносами и так далее. Списание заблокированных средств в таких случаях может выполняться по подтверждающему запросу мерчанта или по истечению заданного времени. Если же необходимо вернуть средства пользователю, то до списания это можно сделать через отмену блокировки, а после списания — через возврат, как и в случаях с оплатами в одну стадию. Оплаты в две стадии в настоящее время поддерживаются только при работе с платёжными картами.Подробная информация об их проведении представлена в разделе [Оплата в две стадии](ru_gate_payment_auth.md#). При выборе варианта, наиболее подходящего для конкретного вида бизнесав конкретных регионах, всегда можно обращаться за консультациями к курирующему менеджеру Ecommpay. Платёжные методы в платформе Ecommpay — это способы проведения платежей, которые характеризуются поддерживаемыми операциями, валютами, платёжными инструментами и пользовательскими сценариями в доступных регионах для конкретных платёжных систем. Так, оплаты индонезийскими рупиями через системы интернет-банкинга Индонезии представляют собой один метод, а оплаты через электронные кошельки в той же валюте — другой. И такие отличия, специфичные для разных регионов и видов бизнеса, делают актуальными множество платёжных методов в платёжной платформе. Для уточнения различий между конкретными методами и выбора методов, наиболее подходящих для вида бизнеса мерчанта, следует обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[FAQ](ru_faq.md) --- # Проведение платежей {#ru_faq_payment_processing} статья с ответами на вопросы о порядке проведения разных видов платежей и выполнения операций и процедур, а также о правилах указания отдельных параметров в запросах В этом подразделе представлены ответы на вопросы о том, как эффективно инициировать и проводить платежиразных видов, обеспечивая их высокую проходимость и решая при этом типичные и нетипичные задачи. Вопросы этой группы касаются того, как через грамотное указание различных параметрови настройку решений для конвертации валют сводить к минимуму уровень отклонения платежей, а также того, как при необходимости возвращать средства пользователями отменять такие возвраты и выплаты. ## Почему отличаются наборы обязательных параметров в разных запросах \(и что с этим делать\)? {#section_ccs_qv3_31c .section} **Кратко:** это связано с тем, что разные платёжные системы и провайдеры по-разному строят свою работу и применяют различные требования к входным данным; и чтобы оптимизировать работу с платежами в разных случаях, может быть полезным использовать в запросах максимально развёрнутые наборы сведений о пользователях. Платёжная платформа позволяет выполнять множество операций с использованием разнообразных платёжных методов.Для выполненияэтих операцийможет требоваться участие разных партнёров\(платёжных систем и провайдеров\),и у каждого из этих партнёровмогут применяться свои правила работы и требования к параметрам для проведения платежей. Поэтому такие параметры, как описание платежа, номер телефона пользователя или адрес его электронной почты и прочие подобные, могут быть обязательны в одних случаях и не обязательны в других. В платформе мы стараемся обеспечивать максимальную доступность платежей и операций, поэтомув каждом случае сводим число строго обязательных параметров к минимуму и описываем это в спецификациях API и документации. Вместе с тем, для сложных ситуаций, когда для одной операции в рамках одного платёжного метода одни и те же параметры могут быть обязательными или нетс учётом специфических факторов \(как, например, в случае с проверкой AVS\), мы применяем специальную процедуру с дополнением информации о платеже по ходу его проведения\([Дополнение информации о платеже](ru_Gate_Clarification.md)\). Чтобы оптимизировать работу с обязательными и необязательными параметрами, на стороне веб-сервиса можно настроить регистрацию и использование в каждом запросе максимально полного набора данных о пользователях\(поскольку именно эти параметры чаще всего могут запрашиваться в качестве дополнительных со стороны провайдеров и платёжных систем\). Также с частными вопросамио параметрах и работе с ними всегда можно обращаться к специалистам технической поддержки Ecommpay. ## Зачем указывать платёжный метод при вызове Payment Page? {#section_nqt_lcj_31c .section} **Кратко:** это сокращает пользовательский сценарий в платёжной форме и может быть удобным, когда актуально предоставить пользователю возможность выбора платёжного метода непосредственно в веб-сервисе или выбрать предпочтительный метод за него. Платёжная форма Payment Page по умолчанию открывается со страницы выбора платёжного метода:![](images/ecommpay/ru_faq_payment_processing_1.svg) Но порой это может быть лишним. Например, если пользователь выбирает метод оплаты до вызова платёжной формы или если ему по каким-то причинам надо предоставить конкретный метод, предпочтительный для оплат из конкретного региона. Для таких случаев предусмотрен вызов Payment Page с указанием конкретного платёжного метода. И если в запросе на открытие формы использовать параметр `force_payment_method`, то платёжная форма открывается со страницы для работы с выбранным методом.Как правило, это страница для указания платёжных реквизитов:![](images/ecommpay/ru_faq_payment_processing_2.svg) Это удобно и помогает улучшать пользовательские сценарии. Однако, стоит учитывать, что при вызове Payment Page с указанием конкретного платёжного метода пользователь оказывается ограничен в выборе иного метода оплаты даже в тех случаях, когда исходная попытка не удалась и могут задействоваться повторные попытки \([подробнее](ru_PP_Try_Again.md)\).Поэтому открывать Payment Page с указанием метода лучше только когда есть уверенность, что для пользователя актуален выбранный метод оплаты и это сочетается с использованием других возможностей, в том числе для повторных попыток оплаты. Более подробная информация о предварительном выборе платёжных методов представлена [в отдельной статье](ru_PP__PreselectingPS.md). Вместе с тем, для оптимизации пользовательских сценариев и способов работы с платёжными методами могут быть полезны такие возможности, как ограничение списка платёжных методов\(с использованием параметра `hide`\)и оплата с использованием токенов платёжных карт\([Проведение оплат по токенам](ru_PP_Payment_by_token.md)\). ## Почему важно передавать идентификатор и IP-адрес пользователя? {#section_pts_qcj_31c .section} **Кратко:** эти параметры позволяют глубже анализировать платёжный трафик и, помимо прочего, обеспечивать дополнительную защиту от мошенничества. При работе с платёжной платформой Ecommpay к числу обязательных параметров для выполнения финансовых операций относятся IP-адрес и идентификатор пользователя. Они необходимы для анализа операций на предмет мошенничества, и при отсутствии или некорректном указании этих данных операции могут отклоняться, понижая конверсию. ## Как указывать имя пользователя? {#section_z41_5cj_31c .section} **Кратко:** при указании имени и фамилии пользователя важно использовать реальную информацию \(в том числе для прохождения различных проверок\) и соблюдать определённые требования, позволяющие использовать различные алфавитные и отдельные неалфавитные символы. При составлении запросов к платёжной платформе может быть актуальным указывать имя и фамилию пользователя и \(или\) держателя карты. В таких случаях важно соблюдать ряд условий, потому что эти параметры проходят проверку не только на корректность формата данных, но и на соответствие различным правилам, в том числе правилам защиты от мошенничества. Так, в платёжной платформе запрещено проведение выплат на неперсонифицированные платёжные карты, поскольку их нельзя проверить на санкционные ограничения.Кроме того, имя и фамилия пользователя могут проверяться и на стороне платёжных систем на соответствие их правилам. Чтобы избегать отклонения платежей из-за ошибок в именах пользователей, при их указании важно соблюдать следующие рекомендации: - имя и фамилия должны быть реальными, например, *CARD HOLDER* или *Customer Name* некорректны; - количество символов в значении любого параметра, относящегося к имени, должно быть не менее 2 и, по возможности, не более 50; - допускается использование различных букв, цифр и других символов в кодировке UTF-8. Для параметра `card_holder` дополнительно к перечисленным применяются следующие условия: - допускается использование: - любых алфавитных символов из числа представленных в стандарте Unicode, - точки в сокращениях, например в словах *Mr.* или *Jr.*, - апострофа, например как в *d'Arc* или *O'Hara*, - дефиса в составных именах и фамилиях, например *Anna-Maria* или *Jean-Baptiste*. - допускается использование не менее двух слов, при этом хотя бы два слова должны содержать более одной буквы, и не более одной точки, поэтому, например, конструкция *Mr. Alexandre Dumas Jr.* является некорректной, а *Alexandre Dumas Jr.* — допустимой; - не допускается использование дефиса для сокращений, так как он интерпретируется как разделитель между словами, и поэтому, например, конструкция *M-r Holder* является некорректной, так как образует три слова, два из которых состоят всего из одной буквы. ## Что можно передавать в параметре description? {#section_nfd_bdj_31c .section} **Кратко:** если этот параметр обязателен, в его значении необходимо указывать причину выполнения операции, если же этот параметр не обязателен, можно указывать любые дополнительные сведения. В запросах на проведение платежей через платформу используется параметр `description`.В зависимости от типа операции и специфики платёжного метода онможет быть обязательным, например для возвратов, и необязательным.Обязательность для разных случаев можно уточнять в статьях с описаниями используемых методов. - Если параметр `description` обязателен, в его значении необходимо указывать причину выполнения операции, например: *Частичный возврат оплаты в связи с тем, что пользователь вернул часть заказа \(не подошёл размер\)*, *Полный возврат из-за технических проблем с оказанием услуги* или *Возврат полной суммы билета из-за отмены сеанса*. - Если параметр `description` необязателен, в его значении можно указывать любые дополнительные сведения о платеже, например: *Пополнение кошелька 007*, *Зачисление на счёт 271828*, *Оплата по промокоду* или *Вывод средств по заявке № 314*. Если эти описания указываются в запросах, то они передаются в оповещениях и отображаются в интерфейсе Dashboardи при необходимости могут использоваться для дополнительного анализа платежей на стороне мерчанта. ## Когда и как применяется конвертация валют? {#section_lbg_xwd_wbc .section} **Кратко:** конвертация применяется, когда хотя бы одна из задействованных в проведении платежа валют отличается от остальных, и может выполняться как на стороне платёжного сервиса, обслуживающего пользователя, так и на стороне Ecommpay. Выполнение любой финансовой операции подразумевает перемещение средств от определённого „источника“ к заданному „приёмнику“ по связывающему их „каналу“. В случае с платёжной платформой Ecommpay это выглядит так: - источником и приёмником выступают платёжный инструмент пользователя и балансовые средства мерчанта \(для оплат — в указанном сочетании, для возвратов и выплат — в обратном\); - платёжным каналом выступает совокупность технических средств и логических сущностей, которая позволяет перемещать средства между платёжной платформой, обслуживающей мерчанта, и платёжным сервисом, обслуживающим пользователя. Когда в платёжном инструменте пользователя, на балансе мерчанта и в используемом платёжном канале используются средства в одной и той же валюте, финансовые операции могут выполняться без каких-либо конвертаций. Но когда хотя бы одна из этих валют отличается от других, необходима конвертация— такая, чтобы можно было переместить средства по используемому каналу. Фактической валютой любой операции, которая может также называться операционной или расчётной, всегда выступает именно валюта канала\(помимо прочего, это может быть важным для учёта и анализа платежей, работы по опротестованиям и других процессов\). Исходя из этого строится и конвертация: - если от расчётной валюты отличается валюта платёжного инструмента пользователя, тодля стыковки с каналом выполняется конвертация на стороне организации, обслуживающей этот платёжный инструмент; - если от расчётной валюты отличается балансовая валюта мерчанта, тодля стыковки с каналом выполняется конвертация на стороне Ecommpay. В качестве примера можно рассмотреть ситуацию, когда пользователь из Польши с платёжной картой, счёт которой ведётся в польских злотых\(`PLN`\), рассчитывается за определённую услугу в Норвегии с использованием платёжного канала в норвежских кронах\(`NOK`\), а балансовой валютой мерчанта при этом выступает евро\(`EUR`\). В таком случае конвертация из злотых в кроны выполняется на стороне эмитента\(по применяемому им курсу и на его условиях\), а конвертация из крон в евро — на стороне Ecommpay. В дополнение к этому возможны ситуации, когда исходная валюта операции, указанная в запросе, отличается от валюты используемого канала. Для обработки таких ситуаций на стороне платёжной платформы применяется алгоритм с первичной конвертацией исходной суммы в валюту канала и последующим выполнением операции для сконвертированной суммы в валюте канала\(с дополнительными вторичными конвертациями, как в приведённом примере, если они актуальны\). При этом в типовом программном оповещении о выполнении такой операции исходные сумма и валюта, указанные в запросе, обозначаются как `sum_initial`, а сконвертированныерасчётные сумма и валюта — как `sum_converted`. Подытоживая, можно сказать, что конвертация валют при выполнении финансовых операций применяется как вспомогательная процедура для подстройки под используемые платёжные каналы, как со стороны пользователя и его платёжного сервиса, так и со стороны мерчанта и платёжной платформы Ecommpay. ## Как оптимизировать работу с разными валютами и их конвертацией? {#section_w5y_wvd_wbc .section} **Кратко:** чтобы минимизировать число необходимых конвертаций и возможных потерь при проведении платежей, можно подключать разные платёжныеметоды и каналы с учётом специфики аудитории мерчанта и планов развития бизнеса, а также использовать различные возможности и решения, доступные в платёжной платформе\(например, возможность [конвертации с выбором валюты пользователем](ru_pp_currency_choice.md) при работе через Payment Page\). При изобилии платёжныхметодов, инструментов и валют в современной электронной коммерции конвертация валют зачастую оказывается одним из ключевых факторов, обеспечивающих возможность проведения платежей и оказания услуг. Вместе с тем, ни пользователи, ни мерчанты не любят терять деньги на комиссиях и курсовых разницах валютных пар, что вполне допустимо при конвертации. Чтобы минимизировать число необходимых конвертацийи возможных потерь при проведении платежей, со стороны мерчанта можно выстраивать комплексную работу в этом направлении. - Прежде всего, стоит анализировать свою аудиторию и её платёжные предпочтения.Из каких стран ваши пользователи, какимиметодами и валютами они предпочитают пользоваться и насколько часто могут сталкиваться с конвертацией. - Понимая специфику своей аудитории и планы развития бизнеса, стоит настраивать под них спектр используемых платёжныхметодов и каналов. При этом полезно обращаться к курирующему менеджеру Ecommpay для выстраивания оптимальной структуры поддерживаемых валют, балансов и каналов.Помимо прочего, в рамках такой работы могут задаваться валюты, используемые в разных случаях для конвертации по умолчанию, и настраиваться другие полезные решения. - Работая с широким кругом пользователей, может быть полезным давать им возможность самостоятельного выбора расчётной валюты и избегания конвертации на их стороне.При использовании платёжной формы Payment Page такая возможность может обеспечиваться в ней \([подробнее](ru_pp_currency_choice.md)\). В иных случаях можно настроить это в рамках веб-сервиса. - Сталкиваясь с другими вопросами и задачами, связанными с конвертацией, также можно обращаться к специалистам Ecommpay— мы всегда заинтересованы в том, чтобы обеспечивать лучший сервис для своих клиентов и решать даже самые нетипичные задачи. ## Когда и как можно возвращать средства пользователям? {#section_g5j_xd4_h1c .section} **Кратко:** после проведения оплаты по ней, как правило, можно выполнить возврат, через Gate API или Dashboard; кроме того, в некоторых случаях можно возвращать средства и другими способами, через отмены блокировок в рамках двухстадийных оплат и через выплатытеми же или иными платёжными методами. *Что такое «возврат» в платёжной платформе.* Возвратом в рамках платёжной платформы Ecommpay называется операция перевода пользователю средств, списанных с него при проведении оплаты.То есть, если что-то в рамках оплаты через платформу с пользователя списали, то посредством возврата через платформу можно это списанное ему вернуть, в рамках той же оплаты. Довольно просто, но, как водится, есть разные нюансы. *Что стоит знать о возвратах.* Чтобы ориентироваться в работе с возвратами, полезно знать о следующем: - Возвраты могут быть полными и частичными\(на всю сумму оплаты или на её часть\). В платформе поддерживается возможность выполнять неоднократные возвраты по одной и той же оплате, при условии, что сумма каждого очередного возврата не превышаетсумму, которую списали при оплате и ещё не вернули пользователю в рамках предыдущих возвратов \(эта сумма называется актуальной суммой платежа\). - Возвраты могут выполняться не во всех случаях. Если для оплат с прямым использованием карт возвраты, как правило, доступны без ограничений, то для оплат альтернативными платёжными методами ситуация может быть разной: возвраты могут поддерживаться в полной мере или с ограничениями либо не поддерживаться вовсе.Среди ограничений в таких случаях может быть, например, недоступность частичных возвратов или недоступность любых возвратов по истечении заданного срока давности оплат. Что с этим делать? Прежде всего, по каждому из подключаемых альтернативных методов можно уточнять, поддерживаются ли для него возвраты, и если да, то стоит ли учитывать при этом какие-либо особенности. Кроме того, если в каких-то случаях возвраты могут быть недоступны, но вернуть деньги необходимо, можно уточнять, есть ли возможности перевода средств пользователям другими способами\(например, посредством выплат через те же или другие платёжные методы\). И, как и в иных сложных ситуациях, можно рассчитывать на помощь курирующего менеджера Ecommpay. - Возвраты могут выполняться с помощью разных технических операций. С учётом специфики различных платёжных систем технической операцией по возврату средств в разных случаях может выступать `reversal` или `refund`. Как правило, `reversal` используется для возврата, выполняемого до закрытия того операционного дня, в который была проведена соответствующая оплата с использованием платёжной карты, а `refund` в остальных случаях.Вместе с тем, `reversal` может использоваться, например в случаях, когда в рамках оплаты с проверкой зачисления\(через операцию `payment confirmation`\) выявляется, что средства не были зачислены на счёт. Что с этим делать? Иметь в виду, что есть такие нюансы и не удивляться разным названиям операций. К слову, в интерфейсе Dashboard ко всем возвратам применяется название `refund` \(чтобы было немного проще\). Если же важно учитывать, в каких случаях была операция `reversal`, а в каких `refund`, достаточно контролировать это через программные [оповещения](ru_platform_callbacks.md#) и, если актуально, через интерфейс [Data API](https://api-data.ecommpay.com/). Если необходима более детальная информация, можно обращаться к отдельной статье [Возвраты средств после оплат](ru_Gate_Refund.md). *Как инициировать возвраты.* Инициировать возвраты со стороны мерчанта можно через Gate API и Dashboard. При работе через Gate API для инициирования возвратов используются конечные точки и форматы, описанные всоответствующих статьях: для платежей с прямым использованием карт — в статье [Возвраты средств после оплат](ru_Gate_Refund.md), для платежей альтернативными методами — в статьях о работе с этими методами, в разделе [Методы](ru_pm_about.md). При работе через Dashboard можно пользоваться механизмами одиночных и массовых возвратов, описанными [в соответствующей статье](ru_dbl_payments.md#). *Можно ли вернуть средства иначе.* Безусловно. В каких-то случаях вместо простых оплат с последующими возвратами могут быть полезны [оплаты в две стадии](ru_platform_dms_model.md). В рамках каждой такой оплаты, как правило, можно сначала блокировать некоторую сумму на счёте пользователя и затем списать только часть этой суммы, сняв блокировку с остатка, или не списывать средства вовсе и вернуть всё пользователю. При этом важным преимуществом может являться скорость возвращения средств: на снятие блокировки могут уходить секунды и минуты, в то время как на возврат средств — часы и дни. Кроме того, в тех ситуациях, когда необходимо вернуть средства по проведённым оплатам, но возвраты не поддерживаются для используемых платёжных методов или не могут быть выполнены из-за применяемых ограничений\(например, по давности оплат\), можно согласовывать с пользователями и специалистами Ecommpay проведение соответствующих выплат через те же или другие платёжные методы. В таких ситуациях важно информировать пользователей об опосредованном возвращении средств и получать их согласие на проведение компенсирующих выплат, в то время как сама возможность такого возвращения средств может выступать дополнительным конкурентным преимуществом и повышать лояльность пользователей. Наконец, если возникают какие-то иные ситуации, не описанные в рамках этого ответа и упомянутых в нём статей, но касающиеся возвращения средств пользователям, можно обращаться к курирующему менеджеру и совместно искать оптимальные решения.И они обязательно найдутся. ## Когда и как можно отменять возвраты и выплаты? {#section_hds_lh2_wbc .section} **Кратко:** в некоторых случаях допускается отменять возвраты и выплаты, возвращая себе средства, некорректно отправленные пользователям; такие специфические операции выполняются через обращения к специалистам технической поддержки Ecommpay. **Введение** Порой могут быть актуальными ситуации, когда в силу разных обстоятельств после перевода пользователю средств в рамках возврата или выплаты необходимо отменить этот перевод и вернуть средства назад— например, если возврат был выполнен не по искомой оплате или если выплата была проведена на избыточную сумму. В платёжной платформе Ecommpay предусмотрены возможностидля отмены таких действий, но только с учётом ограничений, применяемых провайдерами и платёжными системами. **Условия** - Отмены возвратов и выплат могут выполнятьсятолько по тем платёжным методам, для которых поддерживается такая возможность, с учётом возможных дополнительных ограничений по платёжным инструментам и иным критериям. Дополнительная информация о таких ограничениях для платежей с прямым использованием платёжных карт представлена в этом ответе.Информацию для альтернативных платёжных методов можно уточнять у специалистов технической поддержки Ecommpay. - При учёте ограничений по времени, применяемых провайдерами и платёжными системами, следует учитывать также и время, необходимое для отмены возврата или выплаты на стороне Ecommpay — как правило, оно занимает не более тридцати минут. Отмены по истечении заданных сроков могут приводить к опротестованиям, и в таких случаях ответственность за возможные компенсации возлагается на мерчанта. - Отмены возвратов и выплат допустимы только в отношении тех операций и платежей, которые не опротестовываются со стороны пользователей. При получении информации об опротестованиях некорректно выполненных возвратов или выплат рекомендуется принимать такие опротестования. Подробнее о работе с опротестованиями — [в соответствующем подразделе FAQ](ru_faq_chargebacks.md). - Возвраты могут отменяться только по отдельным операциям `refund`. Операции `reversal` не подлежат отмене. Также нельзя отменять сразу несколько операций `refund` с частичными возвратами по одной оплате. Частичные возвраты, как и полные, могут отменяться только по отдельности. - Возвраты по оплатам с прямым использованием платёжных карт могут отменяться только для карт определённых платёжных систем, с учётом заданных ограничений по времени: - для карт American Express — в течение времени, актуального для конкретного проекта\(это время можно уточнить через курирующего менеджера Ecommpay\); - для карт Mastercard — в течение 24 часов; - для карт Visa — в течение 30 календарных дней. - Выплаты с прямым использованием платёжных карт могут отменяться только для карт платёжной системы Visa, в течение одного календарного дня и только в исключительных случаях, устанавливаемых и регулируемых платёжной системой. **Порядок действий** Чтобы отменить возврат или выплату, следует: 1. Определить идентификатор отменяемой операции \(`operation_id`\) и сообщить о необходимости её отмены специалистам технической поддержки Ecommpay. Для определения идентификатора при этом можно использовать карточку платежа в интерфейсе Dashboard или программное оповещение о выполнении операции, а для связи с технической поддержкой — интерфейс Dashboard \(с функцией **Создать обращение в Поддержку** в карточке платежа\)или электронную почту \([support@ecommpay.com](mailto:support@ecommpay.com)\). 2. Получить подтверждение того, что обращение зарегистрировано на стороне Ecommpay. Каждое поступающее обращение автоматически регистрируется, при этом ему присваивается идентификатор \(`ticket ID`\), который указывается в письме о подтверждении регистрации и который можно использовать в дальнейшем для уточнения информации об обращении и работах по нему. 3. Получить ответ по результатам обработки обращения. На обработку подобных обращений, как правило, уходит до получаса, в рамках которых специалисты Ecommpay: 1. Проверяют возможность отмены целевой операции в соответствии с правилами платёжной системы. 2. Если возможность отмены подтверждена, выполняют необходимые действия. При отмене возврата — в рамках платежа, по которому был выполнен возврат, создаётся и выполняется операция `refund_reversal`, ей присваивается статус `success`, а платежу — статус `partially refunded` или `success`\(в зависимости от актуальной суммы платежа\); при этом статус отменяемой операции возврата не меняется, а информация о дополнительно созданной операции и обновлении статусов отображается в карточке платежа в интерфейсе Dashboard и не дублируется в программных оповещениях к веб-сервису. При отмене выплаты — этой выплате присваивается статус `decline`; при этом не создаются дополнительные операции, информация о платеже обновляется в интерфейсе Dashboard, а отправка к веб-сервису оповещения с информацией об изменении статуса выплаты выполняется по предварительному согласованию. 3. Сообщают о результате работ по обращению. 4. Если была осуществлена отмена целевой операции, убедиться в возвращении средств. При отмене возврата баланс должен увеличиваться на сумму этого возврата за вычетом комиссии Ecommpay за его отмену, а при отмене выплаты — на сумму этой выплаты и сумму комиссии Ecommpay, удержанную ранее за её проведение. **На уровень выше:**[FAQ](ru_faq.md) --- # Приём оповещений {#ru_faq_callbacks} статья с ответами на вопросы о работе с программными оповещениями от платёжной платформы Ecommpay В этом подразделе представлены ответы на вопросы о работе с программными оповещениями от платёжной платформы, в том числе о параметрах и настройках этих оповещений. В структуру оповещений, отправляемых от платёжной платформы Ecommpay к веб-сервису мерчанта, включаются наборы параметров о последней операции и о платеже, к которому она относится. Стандартные параметры для оповещений о проведении финансовых операцийи создании токенов описаны в разделе [Работа с оповещениями](ru_platform_callbacks.md#). Вместе с тем, по согласованию со специалистами технической поддержки Ecommpay можно настраивать структуру оповещений с учётом предпочтений мерчанта. Просматривать и изменять настройки оповещений мерчант может только по запросу в техническую поддержку Ecommpay. Если оповещение не приходит в течение установленного периода времени, необходимо убедиться в следующем: 1. Оповещения ожидаются по адресу, который был передан специалистам Ecommpay при интеграции. 2. Для этого адреса корректно настроен приём HTTP-запросов от платёжной платформы: IP-адреса Ecommpay добавлены в список разрешённых и сообщения не блокируются на уровне межсетевого экрана или других сетевых устройств. 3. В запросе на проведение платежа не отключена функция отправки оповещений — не передан параметр `callback.force_disable` со значением `1`. Если все эти условия выполнены, но оповещения по-прежнему не приходят, следует связаться со службой технической поддержки Ecommpay, указав идентификатор проекта и URL, по которому ожидаются оповещения. **На уровень выше:**[FAQ](ru_faq.md) --- # Контроль результатов {#ru_faq_payment_result} статья с ответами на вопросы о контроле и интерпретации результатов платежей, операций и процедур, выполняемых в платформе Ecommpay В этом подразделе представлены ответы на вопросы о контроле и интерпретации результатов различных платежей, операций и процедур, выполняемых в платформе. Для этого можно использовать пользовательские и программные интерфейсы. Но важно помнить, что информация в пользовательских интерфейсах становится доступной с задержкой \(как правило, в пределах минуты\), в то время как через программные интерфейсы эту информацию можно получать без задержек \(с точностью до скорости формирования и передачи сообщений\). Если предпочтительны пользовательские интерфейсы, то можно обращаться к реестрам и карточкам платежей в интерфейсе Dashboard \(подробнее — в разделе [Контроль проведения платежей](ru_dbl_payments.md#) для Dashboard\). Если предпочтительны программные интерфейсы, то можно оперировать оповещениями, отправляемыми от платформы в заданных случаях, и ответами, отправляемыми на запросы о состоянии платежа. В этих оповещениях и ответах используются такие параметры, как `status`, `code` и `message` в объекте `payment` и в массивах `operations` и `errors` \(подробнее — в разделах [Работа с оповещениями](ru_platform_callbacks.md#) и [Получение информации о состоянии платежа](ru_Gate_payment_status_request.md#)\). При работе с интерфейсом Gate надо учитывать, что в синхронных ответах на запросы, обрабатываемые по асинхронной схеме, в параметре `status` в теле ответа указывается статус запроса, но не платежа или операции. Статус `success` в теле ответа свидетельствует о том, что запрос принят в обработку, а статус `error` — о том, что запрос не может быть принят в обработку и выполнен. И не более. Информацию об этих статусах и общей структуре и отправке ответов можно найти в разделе [Формат ответа](ru_gate_interaction_organisation.md#). Чтобы получать информацию именно о состоянии платежей и операций, а не о приёме запросов, стоит оперировать параметрами `status` в соответствующих объектах — `payment` и `operation` — в оповещениях и ответах на запросы о состоянии платежей, либо использовать интерфейс Dashboard. Информация об этом приведена в ответе на предыдущий вопрос. Наконец, можно отметить, что в некоторых случаях фактическое зачисление средств на стороне платёжных систем осуществляется с существенной задержкой \(вплоть до нескольких суток\) после того, как операция была подтверждена и получила конечный статус. Поэтому при вопросах о расхождениях между движением средств и статусами платежей и операций можно обращаться в службу технической поддержки Ecommpay, а также уточнять статусы конкретных платежей на стороне провайдеров и платёжных систем. Если во время обработки запроса или выполнения операции возникли ошибки или поводы для отказа, причины их возникновения можно узнать следующими способами: - В синхронном ответе на запрос, если была обнаружена ошибка при первичной обработке запроса.Информация о таких ошибках представлена в разделе [Формат ответа](ru_gate_interaction_organisation.md#). - В полученном промежуточном или итоговом оповещении — через код ответа и сообщение, которые могут быть представлены: - в массиве `errors`, если операция была отклонена на стороне платёжной платформы, например, если операция не прошла проверку на соответствие установленным бизнес-правилам; - в параметрах `operation.code` и `operation.message`, если операция была отклонена на стороне провайдера или платёжной системы. Информация о работе с оповещениями представлена в разделе [Работа с оповещениями](ru_platform_callbacks.md#). - В карточке платежа в интерфейсе Dashboard. Информация о работе с реестрами и карточками платежей представлена в разделе [Контроль проведения платежей](ru_dbl_payments.md#) \(Dashboard\). Информация о возможных ошибках при выполнении операций и о кодах, которые используются в оповещенияхи интерфейсе Dashboard, представлена в разделе [Работа с информацией об операциях](ru_platform_payment_info_codes.md). **На уровень выше:**[FAQ](ru_faq.md) --- # Работа с опротестованиями {#ru_faq_chargebacks} статья с ответами на вопросы о работе с опротестованиями по платежам, проведённым через платёжную платформу Ecommpay, прежде всего в тех случаях, когда Ecommpay выступает в качестве эквайера В этом подразделе представлены ответы на вопросы о работе с опротестованиями финансовых операций.Представленная здесь информация отчасти является общей и применима к опротестованиям в целом, но большей частью относится к платежам, в которых Ecommpay выступает как эквайери по опротестованиям которых взаимодействует со стороны мерчантас эмитентами и платёжными системами. Это платежи с использованием карт платёжных систем Mastercard и Visa в рамках карточных платежейи методов Apple Pay и Google Pay. ## Что такое «опротестование», chargeback и dispute? {#section_fmz_kr4_p5b .section} **Кратко:** это разные варианты названия для регламентированного оспаривания финансовой операции. *Опротестование* — это регламентированное оспаривание финансовой операции с целью возмещения её полной или частичной суммы. При работе с разными платёжными системами такая процедура может называться по-разному: так, международная платёжная система Mastercard использует термин *опротестование* \(*chargeback*\), а международная платёжная система Visa — *спорная операция*\(*dispute*\). В платёжной платформе Ecommpay принято использовать общий термин *опротестование*\(*chargeback*, для которогов некоторых случаях допустима также форма „чарджбэк“\). Опротестования могут оформляться по инициативе пользователей и эмитентов в отношении отдельных операций, касающихся списания средств с пользователей в рамках оплат, возвратов средств по оплатам и зачислений в рамках выплат.Это может происходить по различным причинам, например при неудовлетворённости пользователя качеством услуги или технической невозможности зачислить средства на стороне эмитента. **Прим.:** Одной из причин опротестования может быть выполнение операции при отказе эмитента в авторизации \(под которой в данном случае подразумевается подтверждение эмитентом возможности проведения оплаты или выплаты с использованием конкретной платёжной карты\). При работе с платёжной платформой Ecommpay операция без авторизации не может быть выполнена технически, поскольку запрос на авторизацию направляется к сервису эмитента автоматически после получения от веб-сервиса мерчанта запроса на проведение платежа, и если авторизация была отклонена, платёж также отклоняется на стороне платформы. Однако это не исключает возможности оформления эмитентами опротестований по причинам, связанным с авторизацией. Опротестования могут влиять на деловую репутацию мерчанта и вести к дополнительным издержкам, поэтому на каждое опротестование важно оперативно реагировать и разрешать его согласно правилам платёжной системы. Чтобы помогать в этом своим мерчантам,Ecommpay активно участвует в работе по опротестованиям техопераций, в которых выступает как эквайер. Это операции с использованием карт платёжных систем Mastercard и Visa в рамках карточных платежейи методов Apple Pay и Google Pay. При опротестованиях таких операций Ecommpay оперативно уведомляет мерчантов о поступлении новой информации об опротестованиях и при необходимости формирует ответные документы для оспаривания опротестований на основе представленных мерчантами доказательств и в соответствии с правилами платёжных систем, после чего направляет эти документы эмитентам и сопровождает процесс вплоть до его завершения. Более подробная информация о порядке работы с опротестованиями представлена в ответе на соответствующий вопрос этого раздела — [Как осуществляется работа с опротестованиями?](ru_faq_chargebacks.md#section_plz_g54_p5b). ## Что делать при получении опротестования? {#section_ozj_mr4_p5b .section} **Кратко:** при получении от Ecommpay информации об опротестовании мерчанту следует принять или оспорить его через интерфейс Dashboard в течение четырёх рабочих дней, следующих за днём информирования. *Что делать.* При поступлении информации о новом опротестовании уведомление об этом отображается в интерфейсе Dashboard и направляется мерчанту по электронной почте, а также через программное оповещение, если была подключена отправка таких оповещений \([подробнее](ru_dbl_chargeback_callbacks.md#)\).В зависимости от того, признаёт ли мерчант правомерность опротестования, он может *принять или оспорить* его.В первом случае работа с этим опротестованием завершается в пользу эмитента. Во втором случае работа ведётся до тех пор, пока одна из сторон не примет обязательство на себя или решение не будет принято арбитражной комиссией платёжной системы. **Прим.:** В интерфейсе Dashboard опротестования группируются по различным случаям \(„кейсам“\) на основе параметров **Дата отчета**, **Номер аккаунта** и **Код причины**, что позволяет предоставлять ответ как по отдельному опротестованию, так и по нескольким опротестованиям в группе. При открытии карточки опротестования на левой панели отображается список всех опротестований, входящих в группу, на двух средних панелях — информация о выбранном опротестовании, а на правой — данные, на основе которых были сгруппированы опротестования. *Что учитывать.* Если в работу с опротестованием вступает арбитражная комиссия, то в случае проигрыша спора или принятия опротестования мерчант признаётся ответственным не только за возмещение оспариваемой суммы, но и за выплату комиссии, взимаемой платёжной системой. Поэтому перед оспариванием рекомендуется *убедиться в наличии необходимых доказательств* дляподтверждения позиции мерчанта и опровержения опротестования. Информацию о том, какие документы могут потребоваться для оспариваний в конкретных случаях, а также рекомендации по оформлению таких документов можно найти в карточках опротестований интерфейса Dashboard\(на панели представления опровержений\) или запросить у специалистов Ecommpay по работе с опротестованиями\(через электронную почту, указав курирующего менеджера в числе адресатов\).Вместе с тем, в некоторых случаях представление документов не обязательно: например, если опротестование было оформлено по причине невыполненной авторизации, достаточно указать код авторизации и дату её выполнения. При рассмотрении опротестований по причинам мошенничества, для которых по оспариваемой операции не был выполнен возврат средств, арбитражные комиссии могут выносить решения с учётом индикаторов результата аутентификации 3‑D Secure \(подробнее — в справочнике [Индикаторы ECI](ru_ECI_codes.md)\): в таких случаях, если в соответствии с этим значением ответственной стороной признан мерчант, решение, как правило, выносится в пользу эмитента. Поэтому перед принятием решения по опротестованию рекомендуется предварительно *проверить индикатор ECI* по оспариваемой операции. *Когда принимать решения.* Обо всех решениях по опротестованию следует сообщать *в установленные Ecommpay периоды*. Для предоставления первичного ответа на опротестование отводится четыре рабочих дня, следующих за днём информирования об опротестовании. Для предоставления последующих ответов период может быть разным: так, при работе с МПС Visa по опротестованиям, связанным с проблемами авторизации и мошенничеством, для ответа мерчанту может отводиться от одного до двух рабочих дней, в других случаях — в среднем около четырёх рабочих дней. При отсутствии ответа в установленный период работа по опротестованию завершается в пользу эмитента или продолжается до вынесения решения арбитражной комиссией \(если опротестование уже было передано эмитентом на рассмотрение в комиссию\). **Прим.:** Информация о периодах, отводимых на принятие решений мерчантом, отображается в карточках опротестований интерфейса Dashboard или, если по согласованию с Ecommpay со стороны мерчанта не используются учётные записи Dashboard, указывается специалистами Ecommpay по работе с опротестованиями в уведомлениях, направляемых на заданный адрес электронной почты мерчанта. *Как фиксировать решения.* Технически принять или оспорить опротестование можно *через раздел* **Чарджбеки** интерфейса Dashboard\(для этого можно воспользоваться инструментами в карточке опротестования: **Принять**, чтобы принять опротестование, и **Предоставить документы**, чтобы оспорить опротестование\) или, если по каким-то причинам ответ не может быть предоставлен через Dashboard, *через обращение* к специалистам Ecommpay по работе с опротестованиями\(адрес их электронной почты можно найти в карточке опротестования или запросить у курирующего менеджера\). *Как решать возникающие вопросы.* При возникновении вопросов по работе с опротестованиями можно обращаться к курирующему менеджеру Ecommpay, а также к специалистам по работе с опротестованиями\(указывая курирующего менеджера в числе адресатов\). ## Как осуществляется работа с опротестованиями? {#section_plz_g54_p5b .section} **Кратко:** работа с каждым опротестованием осуществляется поэтапно в соответствии с одной из заданных схем, при этом Ecommpay как эквайерпредставляет интересы мерчанта, взаимодействуя с платёжной системой и эмитентом. **Общая информация** В работе с опротестованиями, как правило, участвуют три стороны — эмитент со стороны пользователя, платёжная система в качестве регулирующего органа и эквайер или мерчант со стороны мерчанта. Ecommpay активно участвует в работе по опротестованиям техопераций, в которых выступает как эквайер. Это операции с использованием карт платёжных систем Mastercard и Visa в рамках карточных платежейи методов Apple Pay и Google Pay.При опротестованиях таких операций Ecommpay в установленные периоды взаимодействует со всеми сторонами, в том числе уведомляя мерчанта о решениях эмитента и платёжной системы и осуществляя требуемое движение средств мерчанта. В остальных случаях, при опротестованиях операций, выполненных через платёжную платформу Ecommpay с использованием карт других платёжных систем или в рамках других методов, мерчант ведёт работу по ним самостоятельно. В работе по опротестованиям финансовых операций могут предусматриваться разные этапы и переходы между ними, при этом количество этапов может варьироваться в зависимости от специфики платёжных систем, причин опротестований и решений, принятых сторонами. Ecommpay выделяет для такой работы четыре этапа — Chargeback \(„Чарджбэк“\), Representment \(„Репрезентмент“\), Pre-Arbitration \(„Преарбитраж“\), со стадиями attempt и response, и Arbitration \(„Арбитраж“\). При поступлении в Ecommpay информации об оформлении опротестования эта информация регистрируется в платформе и становится доступной через интерфейсы Dashboard \(в разделе **Чарджбеки**\)и Data API\([подробнее](ru_dbl_using_api.md#)\), а на заданные адреса электронной почты учётных записей Dashboard \(в профилях которых включена функция **Получать письма о чарджбэках**\) автоматически направляются уведомления с общими сведениями об опротестовании. Вместе с этим открывается первый этап работы с опротестованием — Chargeback. **Прим.:** Если по согласованию с Ecommpay со стороны мерчанта не используются учётные записи Dashboard, то при поступлении информации о новом опротестовании вместе с уведомлением на заданный адрес электронной почты мерчанта направляется файл с полными сведениями об опротестовании. После ознакомления с информацией об опротестовании его можно *принять* или *оспорить*. В первом случае работа с опротестованием завершается в пользу эмитента, а во втором продолжается до принятия итогового решения. **Прим.:** Опротестования по возвратам \(chargeback on refund\) и выплатам \(chargeback on payout\) рекомендуется принимать, поскольку они оформляются, как правило, из-за отсутствия у эмитентов возможности зачислять денежные средства на счета пользователей и оспаривание таких опротестований не решает эту проблему.При получении опротестований по возвратам и выплатам со стороны мерчанта можно предлагать пользователям обращаться к эмитентам для уточнения причин, по которым средства не поступают на их счета, и для выявления возможностей повторных попыток зачисления. Если таких возможностей у эмитентов нет, рекомендуется находить другие способы перевода средств пользователям. На этапах Representment и Pre-Arbitration стороны обмениваются дополнительными сведениями, рассматривают доводы друг друга и пытаются прийти к согласованному решению. Если стороны не находят общего решения, на последнем этапе работы — Arbitration — опротестование рассматривается арбитражной комиссией платёжной системы.В таком случае проигравшая сторона признаётся ответственной не только за возмещение оспариваемой суммы, но и за выплату денежной комиссии платёжной системе. **Схемы работы** В рамках взаимодействия с различными платёжными системами работа по опротестованиям может быть организована по-разному.Со стороны Ecommpay длятакой работыиспользуются *одна полная и две сокращённые схемы*. Полная схемавключает в себя все этапы работы с опротестованиями и используется в следующих случаях: - При работе с МПС Mastercard — для всех опротестований, кроме тех, по которым эмитент инициировал работу по сокращённой схеме. - При работе с МПС Visa — для опротестований, связанных с ошибками при обработке операций или с претензиями пользователей в отношении качества товаров и услуг, в том числе в их финансовой составляющей. Сокращённые схемы, с учётом специфики платёжных систем, включают в себя меньшее количество этапов и используются в следующих случаях: - При работе с МПС Mastercard — для опротестований, связанных с проблемами авторизации и переданных эмитентом на рассмотрение в арбитражную комиссию платёжной системы по итогам этапа Representment. В этом случае отсутствует этап Pre-Arbitration. - При работе с МПС Visa — для опротестований, связанных с проблемами авторизации или мошенничеством. В этом случае отсутствует этап Representment и первое представление опровержений со стороны мерчанта осуществляется на этапе Pre-Arbitration. С учётом этих особенностей схемы работы по опротестованиям с участием Ecommpay можно представить следующим образом. ![](images/ru_chargeback_mastercardvisa.svg) *Полная схема* ![](images/ru_chargeback_mastercard.svg) *Сокращённая схема Mastercard* ![](images/ru_chargeback_visa.svg) *Сокращённая схема Visa* **Этапы работы** *Введение* Каждый из этапов работы с опротестованием инициируется определённым образом и имеет свою специфику.В следующих пунктах описаны возможные ситуации в рамках каждого из этапов и по их итогам, а также изменения статуса опротестования и баланса мерчанта в зависимости от ситуации \(при работе с опротестованиями возвратов и выплат баланс мерчанта изменяется в обратном порядке\). *Chargeback \(„Чарджбэк“\)* Этап Chargeback инициируется эмитентом, а ответственным за принятие решения на нём является мерчант \(за исключением ситуации, когда опротестование отзывается эмитентом\).На этом этапе *мерчанту следует сообщить Ecommpay о решении по опротестованию* в течение четырёх рабочих дней, следующих за днём уведомления об опротестовании. При этом, в зависимости от ситуации и имеющихся опровержений, со стороны мерчанта можно оспаривать исходную сумму опротестования как полностью, так и частично. В целом на этапе Chargeback возможны следующие ситуации. |Ситуация|Статус| |--------|------| |Информация об опротестовании поступила в Ecommpay и была направлена мерчанту. Ожидается ответ— принять или оспорить опротестование. Баланс мерчанта уменьшается на исходную сумму опротестования. Также с мерчанта может быть удержана комиссия Ecommpay |Needs response| |Опротестование принято мерчантом — исходя из его ответа или того, что он не предоставил ответ в установленный период\(во втором случае в статусе используется уточнение expired\). Работа с опротестованием завершена в пользу эмитента. Баланс мерчанта не изменяется |Accepted by merchant| |Опротестование отозвано эмитентом.Работа с опротестованием завершена в пользу мерчанта. Баланс мерчанта увеличивается на исходную сумму опротестования |Cancelled by issuer| |Опротестование оспорено мерчантом.Ecommpay инициирует следующий этап. Баланс мерчанта не изменяется |In progress| *Representment \(„Репрезентмент“\)* В рамках полной схемы \(для МПС Mastercard и Visa\) и сокращённой схемы МПС Mastercard этап Representment инициируется Ecommpay, а ответственным за принятие решения на нём является эмитент. В рамках сокращённой схемы МПС Visa этот этап отсутствует и оспаривание начинается на этапе Pre-Arbitration.На этом этапе Ecommpay через платёжную систему направляет эмитенту ответный документ с опровержениями мерчанта и *мерчанту следует ожидать информации о решении эмитента*. В целом на этапе Representment возможны следующие ситуации. |Ситуация|Статус| |--------|------| |Опротестование полностью или частично оспорено, представлены опровержения со стороны мерчанта. Ожидается ответ эмитента— принять опровержения или продолжить работу с опротестованием. Баланс мерчанта не изменяется |In progress| |Опровержения мерчанта для частичного оспаривания опротестования приняты эмитентом. Работа с опротестованием завершена частично в пользу мерчанта и частично в пользу эмитента. Баланс мерчанта увеличивается на часть исходной суммы опротестования, поскольку эта сумма была списана с мерчанта на этапе Chargeback |Partially won| |Опровержения мерчанта приняты эмитентом.Работа с опротестованием завершена в пользу мерчанта. Баланс мерчанта увеличивается на исходную сумму опротестования |Won| |Опровержения мерчанта не приняты эмитентом или приняты лишь частично.Эмитент инициирует следующий этап. Баланс мерчанта не изменяется |In progress| *Pre-Arbitration \(„Преарбитраж“\)* Этап Pre-Arbitration состоит из двух стадий: attempt и response, на которых Ecommpay и эмитент предоставляют друг другу ответы по опротестованию, а очерёдность ответов зависит от схемы работы с опротестованием. При этом оспариваемая сумма может быть уменьшена по инициативе эмитента, если он принимает только часть опровержений мерчанта. В рамках полной схемы стадия Pre-Arbitration attempt инициируется эмитентом \(если эмитент не принял опровержения мерчанта на этапе Representment\), а ответственным за принятие решения на стадии Pre-Arbitration response является мерчант. В этом случае*мерчанту следует сообщить Ecommpay о своём решении* по опротестованию в течение установленного периода — как правило, в пределах четырёх рабочих дней, следующих за днём уведомления мерчанта о переходе на стадию attempt. В рамках сокращённой схемы МПС Mastercard этап Pre-Arbitration отсутствует, так как эмитент решает передать опротестование на рассмотрение арбитражной комиссии по итогам этапа Representment. В рамках сокращённой схемы МПС Visa стадия Pre-Arbitration attempt инициируется Ecommpay, а ответственными за принятие решений на стадии Pre-Arbitration response являются эмитент и мерчант. В этом случае,если эмитент не принял опроверженияна стадии Pre-Arbitration response, *мерчанту следует сообщить Ecommpay о своём решении* по дальнейшим действиям — принять опротестование или передать его на рассмотрение арбитражной комиссии. На принятие этого решения, как правило, отводятся один-два рабочих дня, следующих за днём уведомления мерчанта о решении эмитента. **Прим.:** Информация о периодах, отводимых на принятие решений мерчантом, отображается в карточках опротестований интерфейса Dashboard или, если по согласованию с Ecommpay со стороны мерчанта не используются учётные записи Dashboard, указывается специалистами Ecommpay по работе с опротестованиями в уведомлениях, направляемых на заданный адрес электронной почты мерчанта. В рамках полной схемы на этапе Pre-Arbitration возможны следующие ситуации. |Полная схема. Ситуация|Статус| |----------------------|------| |*Стадия Pre-Arbitration attempt*| |Опровержения, представленные на этапе Representment, не приняты эмитентом или приняты лишь частично. Информация об этом направлена мерчанту. Ожидается ответ— принять или продолжить оспаривать опротестование. Баланс мерчанта не изменяется |In progress| |*Стадия Pre-Arbitration response*| |Получен ответ мерчанта\(либо истёк период ожидания и опротестование признаётся принятым\). Баланс мерчанта не изменяется |In progress| |Опротестование принято мерчантом.Работа с опротестованием завершена в пользу эмитента. Баланс мерчанта не изменяется, так как исходная сумма опротестования уже была списана с мерчанта на этапе Chargeback |Accepted by merchant| |Опротестование оспорено мерчантом. Ожидается ответ эмитента— принять опровержения или передать опротестование на рассмотрение в арбитражную комиссию платёжной системы. Баланс мерчанта не изменяется |In progress| |Опровержения частично приняты эмитентом и мерчант согласился с таким решением.Работа с опротестованием завершена частично в пользу мерчанта и частично в пользу эмитента. Баланс мерчанта увеличивается на часть оспариваемой суммы, поскольку исходная сумма опротестования была списана с мерчанта на этапе Chargeback |Partially won| |Опротестование оспорено мерчантом и опровержения приняты эмитентом.Работа с опротестованием завершена в пользу мерчанта. Баланс мерчанта увеличивается на исходную сумму опротестования |Won| |Опротестование оспорено мерчантом и опровержения не приняты эмитентом. Ожидается передача опротестования на рассмотрение в арбитражную комиссию платёжной системы\(эту передачу выполняет эмитент\). Баланс мерчанта не изменяется |In progress| В рамках сокращённой схемы МПС Visa на этапе Pre-Arbitration возможны следующие ситуации. |Сокращённая схема Visa. Ситуация|Статус| |--------------------------------|------| |*Стадия Pre-Arbitration attempt*| |Опротестование оспорено и представлены опровержения со стороны мерчанта. Ожидается ответ эмитента— принять опровержения или продолжить работу с опротестованием. Баланс мерчанта не изменяется |In progress| |*Стадия Pre-Arbitration response*| |Получен ответ эмитента. Баланс мерчанта не изменяется |In progress| |Опровержения частично приняты эмитентом и мерчант согласился с таким решением.Работа с опротестованием завершена частично в пользу мерчанта и частично в пользу эмитента. Баланс мерчанта увеличивается на часть оспариваемой суммы, поскольку исходная сумма опротестования была списана с мерчанта на этапе Chargeback |Partially won| |Опровержения приняты эмитентом.Работа с опротестованием завершена в пользу мерчанта. Баланс мерчанта увеличивается на исходную сумму опротестования |Won| |Опровержения не приняты эмитентом. Ожидается ответ мерчанта— принять опротестование или передать его на рассмотрение в арбитражную комиссию. Баланс мерчанта не изменяется |In progress| |Опротестование принято мерчантом — исходя из его ответа или того, что он не предоставил ответ в установленный период.Работа с опротестованием завершена в пользу эмитента. Баланс мерчанта не изменяется, так как исходная сумма опротестования уже была списана с мерчанта на этапе Chargeback |Accepted by merchant| |Опротестование оспаривается мерчантом. Ожидается передача опротестования на рассмотрение в арбитражную комиссию платёжной системы\(эту передачу выполняет Ecommpay\). Баланс мерчанта не изменяется |In progress| *Arbitration \(„Арбитраж“\)* В рамках полной схемы \(для МПС Mastercard и Visa\) и сокращённой схемы МПС Mastercard этап Arbitration инициируется эмитентом \(в этом случае специалисты Ecommpay уведомляют мерчанта о том, что этап был инициирован\), а в рамках сокращённой схемы МПС Visa — Ecommpay по согласованию с мерчантом. Ответственной за принятие решения на этапе Arbitration является арбитражная комиссия платёжной системы.На этом этапе *мерчанту следует ожидать решения* арбитражной комиссии. Арбитражная комиссия приступает к рассмотрению опротестования по истечении подготовительного периода— семи \(при работе с МПС Visa\) или десяти \(при работе с МПС Mastercard\) календарных дней. В течение этого периода и далее до вынесения итогового решения мерчант может запросить у Ecommpay снятие опротестования с рассмотрения.Однако следует учитывать, что такое снятие ведёт к принятию опротестования и взиманию денежной комиссии платёжной системы за проигрыш спора. С другой стороны, до вынесения итогового решения эмитент также может закончить работу с опротестованием, приняв представленные опровержения. При рассмотрении опротестования арбитражной комиссией учитывается только та сумма, по которой стороны не пришли к соглашению и перешли на этап Arbitration. Например, если оспариваемая сумма изначально составляла 900 USD и в процессе спора была уменьшена до 600 USD по инициативе мерчанта или эмитента, то на этапе Arbitration будет рассматриваться сумма 600 USD, которая в результате может быть возмещена одной из сторон или разделена между ними по решению арбитражной комиссии платёжной системы. По итогам этапа Arbitration с мерчанта могут списываться денежные комиссии платёжной системы: - при снятии опротестования с рассмотрения по просьбе мерчанта; - при принятии решения в пользу эмитента \(в том числе частично\); - при выявлении нарушений со стороны мерчанта \(к таким нарушениям могут относиться,в частности,нарушения правил платёжной системы касательно использования платёжных данных пользователя\). **Прим.:** Для уточнения информации о денежных комиссиях, взимаемых платёжными системами в отдельных случаях, а также о возможных нарушениях, облагаемых комиссиями, можно обращаться к специалистам Ecommpay по работе с опротестованиями \(через электронную почту, указывая курирующего менеджера в числе адресатов\). Адрес их электронной почты можно найти в карточках опротестований интерфейса Dashboard. В целом на этапе Arbitration возможны следующие ситуации. |Ситуация|Статус| |--------|------| |Ожидается решение арбитражной комиссии.При этом опротестование может быть снято с рассмотрения по просьбе мерчанта или эмитента до вынесения решения со стороны комиссии. Баланс мерчанта не изменяется |In progress| |Опротестование снято с рассмотрения по просьбе мерчантадо вынесения решения арбитражной комиссией. Работа с опротестованием завершена в пользу эмитента. Баланс мерчанта уменьшается на сумму комиссии платёжной системы, поскольку исходная сумма опротестования уже была списана с мерчанта на этапе Chargeback |Accepted by merchant| |По решению арбитражной комиссии работа с опротестованием завершена в пользу эмитента. Баланс мерчанта уменьшается на сумму комиссии платёжной системы, поскольку исходная сумма опротестования уже была списана с мерчанта на этапе Chargeback |Lost| |По решению арбитражной комиссии работа с опротестованием завершена частично в пользу мерчанта и частично в пользу эмитента. Баланс мерчанта увеличивается на часть оспариваемой суммы, поскольку полная оспариваемая сумма была списана с мерчанта на этапе Chargeback. При этом сумма комиссии платёжной системы, в зависимости от решения арбитражной комиссии, может быть удержана только с одной из сторон или же разделена между сторонами |Partially won| |Опротестование снято с рассмотрения по просьбе эмитента или, по решению арбитражной комиссии, работа с опротестованием завершена в пользу мерчанта. Баланс мерчанта увеличивается на оспариваемую сумму |Won| ## Как можно узнать статус опротестования? {#section_nxx_tv4_p5b .section} **Кратко:** информацию об опротестованиях, разбираемых с участием Ecommpay, можно получать через интерфейсы Dashboard и Data API и, в отдельных случаях, через электронную почту. Актуальную информацию об опротестованиях, в том числе об их статусах, можно получать через интерфейсы Dashboard\(используя инструменты разделов **Чарджбеки** и **Отчёты**\) и Data API\([подробнее](ru_dbl_using_api.md#)\). Кроме того, информация об опротестованиях может направляться специалистами Ecommpay на заданный адрес электронной почты мерчанта. Это актуально в следующих случаях: - когда, по согласованию с Ecommpay, со стороны мерчанта не используются учётные записи Dashboard; - когда опротестование передаётся на рассмотрение в арбитражную комиссию; - когда работа с опротестованием завершается в силу того, что арбитражная комиссия платёжной системы приняла решение полностью или частично в пользу эмитента. В платёжной платформе Ecommpay для опротестований используются следующие статусы. |Needs response|Промежуточный статус. Ожидается ответ мерчанта на опротестование| |In progress|Промежуточный статус. Идёт работа с опротестованием, итоговое решение не принято| |Accepted by merchant \(expired\)|Итоговый статус. Мерчант не предоставил первичный ответ по опротестованию в установленный период. Работа с опротестованием завершена в пользу эмитента| |Accepted by merchant|Итоговый статус. Мерчант принял опротестование и отказался от его дальнейшего оспаривания. Работа с опротестованием завершена в пользу эмитента| |Lost|Итоговый статус. Арбитражная комиссия приняла решение в пользу эмитента. Работа с опротестованием завершена в пользу эмитента| |Partially won|Итоговый статус. Работа с опротестованием завершена частично в пользу мерчанта и частично в пользу эмитента по одной из следующих причин: ◆ мерчант оспорил часть исходной суммы опротестования и эмитент принял опровержения мерчанта ◆ опровержения мерчанта на исходную сумму опротестования частично приняты эмитентом и мерчант согласился с таким решением ◆ арбитражная комиссия приняла решение частично в пользу мерчанта и частично в пользу эмитента | |Won|Итоговый статус. Эмитент согласился с опровержениями или арбитражная комиссия приняла решение в пользу мерчанта. Работа с опротестованием завершена в пользу мерчанта| |Cancelled by issuer|Итоговый статус. Эмитент отозвал опротестование. Работа с опротестованием завершена в пользу мерчанта| ## Что такое chargeback reversal? {#section_t4k_dn5_p5b .section} **Кратко:** это термин, используемый для обозначения ситуаций, когда эмитент отзывает опротестование. *Chargeback reversal* — это отзы́в опротестования эмитентом до первичного ответа на это опротестование со стороны мерчанта.В результате такого отзы́ва баланс мерчанта увеличивается \(при опротестовании оплаты\) или уменьшается \(при опротестовании возврата или выплаты\) на исходную сумму опротестования, а опротестованию присваивается статус Cancelled by issuer. Реагировать на опротестование в таком случае не требуется. ## Что такое chargeback on refund и chargeback on payout? {#section_djm_gn5_p5b .section} **Кратко:** это названия опротестований по операциям возвратов и выплат. *Chargeback on refund* и *chargeback on payout* — это опротестования возврата и выплаты соответственно. Они оформляются эмитентами при отсутствии возможности зачисления денежных средств на счета держателей карт, например из-за закрытия этих счетов или специфических региональных требований. В результате таких опротестований средства, ранее списанные для возвратов и выплат, возвращаются мерчанту. Поскольку причины опротестований возвратов и выплат определяются на стороне эмитентов, предотвратить подобные ситуации на стороне мерчанта нельзя.Однако, при получении таких опротестований со стороны мерчанта можно предлагать пользователям обращаться к эмитентам для уточнения причин, по которым средства не поступают на их счета, и для выявления возможностей повторных попыток зачисления. Если таких возможностей у эмитентов нет, рекомендуется находить другие способы перевода средств пользователям. ## Можно ли предотвратить опротестование оплаты, вернув средства пользователю, и почему эмитенты могут оформлять опротестования даже после выполнения возвратов? {#section_ahy_kn5_p5b .section} **Кратко:** возвраты помогают избегать опротестований, но всё же не избавляют от них полностью, поскольку в некоторых случаях у эмитентов могут быть причины оспаривать оплаты даже после выполнения возвратов по ним. Оперативный возврат средств пользователю при выявлении неуместного списания\(например, при получении от пользователя жалобы о том, что средства были списаны, но товар не был получен или услуга не была оказана\) может помочь избежать опротестования, но всё-таки не исключает такой возможности.Если, несмотря на возврат, эмитент оформил опротестование оплаты, фактическое подтверждение того, что по ней был выполнен возврат, может использоваться при оспаривании опротестования и повышает вероятность решения спорной ситуации в пользу мерчанта, хотя и не гарантирует такой исход. Эмитент может оформить опротестование платежа, по которому уже был выполнен возврат денежных средств, по разным причинам, в том числе по следующим: - Средства ещё не поступили на счёт держателя карты и эмитент не знает об инициировании возврата. При возврате средства должны поступать на счёт в установленный платёжной системой период \(как правило, он составляет до 15 календарных дней\). Однако пользователь может обратиться к эмитенту до поступления средств и эмитент может оформить опротестование из-за отсутствия информации о возврате. - Не удалось соотнести операцию и возврат. Эмитент может проверить информацию по счёту держателя карты, не соотнести возврат с оплатой и оформить опротестование по одной из следующих причин: - Проведено несколько оплат на разные суммы и выполнен возврат по одной или нескольким из этих оплат. - Суммы оплаты и возврата не совпадают в связи с разницей валютных курсов. Если валюта счёта держателя карты отличается от валюты платежа, суммы оплаты и возврата могут не совпадать в связи с разницей курсов конвертации на дату проведения платежа и на дату выполнения возврата. - Эмитент посчитал, что возврат не относится к опротестованной операции. В этом случае эмитент должен обосновать причины такого решения. Чтобы избегать подобных ситуаций, важно незамедлительно оповещать пользователя о состоянии платежа, правилах возврата и сроках поступления средств.Если опротестование было оформлено несмотря на выполненный ранее возврат, в ответ на такое опротестование рекомендуется предоставить Ecommpay информацию, подтверждающую выполнение возврата. Для дополнительных консультаций по действиям в таких случаях можно обращаться к курирующему менеджеру или специалистам Ecommpay по работе с опротестованиями. \(Адрес их электронной почты можно найти в карточках опротестований интерфейса Dashboard или запросить у курирующего менеджера, а при обращениях к специалистам по работе с опротестованиями следует указывать курирующего менеджера в числе адресатов.\) ## Стоит ли выполнять возврат денежных средств по уже оспариваемой операции? {#section_cyj_nn5_p5b .section} **Кратко:** выполнять возврат по оспариваемой операции не рекомендуется. В общем случае после получения информации об опротестовании оплаты выполнять возврат по ней не рекомендуется. Это связано с тем, что при поступлении в Ecommpay информации об оформлении нового опротестования, независимо от решения мерчанта \(принимать или оспаривать это опротестование\), баланс мерчанта уменьшается на исходную сумму опротестования и эта сумма возвращается эмитенту, а затем \(если работа с опротестованием завершается в пользу эмитента\) — пользователю. Поэтому при попытке выполнить возврат по оспариваемой операции он автоматически отклоняется на стороне платформы— чтобы избежать двойного списания. Вместе с тем, если, несмотря на риск двойного списания, со стороны мерчанта есть вопросы по возврату средств по оспариваемой операции, с такими вопросами можно обращаться к курирующему менеджеру Ecommpay. **На уровень выше:**[FAQ](ru_faq.md) --- # Справочники {#ru_directory} раздел с глоссарием и различными справочниками, которые актуальны при работе с платформой В этом разделе представлен глоссарий с терминами, используемыми в документации, а также справочная информация о кодах языков, валют, платёжных методов, поддерживаемых в интерфейсах Dashboard и Payment Page, а также кодах стран, регионов и Electronic Commerce Indicator. - [Глоссарий](ru_glossary.md#) - [Коды языков](ru_language_codes.md) - [Коды валют](ru_currency_codes.md) - [Коды платёжных методов](ru_pm_codes.md) - [Коды брендов платёжных карт](ru_card_codes.md) - [Коды стран](ru_country_codes.md) - [Коды регионов карточных платежей](ru_region_codes.md) - [Номера тестовых карт](ru_test_cards.md) - [Индикаторы ECI](ru_ECI_codes.md) - **[Глоссарий](ru_glossary.md#)** справочник с определениями терминов, используемых в платформе и документации - **[Коды языков](ru_language_codes.md)** справочник с кодами языков в формате alpha-2 в соответствии со стандартом ISO 639 - **[Коды валют](ru_currency_codes.md)** справочник с кодами валют в формате alpha-3 в соответствии со стандартом ISO 4217 - **[Коды платёжных методов](ru_pm_codes.md)** справочник с кодами поддерживаемых платёжных методов - **[Коды брендов платёжных карт](ru_card_codes.md)** справочник с внутренними кодами брендов платёжных карт, которые могут использоваться при работе с платформой - **[Коды стран](ru_country_codes.md)** справочник с кодами стран в формате alpha-2 в соответствии со стандартом ISO 3166-1 - **[Коды регионов карточных платежей](ru_region_codes.md)** справочник с кодами регионов, применяемых при проведении через платформу Ecommpay платежей с использованием карт платёжных систем Mastercard и Visa - **[Номера тестовых карт](ru_test_cards.md)** справочник с информацией о специализированных номерах карт, которые можно использовать для тестирования различных сценариев проведения карточных платежей - **[Индикаторы ECI](ru_ECI_codes.md)** справочник с кодами Electronic Commerce Indicator, применяемыми со стороны различных платёжных систем, чтобы фиксировать информацию о результатах аутентификации пользователей с применением протокола 3‑D Secure --- # Коды языков {#ru_language_codes} справочник с кодами языков в формате alpha-2 в соответствии со стандартом ISO 639 При работе с различными интерфейсами платёжной платформы Ecommpay могут использоваться буквенные коды языков. В частности, эти коды могут указываться при вызове Payment Page для открытия платёжной формы на определённом языке \([подробнее](ru_PP_WigetLanguages.md#section_bb1_jft_kqb)\). В общем случае коды языков приводятся в формате alpha-2 стандарта [ISO 639](https://www.iso.org/ru/iso-639-language-codes.html), а при исключениях, например когда необходимо использовать языки, не включённые в этот стандарт, согласовываются и применяются дополнительные коды. В следующей таблице приведены коды языков в формате alpha-2 в соответствии со стандартом ISO 639. |Код|Язык| |:-:|----| |`aa`|Афарский| |`ab`|Абхазский| |`ae`|Авестийский| |`af`|Африкаанс| |`ak`|Акан| |`am`|Амхарский| |`an`|Арагонский| |`ar`|Арабский| |`as`|Ассамский| |`av`|Аварский| |`ay`|Аймара| |`az`|Азербайджанский| |`ba`|Башкирский| |`be`|Белорусский| |`bg`|Болгарский| |`bh`|Бихарские языки| |`bi`|Бислама| |`bm`|Бамбара| |`bn`|Бенгальский| |`bo`|Тибетский| |`br`|Бретонский| |`bs`|Боснийский| |`ca`|Каталанский| |`ce`|Чеченский| |`ch`|Чаморро| |`co`|Корсиканский| |`cr`|Кри| |`cs`|Чешский| |`cv`|Чувашский| |`cy`|Валлийский| |`da`|Датский| |`de`|Немецкий| |`dv`|Дивехи \(дхивехи, мальдивский\)| |`dz`|Дзонг-кэ| |`ee`|Эве| |`el`|Греческий| |`en`|Английский| |`eo`|Эсперанто| |`es`|Испанский| |`et`|Эстонский| |`eu`|Баскский| |`fa`|Персидский| |`ff`|Фулах| |`fi`|Финский| |`fj`|Фиджи| |`fo`|Фарерский| |`fr`|Французский| |`fy`|Фризский| |`ga`|Ирландский| |`gd`|Гэльский \(шотландский\)| |`gl`|Галисийский| |`gn`|Гуарани| |`gu`|Гуджарати| |`gv`|Мэнский| |`ha`|Хауса| |`he`|Иврит| |`hi`|Хинди| |`ho`|Хири-моту| |`hr`|Хорватский| |`ht`|Гаитянский креольский| |`hu`|Венгерский| |`hy`|Армянский| |`hz`|Гереро| |`ia`|Интерлингва| |`id`|Индонезийский| |`ie`|Интерлингве \(окциденталь\)| |`ig`|Игбо| |`ii`|Носу \(сычуаньский и\)| |`ik`|Инупиак| |`io`|Идо| |`is`|Исландский| |`it`|Итальянский| |`iu`|Инуктитут| |`ja`|Японский| |`jv`|Яванский| |`ka`|Грузинский| |`kg`|Конго| |`ki`|Кикуйю| |`kj`|Кваньяма| |`kk`|Казахский| |`kl`|Гренландский| |`km`|Кхмерский| |`kn`|Каннада| |`ko`|Корейский| |`kr`|Канури| |`ks`|Кашмирский| |`ku`|Курдский| |`kv`|Коми| |`kw`|Корнский| |`ky`|Кыргызский \(киргизский\)| |`la`|Латинский| |`lb`|Люксембургский| |`lg`|Ганда| |`li`|Лимбургский| |`ln`|Лингала| |`lo`|Лаосский| |`lt`|Литовский| |`lu`|Луба-катанга| |`lv`|Латышский| |`mg`|Малагасийский| |`mh`|Маршалльский| |`mi`|Маори| |`mk`|Македонский| |`ml`|Малаялам| |`mn`|Монгольский| |`mr`|Маратхи| |`ms`|Малайский| |`mt`|Мальтийский| |`my`|Бирманский| |`na`|Науруанский| |`nb`|Норвежский букмол| |`nd`|Северный ндебеле| |`ne`|Непальский| |`ng`|Ндунга| |`nl`|Нидерландский| |`nn`|Новонорвежский| |`no`|Норвежский| |`nr`|Южный ндебеле| |`nv`|Навахо| |`ny`|Ньянджа| |`oc`|Окситанский| |`oj`|Оджибве| |`om`|Оромо| |`or`|Ория| |`os`|Осетинский| |`pa`|Пенджабский| |`pi`|Пали| |`pl`|Польский| |`ps`|Пушту \(пашто\)| |`pt`|Португальский| |`qu`|Кечуа| |`rm`|Романшский| |`rn`|Рунди| |`ro`|Румынский| |`ru`|Русский| |`rw`|Руанда| |`sa`|Санскрит| |`sc`|Сардинский| |`sd`|Синдхи| |`se`|Северносаамский| |`sg`|Санго| |`si`|Сингальский, синхала| |`sk`|Словацкий| |`sl`|Словенский| |`sm`|Самоанский| |`sn`|Шона| |`so`|Сомалийский| |`sq`|Албанский| |`sr`|Сербский| |`ss`|Свати| |`st`|Сесото| |`su`|Сунданский| |`sv`|Шведский| |`sw`|Суахили| |`ta`|Тамильский| |`te`|Телугу| |`tg`|Таджикский| |`th`|Тайский| |`ti`|Тигринья| |`tk`|Туркменский| |`tl`|Тагальский| |`tn`|Тсвана| |`to`|Тонганский| |`tr`|Турецкий| |`ts`|Тсонга| |`tt`|Татарский| |`tw`|Чви| |`ty`|Таитянский| |`ug`|Уйгурский| |`uk`|Украинский| |`ur`|Урду| |`uz`|Узбекский| |`ve`|Венда| |`vi`|Вьетнамский| |`vo`|Волапюк| |`wa`|Валлонский| |`wo`|Волоф| |`xh`|Коса| |`yi`|Идиш| |`yo`|Йоруба| |`za`|Чжуанский| |`zh`|Китайский| |`zu`|Зулу| **На уровень выше:**[Справочники](ru_directory.md) --- # Коды валют {#ru_currency_codes} справочник с кодами валют в формате alpha-3 в соответствии со стандартом ISO 4217 Для указания валют в платёжной платформе Ecommpay используются трёхбуквенные коды \(alpha-3\) в соответствии со стандартом [ISO 4217](https://www.iso.org/ru/iso-4217-currency-codes.html). Эти коды применяются как в программных интерфейсах \(в запросах, ответах и оповещениях\), так и в пользовательских \(включая Payment Page и Dashboard\). Также они используются и в рамках данной документации. В следующей таблице приведены коды большинства валют, которые могут быть актуальны при проведении платежей \(в формате alpha-3 в соответствии со стандартом ISO 4217:2015\), а также количество дробных разрядов, названия и регионы обращения этих валют. |Код|Дробные разряды|Валюта|Регионы| |:-:|:-------------:|------|-------| |`AED`|2|Дирхам ОАЭ|Объединённые Арабские Эмираты| |`AFN`|2|Афгани|Афганистан| |`ALL`|2|Лек|Албания| |`AMD`|2|Армянский драм|Армения| |`ANG`|2|Нидерландский антильский гульден|Кюрасао, Сен-Мартен| |`AOA`|2|Кванза|Ангола| |`ARS`|2|Аргентинское песо|Аргентина| |`AUD`|2|Австралийский доллар|Австралия, Кирибати, Кокосовые \(Килинг\) острова, Науру, Остров Норфолк, Остров Рождества, Остров Херд и острова Макдональд, Тувалу| |`AWG`|2|Арубанский флорин|Аруба| |`AZN`|2|Азербайджанский манат|Азербайджан| |`BAM`|2|Конвертируемая марка|Босния и Герцеговина| |`BBD`|2|Барбадосский доллар|Барбадос| |`BDT`|2|Така|Бангладеш| |`BGN`|2|Болгарский лев|Болгария| |`BHD`|3|Бахрейнский динар|Бахрейн| |`BIF`|0|Бурундийский франк|Бурунди| |`BMD`|2|Бермудский доллар|Бермуды| |`BND`|2|Брунейский доллар|Бруней-Даруссалам| |`BOB`|2|Боливиано|Боливия| |`BOV`|2|Мвдол|Боливия| |`BRL`|2|Бразильский реал|Бразилия| |`BSD`|2|Багамский доллар|Багамские острова| |`BTN`|2|Нгултрум|Бутан| |`BWP`|2|Пула|Ботсвана| |`BYN`|2|Белорусский рубль|Беларусь| |`BZD`|2|Белизский доллар|Белиз| |`CAD`|2|Канадский доллар|Канада| |`CDF`|2|Конголезский франк|Конго| |`CHE`|2|WIR-евро|Швейцария| |`CHF`|2|Швейцарский франк|Лихтенштейн, Швейцария| |`CHW`|2|WIR-франк|Швейцария| |`CLF`|4|Единица развития|Чили| |`CLP`|0|Чилийское песо|Чили| |`CNY`|2|Юань|Китай| |`COP`|2|Колумбийское песо|Колумбия| |`COU`|2|Единица реальной стоимости|Колумбия| |`CRC`|2|Коста-риканский колон|Коста-Рика| |`CUC`|2|Конвертируемое песо|Куба| |`CUP`|2|Кубинское песо|Куба| |`CVE`|2|Эскудо Кабо-Верде|Кабо-Верде| |`CZK`|2|Чешская крона|Чехия| |`DJF`|0|Франк Джибути|Джибути| |`DKK`|2|Датская крона|Гренландия, Дания, Фарерские острова| |`DOP`|2|Доминиканское песо|Доминиканская Республика| |`DZD`|2|Алжирский динар|Алжир| |`EGP`|2|Египетский фунт|Египет| |`ERN`|2|Накфа|Эритрея| |`ETB`|2|Эфиопский быр|Эфиопия| |`EUR`|2|Евро|Аландские острова, Андорра, Гваделупа, Майотта, Мартиника, Монако, Папский Престол, Реюньон, Сан-Марино, Сен-Бартелеми, Сен-Мартен \(французская часть\), Сент-Пьер и Микелон, Французская Гвиана, Французские Южные территории, Черногория, страны Европейского союза, кроме Болгарии, Чехии, Дании, Венгрии, Польши, Румынии и Швеции| |`FJD`|2|Доллар Фиджи|Фиджи| |`FKP`|2|Фунт Фолклендских островов|Фолклендские острова| |`GBP`|2|Фунт стерлингов|Гернси, Джерси, Остров Мэн, Соединенное Королевство Великобритании и Северной Ирландии| |`GEL`|2|Лари|Грузия| |`GHS`|2|Ганский седи|Гана| |`GIP`|2|Гибралтарский фунт|Гибралтар| |`GMD`|2|Даласи|Габмия| |`GNF`|0|Гвинейский франк|Гвинея| |`GTQ`|2|Кетсаль|Гватемала| |`GYD`|2|Гайанский доллар|Гайана| |`HKD`|2|Гонконгский доллар|Гонконг| |`HNL`|2|Лемпира|Гондурас| |`HTG`|2|Гурд|Гаити| |`HUF`|2|Форинт|Венгрия| |`IDR`|2|Рупия|Индонезия| |`ILS`|2|Новый израильский шекель|Израиль| |`INR`|2|Индийская рупия|Бутан, Индия| |`IQD`|3|Иракский динар|Ирак| |`IRR`|2|Иранский риал|Иран| |`ISK`|0|Исландская крона|Исландия| |`JMD`|2|Ямайский доллар|Ямайка| |`JOD`|3|Иорданский динар|Иордания| |`JPY`|0|Иена|Япония| |`KES`|2|Кенийский шиллинг|Кения| |`KGS`|2|Сом|Кыргызстан| |`KHR`|2|Риель|Камбоджа| |`KMF`|0|Коморский франк|Коморы| |`KPW`|2|Северокорейская вона|Корея \(народно-демократическая республика\)| |`KRW`|0|Вона|Корея \(республика\)| |`KWD`|3|Кувейтский динар|Кувейт| |`KYD`|2|Доллар Островов Кайман|Острова Кайман| |`KZT`|2|Тенге|Казахстан| |`LAK`|2|Лаосский кип|Лаос| |`LBP`|2|Ливанский фунт|Ливан| |`LKR`|2|Шри-Ланкийская рупия|Шри-Ланка| |`LRD`|2|Либерийский доллар|Либерия| |`LSL`|2|Лоти|Лесото| |`LYD`|3|Ливийский динар|Ливия| |`MAD`|2|Марокканский дирхам|Западная Сахара, Марокко| |`MDL`|2|Молдавский лей|Молдова| |`MGA`|2|Малагасийский ариари|Мадагаскар| |`MKD`|2|Денар|Северная Македония| |`MMK`|2|Кьят|Мьянма| |`MNT`|2|Тугрик|Монголия| |`MOP`|2|Патака|Макао| |`MRU`|2|Угия|Мавритания| |`MUR`|2|Маврикийская рупия|Маврикий| |`MVR`|2|Руфия|Мальдивы| |`MWK`|2|Малавийская квача|Малави| |`MXN`|2|Мексиканское песо|Мексика| |`MXV`|2|Мексиканская инверсионная единица|Мексика| |`MYR`|2|Малайзийский ринггит|Малайзия| |`MZN`|2|Мозамбикский метикал|Мозамбик| |`NAD`|2|Доллар Намибии|Намибия| |`NGN`|2|Найра|Нигерия| |`NIO`|2|Золотая кордоба|Никарагуа| |`NOK`|2|Норвежская крона|Норвегия, Остров Буве, Шпицберген и Ян-Майен| |`NPR`|2|Непальская рупия|Непал| |`NZD`|2|Новозеландский доллар|Ниуэ, Новая Зеландия, Острова Кука, Питкерн, Токелау| |`OMR`|3|Оманский риал|Оман| |`PAB`|2|Бальбоа|Панама| |`PEN`|2|Соль|Перу| |`PGK`|2|Кина|Папуа Новая Гвинея| |`PHP`|2|Филиппинское песо|Филиппины| |`PKR`|2|Пакистанская рупия|Пакистан| |`PLN`|2|Злотый|Польша| |`PYG`|0|Гуарани|Парагвай| |`QAR`|2|Катарский риал|Катар| |`RON`|2|Румынский лей|Румыния| |`RSD`|2|Сербский динар|Сербия| |`RUB`|2|Российский рубль|Российская Федерация| |`RWF`|0|Франк Руанды|Руанда| |`SAR`|2|Саудовский риял|Саудовская Аравия| |`SBD`|2|Доллар Соломоновых Островов|Соломоновы Острова| |`SCR`|2|Сейшельская рупия|Сейшельские Острова| |`SDG`|2|Суданский фунт|Судан| |`SEK`|2|Шведская крона|Швеция| |`SGD`|2|Сингапурский доллар|Сингапур| |`SHP`|2|Фунт Святой Елены|Остров Святой Елены| |`SLE`|2|Леоне|Сьерра-Леоне| |`SOS`|2|Сомалийский шиллинг|Сомали| |`SRD`|2|Суринамский доллар|Суринам| |`SSP`|2|Южносуданский фунт|Южный Судан| |`STN`|2|Добра|Сан-Томе и Принсипи| |`SVC`|2|Сальвадорский колон|Эль-Сальвадор| |`SYP`|2|Сирийский фунт|Сирийская Арабская Республика| |`SZL`|2|Лилангени|Эсватини| |`THB`|2|Бат|Таиланд| |`TJS`|2|Сомони|Таджикистан| |`TMT`|2|Новый туркменский манат|Туркменистан| |`TND`|3|Тунисский динар|Тунис| |`TOP`|2|Паанга|Тонга| |`TRY`|2|Турецкая лира|Турция| |`TTD`|2|Доллар Тринидада и Тобаго|Тринидад и Тобаго| |`TWD`|2|Новый тайваньский доллар|Тайвань| |`TZS`|2|Танзанийский шиллинг|Танзания| |`UAH`|2|Гривна|Украина| |`UGX`|0|Угандийский шиллинг|Уганда| |`USD`|2|Доллар США|Американское Самоа, Бонэйр, Британская территория в Индийском Океане, Виргинские острова \(Британские\), Виргинские острова \(США\), Гаити, Гуам, Малые Тихоокеанские Отдаленные острова Соединенных Штатов, Маршалловы острова, Микронезия \(федеративные штаты\), острова Тёркс и Кайкос, Палау, Панама, Пуэрто-Рико, Северные Марианские острова, Соединённые Штаты Америки, Тимор-Лесте, Эквадор, Эль-Сальвадор| |`UYI`|0|Уругвайское песо в индексированных единицах|Уругвай| |`UYU`|2|Уругвайское песо|Уругвай| |`UYW`|4|Пенсионная единица \(Уругвай\)|Уругвай| |`UZS`|2|Узбекский сум|Узбекистан| |`VED`|2|Боливар Соберано|Венесуэла| |`VES`|2|Боливар|Венесуэла| |`VND`|0|Донг|Вьетнам| |`VUV`|0|Вату|Вануату| |`WST`|2|Тала|Самоа| |`XAF`|0|Франк КФА BEAC|Габон, Камерун, Конго, Центрально-Африканская Республика, Чад, Экваториальная Гвинея| |`XCD`|2|Восточно-карибский доллар|Ангилья, Антигуа и Барбуда, Гренада, Доминика, Монтсеррат, Сент-Винсент и Гренадины, Сент-Китс и Невис, Сент-Люсия| |`XOF`|0|Франк КФА BCEAO|Бенин, Буркина-Фасо, Гвинея-Биссау, Кот-д'Ивуар, Мали, Нигер, Сенегал, Того| |`XPF`|0|Франк КФП|Новая Каледония, Французская Полинезия, Уоллис и Футуна| |`YER`|2|Йеменский риал|Йемен| |`ZAR`|2|Рэнд|Лесото, Намибия, Южно-Африканская Республика| |`ZMW`|2|Замбийская квача|Замбия| |`ZWL`|2|Доллар Зимбабве|Зимбабве| **На уровень выше:**[Справочники](ru_directory.md) --- # Коды платёжных методов {#ru_pm_codes} справочник с кодами поддерживаемых платёжных методов При работе с различными интерфейсами платёжной платформы Ecommpay могут использоваться служебные коды платёжных методов. Так, в запросах на открытие Payment Page коды могут использоваться для предварительного выбора метода \(в значении параметра `force_payment_method`\) и для скрытия метода из числа доступных \(в значении параметра `hide`\), при работе с интерфейсом Gate — для получения информации о доступных методах, а при работе с интерфейсом Dashboard — для инициирования возвратов и выплат. **Прим.:** При работе с Payment Page могут использоваться также служебные коды групп платёжных методов. Они позволяют задавать предварительно выбранными методы конкретной группы через указание её кода в значении параметра `force_payment_group`. К таким кодам относится `openbanking` для выбора методов группы Open Banking. Важно учитывать, что коды одного и того же метода для разных интерфейсов могут различаться. В следующей таблице приведены коды, применяемые в работе с интерфейсами Payment Page, Gate и Dashboard.При этом часть кодов, указанных в столбце **Gate, Dashboard**, может быть актуальна только для работы с Gate API. Такие коды отмечены записью Gate only. С вопросами по отдельным кодам и работе с ними можно обращаться к специалистам технической поддержки Ecommpay. |Платёжный метод|Payment Page|Gate,Dashboard| |---------------|------------|--------------| |[Классические карточные платежи](ru_pm_card_payments.md)|`card`|- `card` \(при использовании номера карты\) - `card-token` \(при использовании токена карты\) | |[Alipay](pm_alipay.md#)|`alipay`|`wallet/alipay`| |[Apple Pay](pm_applepay.md#)|- `card` \(при прямом использовании карт\) - `apple_pay_core` \(при задействовании сервиса Apple Pay\) |`etoken`| |[AstroPay](pm_astropay.md#)|`astropay`|`wallet/astropay`| |[Indonesian Virtual Accounts](pm_indonesia_va.md#)|`indonesia-va`|`banks/indonesia`| |[Bancontact](pm_bancontact.md#)|`bancontact`|`bancontact`| |[Bancomat Pay](pm_bancomatpay.md#)|`bancomatpay`|`wallet/bancomatpay`| |[Banks of Hong Kong](pm_hk_banks.md#)|–|`banks/hk`| |[Banks of the Philippines](pm_philippines.md#)|`online-philippines-banks`|`banks/philippines`| |[Blik](pm_blik.md#)|`blik`|`blik`| |[Boost Wallet](pm_boost.md#)|`boost`|`wallet/boost` Gate only| |[Brazil Online Banking](pm_brazil_ob.md#)|`online-brazil-banks`|`banks/brazil`| |[Buy Now Pay Later](pm_bnpl.md#)|`bnpl-humm`|`bnpl/humm`Gate only| |[Chile Online Banking](pm_chile_ob.md#)|`online-chile-banks`|`banks/chile`| |[China UnionPay](pm_unionpay.md#)|`cup-union`|`unionpay`| |[Click to Pay](pm_clicktopay.md#)|`etoken-click2pay`|`etoken-click2pay`| |[Coins.ph](pm_coinsph.md#)|`coinsph-wallet`|`wallet/coinsph`| |[DOKU Wallet](pm_doku.md#)|`doku`|`wallet/doku`| |[Ecuador Online Banking](pm_ecuador_ob.md#)|`online-ecuador-banks`|`banks/ecuador`| |[EPS](pm_eps.md#)|`eps`|`bank-transfer/eps` Gate only| |[GCash](pm_gcash.md#)|`gcash-wallet`|`wallet/gcash`| |[Google Pay](pm_googlepay.md#)|- `card` \(при прямом использовании карт\) - `google_pay_host` \(при задействовании сервиса Google Pay\) |- `card` \(при прямом использовании карт\) - `google-pay` \(при задействовании сервиса Google Pay\) | |[GrabPay](pm_grabpay.md#)|`grabpay-wallet`|`wallet/grabpay`| |[Hong Kong FPS QR](pm_hk_qr.md#)|`hk-qr`|`banks/hk-qr` Gate only| |[Indonesian Online Banking](pm_indonesia.md#)|`online-indonesian-banks`|`banks/indonesia`| |[Indonesian Virtual Accounts](pm_indonesia_va.md#)|`indonesia-va`|`banks/indonesia`Gate only| |[iDEAL \| Wero](pm_ideal.md#)|`ideal`|`online-banking/ideal`| |[Malaysian Online Banking](pm_malaysia.md#)|`online-malaysian-banks`|`banks/malaysia`| |[Maya](pm_maya.md#)|`paymaya-wallet`|`wallet/paymaya`| |[MBWay](pm_mbway.md#)|`mbway`|`wallet/mbway`| |[Mexico Online Banking](pm_mexico_ob.md#)|`online-mexico-banks`|`banks/mexico`| |[MoMo Wallet](pm_momoqr.md#)|`momopay`|`momopay` Gate only| |[Multibanсo](pm_multibanco.md#)|`multibanco`|`bank-transfer/multibanco`Gate only| |[MyBank](pm_mybank.md#)|`mybank`|`banks/mybank`| |[Neteller](pm_neteller.md#)|`neteller-wallet`|`wallet/neteller`| |[Open Banking in Austria](pm_austria.md#)|`online-austrian-banks`|`banks/austria` Gate only| |[Open Banking in Belgium](pm_belgium.md#)|`online-belgian-banks`|`banks/belgium` Gate only| |[Open Banking in Denmark](pm_denmark.md#)|`online-danish-banks`|`banks/denmark` Gate only| |[Open Banking in Estonia](pm_estonia.md#)|`online-estonian-banks`|`banks/estonia` Gate only| |[Open Banking in Finland](pm_finland.md#)|`online-finnish-banks`|`banks/finland` Gate only| |[Open Banking in France](pm_france.md#)|`online-french-banks`|`banks/france` Gate only| |[Open Banking in Germany](pm_germany.md#)|`online-german-banks`|`banks/germany` Gate only| |[Open Banking in Hungary](pm_hungary.md#)|`online-hungarian-banks`|`banks/hungary` Gate only| |[Open Banking in Ireland](pm_ireland.md#)|`online-irish-banks`|`banks/ireland` Gate only| |[Open Banking in Italy](pm_italy.md#)|`online-italian-banks`|`banks/italy` Gate only| |[Open Banking in Latvia](pm_latvia.md#)|`online-latvian-banks`|`banks/latvia` Gate only| |[Open Banking in Lithuania](pm_lithuania.md#)|`online-lithuanian-banks`|`banks/lithuania` Gate only| |[Open Banking in Luxembourg](pm_luxembourg.md#)|`online-luxembourg-banks`|`banks/luxembourg` Gate only| |[Open Banking in the Netherlands](pm_netherlands.md#)|`online-netherlands-banks`|`banks/netherlands` Gate only| |[Open Banking in Norway](pm_norway.md#)|`online-norwegian-banks`|`banks/norway` Gate only| |[Open Banking in Poland](pm_poland.md#)|`online-polish-banks`|`banks/poland` Gate only| |[Open Banking in Portugal](pm_portugal.md#)|`online-portuguese-banks`|`banks/portugal` Gate only| |[Open Banking in Romania](pm_romania.md#)|`online-romanian-banks`|`banks/romania` Gate only| |[Open Banking in Spain](pm_spain.md#)|`online-spanish-banks`|`banks/spain` Gate only| |[Open Banking in Sweden](pm_sweden.md#)|`online-swedish-banks`|`banks/sweden` Gate only| |[Open Banking in the UK](pm_uk.md#)|`uk`|`banks/uk` Gate only| |[OVO Wallet](pm_ovo.md#)|`ovo`|`wallet/ovo`| |[PayPal](pm_paypal.md#)|`paypal-wallet`|`wallet/paypal`| |[PayPal Pay Later](pm_paypal_pay_later.md#)|`paypal-wallet`|`wallet/paypal`| |[Peru Online Banking](pm_peru_ob.md#)|`online-peru-banks`|`banks/peru`| |[Philippines Over the Counter & ATM](pm_philippines_atm.md#)|`philippines-atm`|`atm/philippines`Gate only| |[PIX](pm_pix.md#)|`pix`|`pix`| |[Promptpay](pm_promptpay.md#)|`promptpay`|`banks/promptpay`Gate only| |[Przelewy24](pm_przelewy.md#)|`przelewy24`|`online-banking/przelewy24`| |[QRIS](pm_qris.md#)|`indonesia-qr`|`banks/indonesia-qr` Gate only| |[QR Ph](pm_qrph.md#)|`ph-qr`|`qr/ph-qr` Gate only| |[Satispay](pm_satispay.md#)|`satispay`|`wallet/satispay`| |[Shopee](pm_shopee.md#)|`shopee`|`wallet/shopee` Gate only| |[Skrill Wallet](pm_skrill.md#)|`skrill`|`skrill`| |[Swish](pm_swish.md#)|`swish`|`banks/swish`| |[Thai Online Banking](pm_thailand.md#)|`online-thailand-banks`|`banks/thailand`| |[Touch&Go](pm_touchngo.md#)|`touchngo_wallet`|`wallet/touchngo`| |[TrueMoney](pm_truemoney.md#)|`true-money`|`wallet/true-money` Gate only| |[TWINT](pm_twint.md#)|`twint`|`wallet/twint`| |[Vietnamese Online Banking](pm_vietnam.md#)|`online-vietnam-banks`|`banks/vietnam`| |[WeChat](pm_wechat.md#)|`wechat`|`wallet/wechat`| |[«Выплаты на банковские счета в ЕЗПЕ \(SEPA\)»](pm_bankpayout_sepa.md#)|–|`bank-transfer/world`| |[«Локальные выплаты на банковские счета в Великобритании»](pm_bankpayout_uk.md#)|–|`bank-transfer/uk`| **На уровень выше:**[Справочники](ru_directory.md) --- # Коды брендов платёжных карт {#ru_card_codes} справочник с внутренними кодами брендов платёжных карт, которые могут использоваться при работе с платформой При работе с различными интерфейсами платёжной платформы Ecommpay для платежей с использованием карт могут применяться служебные коды [брендов](ru_glossary.md#) этих карт. В частности, такие коды могут указываться в запросах на открытие Payment Page для предварительного выбора бренда \(в значении параметра `force_payment_method_subtype`\) и передаваться в составе оповещений. Также информация о брендах платёжных карт отображается в интерфейсе Dashboard. В следующей таблице приведён перечень таких кодов. |Код|Бренд| |---|-----| |`amex`|American Express| |`maestro`|Maestro| |`mastercard`|Mastercard| |`visa`|Visa| **На уровень выше:**[Справочники](ru_directory.md) --- # Коды стран {#ru_country_codes} справочник с кодами стран в формате alpha-2 в соответствии со стандартом ISO 3166-1 При работе с различными интерфейсами платёжной платформы Ecommpay могут использоваться буквенные коды стран. Они приводятся в формате alpha-2 стандарта [ISO 3166-1](https://www.iso.org/ru/iso-3166-country-codes.html) и могут указываться, например, среди прочих сведений о пользователях в запросах на открытие Payment Pageи проведение платежей через Gate. Кроме того, такие коды применяются и в рамках данной документации. В следующей таблице приведены коды стран в формате alpha-2 в соответствии со стандартом ISO 3166-1:2020. |Код|Страна| |:-:|------| |`AD`|Андорра| |`AE`|Объединённые Арабские Эмираты| |`AF`|Афганистан| |`AG`|Антигуа и Барбуда| |`AI`|Ангилья| |`AL`|Албания| |`AM`|Армения| |`AO`|Ангола| |`AQ`|Антарктика| |`AR`|Аргентина| |`AS`|Американское Самоа| |`AT`|Австрия| |`AU`|Австралия| |`AW`|Аруба| |`AX`|Аландские острова| |`AZ`|Азербайджан| |`BA`|Босния и Герцеговина| |`BB`|Барбадос| |`BD`|Бангладеш| |`BE`|Бельгия| |`BF`|Буркина-Фасо| |`BG`|Болгария| |`BH`|Бахрейн| |`BI`|Бурунди| |`BJ`|Бенин| |`BL`|Сен-Бартелеми| |`BM`|Бермуды| |`BN`|Бруней-Даруссалам| |`BO`|Боливия| |`BQ`|Бонэйр, Синт-Эстатиус и Саба| |`BR`|Бразилия| |`BS`|Багамские Острова| |`BT`|Бутан| |`BV`|Остров Буве| |`BW`|Ботсвана| |`BY`|Беларусь| |`BZ`|Белиз| |`CA`|Канада| |`CC`|Кокосовые острова| |`CD`|Демократическая Республика Конго| |`CF`|Центрально-африканская республика| |`CG`|Республика Конго| |`CH`|Швейцария| |`CI`|Кот-д'Ивуар| |`CK`|Острова Кука| |`CL`|Чили| |`CM`|Камерун| |`CN`|Китай| |`CO`|Колумбия| |`CR`|Коста-Рика| |`CU`|Куба| |`CV`|Кабо-Верде| |`CW`|Кюрасао| |`CX`|Остров Рождества| |`CY`|Кипр| |`CZ`|Чехия| |`DE`|Германия| |`DJ`|Джибути| |`DK`|Дания| |`DM`|Доминика| |`DO`|Доминиканская Республика| |`DZ`|Алжир| |`EC`|Эквадор| |`EE`|Эстония| |`EG`|Египет| |`EH`|Сахарская Арабская Демократическая Республика| |`ER`|Эритрея| |`ES`|Испания| |`ET`|Эфиопия| |`FI`|Финляндия| |`FJ`|Фиджи| |`FK`|Фолклендские острова| |`FM`|Микронезия| |`FO`|Фарерские острова| |`FR`|Франция| |`GA`|Габон| |`GB`|Великобритания| |`GD`|Гренада| |`GE`|Грузия| |`GF`|Гвиана| |`GG`|Гернси| |`GH`|Гана| |`GI`|Гибралтар| |`GL`|Гренландия| |`GM`|Гамбия| |`GN`|Гвинея| |`GP`|Гваделупа| |`GQ`|Экваториальная Гвинея| |`GR`|Греция| |`GS`|Южная Георгия и Южные Сандвичевы Острова| |`GT`|Гватемала| |`GU`|Гуам| |`GW`|Гвинея-Бисау| |`GY`|Гайана| |`HK`|Гонконг| |`HM`|Херд и Макдональд| |`HN`|Гондурас| |`HR`|Хорватия| |`HT`|Гаити| |`HU`|Венгрия| |`ID`|Индонезия| |`IE`|Ирландия| |`IL`|Израиль| |`IM`|Остров Мэн| |`IN`|Индия| |`IO`|Британская территория в Индийском океане| |`IQ`|Ирак| |`IR`|Иран| |`IS`|Исландия| |`IT`|Италия| |`JE`|Джерси| |`JM`|Ямайка| |`JO`|Иордания| |`JP`|Япония| |`KE`|Кения| |`KG`|Кыргызстан| |`KH`|Камбоджа| |`KI`|Кирибати| |`KM`|Коморы| |`KN`|Сент-Китс и Невис| |`KP`|Корейская Народно-Демократическая Республика| |`KR`|Республика Корея| |`KW`|Кувейт| |`KY`|Острова Кайман| |`KZ`|Казахстан| |`LA`|Лаос| |`LB`|Ливан| |`LC`|Сент-Люсия| |`LI`|Лихтенштейн| |`LK`|Шри-Ланка| |`LR`|Либерия| |`LS`|Лесото| |`LT`|Литва| |`LU`|Люксембург| |`LV`|Латвия| |`LY`|Ливия| |`MA`|Марокко| |`MC`|Монако| |`MD`|Молдова| |`ME`|Черногория| |`MF`|Сен-Мартен| |`MG`|Мадагаскар| |`MH`|Маршалловы Острова| |`MK`|Северная Македония| |`ML`|Мали| |`MM`|Мьянма| |`MN`|Монголия| |`MO`|Макао| |`MP`|Северные Марианские Острова| |`MQ`|Мартиника| |`MR`|Мавритания| |`MS`|Монтсеррат| |`MT`|Мальта| |`MU`|Маврикий| |`MV`|Мальдивы| |`MW`|Малави| |`MX`|Мексика| |`MY`|Малайзия| |`MZ`|Мозамбик| |`NA`|Намибия| |`NC`|Новая Каледония| |`NE`|Нигер| |`NF`|Остров Норфолк| |`NG`|Нигерия| |`NI`|Никарагуа| |`NL`|Нидерланды| |`NO`|Норвегия| |`NP`|Непал| |`NR`|Науру| |`NU`|Ниуэ| |`NZ`|Новая Зеландия| |`OM`|Оман| |`PA`|Панама| |`PE`|Перу| |`PF`|Французская Полинезия| |`PG`|Папуа — Новая Гвинея| |`PH`|Филиппины| |`PK`|Пакистан| |`PL`|Польша| |`PM`|Сен-Пьер и Микелон| |`PN`|Острова Питкэрн| |`PR`|Пуэрто-Рико| |`PS`|Государство Палестина| |`PT`|Португалия| |`PW`|Палау| |`PY`|Парагвай| |`QA`|Катар| |`RE`|Реюньон| |`RO`|Румыния| |`RS`|Сербия| |`RU`|Россия| |`RW`|Руанда| |`SA`|Саудовская Аравия| |`SB`|Соломоновы Острова| |`SC`|Сейшельские Острова| |`SD`|Судан| |`SE`|Швеция| |`SG`|Сингапур| |`SH`|Острова Святой Елены, Вознесения и Тристан-да-Кунья| |`SI`|Словения| |`SJ`|Шпицберген и Ян-Майен| |`SK`|Словакия| |`SL`|Сьерра-Леоне| |`SM`|Сан-Марино| |`SN`|Сенегал| |`SO`|Сомали| |`SR`|Суринам| |`SS`|Южный Судан| |`ST`|Сан-Томе и Принсипи| |`SV`|Сальвадор| |`SX`|Синт-Мартен| |`SY`|Сирия| |`SZ`|Эсватини| |`TC`|Тёркс и Кайкос| |`TD`|Чад| |`TF`|Французские Южные и Антарктические Территории| |`TG`|Того| |`TH`|Таиланд| |`TJ`|Таджикистан| |`TK`|Токелау| |`TL`|Восточный Тимор| |`TM`|Туркмения| |`TN`|Тунис| |`TO`|Тонга| |`TR`|Турция| |`TT`|Тринидад и Тобаго| |`TV`|Тувалу| |`TW`|Тайвань \(Китайская республика\)| |`TZ`|Танзания| |`UA`|Украина| |`UG`|Уганда| |`UM`|Внешние малые острова США| |`US`|Соединённые Штаты Америки| |`UY`|Уругвай| |`UZ`|Узбекистан| |`VA`|Ватикан| |`VC`|Сент-Винсент и Гренадины| |`VE`|Венесуэла| |`VG`|Виргинские острова \(Великобритания\)| |`VI`|Виргинские острова \(США\)| |`VN`|Вьетнам| |`VU`|Вануату| |`WF`|Уоллис и Футуна| |`WS`|Самоа| |`YE`|Йемен| |`YT`|Майотта| |`ZA`|Южно-Африканская Республика| |`ZM`|Замбия| |`ZW`|Зимбабве| **На уровень выше:**[Справочники](ru_directory.md) --- # Коды регионов карточных платежей {#ru_region_codes} справочник с кодами регионов, применяемых при проведении через платформу Ecommpay платежей с использованием карт платёжных систем Mastercard и Visa При проведении платежей с прямым использованием карт в соответствии с правилами международных платёжных систем должны учитываться страны пользователя и мерчанта — это важно для соблюдения установленных ограничений, корректной тарификации платежей и анализа платёжного трафика \(в том числе на предмет мошенничества\). *Страной пользователя* при этом считается страна регистрации счёта, связанного с картой пользователя, а *страной мерчанта* — страна регистрации офиса или торговой точки мерчанта. Чтобы идентифицировать различные комбинации этих стран, используются специальные коды, устанавливаемые платёжными системами. При работе с платёжной платформой Ecommpay такие коды указываются в программных ответах и оповещениях о проведении платежей. В следующих таблицах приведены коды регионов, применяемые при проведении платежей с использованием карт платёжных систем Mastercard и Visa. |Код|Описание| |---|--------| |`domestic`|Страны мерчанта и пользователя совпадают| |`intereuropean`|Страны мерчанта и пользователя относятся к Европейскому региону, но только одна из них относится к Единой зоне платежей в евро\(SEPA\)| |`interregional`|Страна мерчанта относится к Европейскому региону, а страна пользователя — нет| |`non-sepa`|Страны мерчанта и пользователяразличаются, при этом обе страны относятся к Европейскому региону, но не входят в Единую зону платежей в евро\(SEPA\)| |`sepa (eea)`|Страны мерчанта и пользователяразличаются, при этом обе страны относятся к Европейскому региону, Единой зоне платежей в евро\(SEPA\) и Европейской экономической зоне\(EEA\)| |`sepa (non-eea)`|Страны мерчанта и пользователяразличаются, при этом обе страны относятся к Европейскому региону и Единой зоне платежей в евро\(SEPA\), но по крайней мере одна из них не относится к Европейской экономической зоне\(EEA\)| |Код|Описание| |---|--------| |`domestic`|Для оплат — страны мерчанта и пользователя совпадают. Для выплат — страны мерчанта и пользователя совпадают и, вместе с тем, выполняется одно из следующих условий: - страны мерчанта, пользователя, эмитента и эквайера относятся к Европейской экономической зоне\(EEA\), при этом эмитент и эквайер могут относиться к странам, отличным от страны мерчанта и пользователя - страны мерчанта, пользователя, эмитента и эквайера совпадают, при этом страна такого локального платежа может не относиться к Европейской экономической зоне \(EEA\) | |`international`|Страны мерчанта и пользователя относятся к разным регионам согласно правилам платёжной системы Visa| |`eea`|Страны мерчанта и пользователяразличаются, при этом обе страны относятся к Европейской экономической зоне\(EEA\)| |`non-eea isr, tur`|Одна из стран — Израиль или Турция, другая относится к Европейскому региону| |`non-eea che`|Одна из стран — Швейцария, другая относится к Европейскому региону и при этом не является Израилем или Турцией| |`non-eea other`|Одна из стран — Андорра, Монако, Сан-Марино или Ватикан, другая относится к Европейскому региону и при этом не является Израилем, Турцией или Швейцарией| **На уровень выше:**[Справочники](ru_directory.md) --- # Номера тестовых карт {#ru_test_cards} справочник с информацией о специализированных номерах карт, которые можно использовать для тестирования различных сценариев проведения карточных платежей ## Общая информация {#section_zk1_mkl_bbb .section} Чтобы проверять корректность технической интеграции и разных пользовательских сценариев для платежей с прямым использованием платёжных карт, со стороны мерчанта рекомендуется проводить соответствующие тестовые платежи — в рамках тестовых проектов и с использованием тестовых карт, представленных в этом справочнике. При работе с такими картами сценарий обработки каждый раз выбирается исходя из номера карты. Остальные параметры, такие как сумма платежа, имя держателя карты или проверочный код, если иное не оговорено отдельно,могут иметь произвольные значения, но должны указываться в корректном формате \(в том числе это относится и к сроку действия карты, который должен заканчиваться позднее даты платежа\). **Прим.:** Помимо тестирования платежей с прямым использованием карт в платформе поддерживаются также возможности тестирования платежей с использованием альтернативных платёжных методов \([подробнее](ru_pm_testing.md)\). С вопросами о тестировании платежей можно обращаться к специалистам технической поддержки Ecommpay. ## Тестирование оплат {#section_bhy_yqc_qrb .section} Тестирование оплат может проводиться по разным пользовательским сценариям с использованием номеров тестовых платёжных карт, представленных в следующих таблицах. |Карта|Платёжная система|Статус|Примечания| |-----|-----------------|------|----------| |`4000 0000 0000 0077`|Visa|`success`|–| |`4111 1111 1111 1111`|Visa|`decline`|–| |`4000 0000 0000 0119`|Visa|`success`|Проведение платежа с регистрацией повторяемой оплаты| |`4000 0000 0000 0119`|Visa|`decline`|Отклонение списания по ранее зарегистрированной повторяемой оплате по причине неактуальности реквизитов карты, с кодом ответа `10102`| |`4000 0000 0000 0135`|Visa|`success`|Проведение платежа с регистрацией повторяемой оплаты| |`4000 0000 0000 0135`|Visa|`decline`|Отклонение списания по ранее зарегистрированной повторяемой оплате из-за недостатка средств на счёте, с кодом ответа `10105`| |`4539 1214 1116 8251`|Visa|`decline`|Отклонение платежа из-за превышения времени обработки запроса на стороне эмитента| |`5126 1600 0035 6675`|Mastercard|`success`|Проведение платежа с частичным списанием \(при активировании такой возможности и попытке оплаты на сумму более 120 EUR, [подробнее](ru_gate_partial_approval.md)\)| |`4010 5716 7622 3548`|Visa|`success`|Проведение платежа с частичным списанием \(при активировании такой возможности и попытке оплаты на сумму более 120 EUR, [подробнее](ru_gate_partial_approval.md)\)| |Карта|Платёжная система|Статус|Примечания| |-----|-----------------|------|----------| |`4314 2200 0000 0056`|Visa|`success`|Challenge flow с отображением ACS-страницы и вводом кода| |`4477 0000 0000 0006`|Visa|`success`|Frictionless flow| |`5413 3300 0000 0019`|Mastercard|`success`|Challenge flow с отображением ACS-страницы и вводом кода| |`5544 3300 0000 0045`|Mastercard|`decline`|Challenge flow с отображением ACS-страницы и вводом кода| |`5252 0000 0000 0004`|Mastercard|`success`|Frictionless flow| ## Тестирование выплат {#section_icg_qrc_qrb .section} Тестирование выплат может проводиться с использованием номеров тестовых платёжных карт, представленных в следующей таблице. |Карта|Платёжная система|Статус| |-----|-----------------|------| |`4242 4242 4242 4242`|Visa|`success`| |`4314 2200 0000 0072`|Visa|`decline`| |`5413 3300 0000 0019`|Mastercard|`success`| |`5413 3300 0000 0035`|Mastercard|`decline`| **На уровень выше:**[Справочники](ru_directory.md) --- # Индикаторы ECI {#ru_ECI_codes} справочник с кодами Electronic Commerce Indicator, применяемыми со стороны различных платёжных систем, чтобы фиксировать информацию о результатах аутентификации пользователей с применением протокола 3‑D Secure Electronic Commerce Indicator \(ECI\) — это индикатор результата аутентификации пользователя \(держателя карты\) с применением протокола 3‑D Secure. Этот индикатор используется для фиксации того, была ли инициирована аутентификация, чем она завершилась и кто — эмитент или мерчант — признан ответственным за решение о допустимости проведения платежа и за возможную компенсацию при опротестовании этого платежа. ECI устанавливается эмитентом на стороне сервера управления доступом \(Access Control Server, ACS\) или платёжной системой по итогам попытки аутентификации, но в некоторых случаях может отсутствовать — например, если пользователь указал неверный одноразовый код \(при использовании варианта challenge flow\) или эмитент выявил высокий риск мошенничества при проверке информации о пользователе \(при использовании варианта frictionless flow\). В зависимости от результата аутентификации операция может быть продолжена или отклонена, что в том числе отражается через ECI. При этом в случаях, когда операция отклонена по итогам аутентификации, проведение платежа может быть продолжено, в частности, если подключена возможность [повторных попыток](ru_PP_Try_Again.md) проведения платежей или [каскадного проведения](ru_pp_cascading.md#) платежей. ECI применяются независимо от версии протокола и варианта аутентификации 3‑D Secure, но при этом со стороны разных платёжных систем используются разные варианты кодирования. В платёжной платформе Ecommpay ECI в общем случае представляются в виде двузначных цифровых кодов с ведущим нулём, но в отдельных случаях для них могут использоваться и другие форматы. Значения ECI передаются к веб-сервису мерчанта в итоговых оповещениях о проведении платежей в параметре `eci` объекта `operation`. В следующей таблице представлена информация об ECI различных платёжных систем для типовых платёжных сценариев. При столкновении с другими ситуациями можно обращаться за уточнениями к специалистам технической поддержки Ecommpay. |Ситуация|Ответственная сторона|ECI| |--------|---------------------|---| |Аутентификация завершена подтверждением подлинности пользователя.Операция может быть продолжена |Эмитент|- American Express — `05` - Mastercard — `02` \(в общем случае\), `07` \(при регистрации платежей типа `recurring`;[подробнее](ru_gate_payment_recurring_registration.md)\) - Visa — `05` | |Аутентификация инициирована со стороны мерчанта и эквайера, но не может быть выполнена эмитентом.Операция может быть продолжена или отклонена исходя из решения эмитента |Эмитент|- American Express — `06` - Mastercard — `01` - Visa — `06` | |Зафиксирован один из следующих случаев:- Аутентификация не инициирована со стороны мерчанта. - Аутентификация инициирована, но в результате её выполнения эмитенту не удалось подтвердить подлинность пользователя. По решению мерчанта операция может быть продолжена |Мерчант|- American Express — `07` - Mastercard — `00` - Visa — `07` | **На уровень выше:**[Справочники](ru_directory.md) ---