MyBank

Введение

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

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

Характеристика

Схема работы

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

Основные операции

Для проведения платежей и выполнения операций с использованием метода MyBank могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты — через Gate и Dashboard. При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения.

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

Сценарии использования

Проведение оплат с использованием метода MyBank осуществляется с перенаправлением пользователей к сервису MyBank, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса.

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

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

Для проведения оплаты через Payment Page с использованием метода MyBank со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом MyBank через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

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

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

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Дополнительно рекомендуется указывать имя, фамилию и код страны пользователя (в формате ISO 3166-1 alpha-2) в параметрах customer_first_name, customer_last_name и customer_country. Для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов в значениях параметров customer_first_name и customer_last_name. Если какой либо из параметров отсутствует в запросе, в платёжной форме могу отобразиться поля для ввода пользователем недостающих значений (подробнее — в разделе Дополнение информации о платежах).
4. Для предварительного выбора метода MyBank необходимо указывать код этого метода в параметре force_payment_method — mybank.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_country": "IT",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_country": "IT",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

Для оповещений о результатах оплат с применением метода MyBank используется типовой формат, описание которого представлено в статье Работа с оповещениями(подробнее).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 133661 была проведена оплата в размере 10,00 EUR.

{
        "provider_extra_fields": {
            "description": "payment 1"
        },
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "PAYMENT_513414",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "PAYMENT_513414"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16571,
                "payment_id": "140346610492",
                "auth_code": ""
            },
            "id": 5031267010142511,
            "type": "sale",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "created_date": "2025-04-04T15:51:17+0000",
            "request_id": "0c4dd430b7016b9314a266ef1afdc95c4537-05031268"
        },
        "signature": "2dJ6jrj+jcWij/FyZi1+zyxrDybkKs5feZbifx9eTRPF8g=="
    }
}

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "TEST_PAYMENT_593338",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_593338"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16571,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 5040750010141727,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "created_date": "2025-04-04T15:53:04+0000",
            "request_id": "db4a7fed5a83c6c45872675814a8968807988f-05040751"
        },
        "signature": "xmx6GdPS4hoEwPDtGWsHVjw8QA75qIUBzjA/O4SPvVbEIA=="
    }
}

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

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

• Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Проведение платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты с незамедлительным списанием средств через Payment Page.
• Работа с информацией об операциях — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

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

Для проведения оплаты через Gate с использованием метода MyBank со стороны веб-сервиса необходимо:

1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису MyBank.
3. Принять итоговое оповещение от платёжной платформы.

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

Информация о форматах запросов и оповещений, используемых для проведения оплат методом MyBank через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

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

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/banks/mybank/sale. Эта точка относится к группе /v2/payment/banks/{payment_method}/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
3. Дополнительно рекомендуется указывать следующие объекты и параметры:
   • customer — объект, содержащий сведения о пользователе:
     • first_name — имя пользователя (для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов);
     • last_name — фамилия пользователя (для предотвращения ошибок при проведении платежей рекомендуется указывать не менее 3 и не более 100 символов);
     • country — код страны пользователя в формате ISO 3166-1 alpha-2.

   Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).

4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода MyBank должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, подпись, а также может содержать различные дополнительные параметры.

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Johnson",
    "country": "IT"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Johnson",
    "country": "IT"
  }
}

Формат промежуточных оповещений для перенаправления пользователей

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

• body — объект с данными для отправки в теле запроса;
• method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
• url — параметр со ссылкой для перенаправления.

  "redirect_data": {
    "body": {},
    "method": "GET",
    "url": "https://www.example.com/pay"
  }

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

Для итоговых оповещений об оплатах с применением метода MyBank используется типовой формат, описание которого представлено в статье Работа с оповещениями(подробнее).

В следующем примере оповещение свидетельствует о том, что в рамках проекта 133661 была проведена оплата в размере 10,00 EUR.

{
        "provider_extra_fields": {
            "description": "payment 1"
        },
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "PAYMENT_513414",
            "type": "purchase",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "PAYMENT_513414"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 16571,
                "payment_id": "140346610492",
                "auth_code": ""
            },
            "id": 5031267010142511,
            "type": "sale",
            "status": "success",
            "date": "2025-04-04T15:51:42+0000",
            "created_date": "2025-04-04T15:51:17+0000",
            "request_id": "0c4dd430b7016b9314a266ef1afdc95c4537-05031268"
        },
        "signature": "2dJ6jrj+jcWij/FyZi1+zyxrDybkKs5feZbifx9eTRPF8g=="
    }
}

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
        "customer": {
            "id": "1",
            "phone": "************"
        },
        "project_id": 133661,
        "payment": {
            "id": "TEST_PAYMENT_593338",
            "type": "purchase",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "method": "MyBank",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_593338"
        },
        "operation": {
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 16571,
                "payment_id": "",
                "auth_code": ""
            },
            "id": 5040750010141727,
            "type": "sale",
            "status": "decline",
            "date": "2025-04-04T15:53:07+0000",
            "created_date": "2025-04-04T15:53:04+0000",
            "request_id": "db4a7fed5a83c6c45872675814a8968807988f-05040751"
        },
        "signature": "xmx6GdPS4hoEwPDtGWsHVjw8QA75qIUBzjA/O4SPvVbEIA=="
    }
}

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

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

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

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

Для выполнения возврата через Gate с использованием метода MyBank со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема выполнения возврата выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом MyBank через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

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

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

1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/refund.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее)),
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий к возврату или его описание;,
     • amount — сумма возврата в дробных единицах валюты (является обязательной при частичном возврате);,
     • currency — код валюты возврата в формате ISO-4217 alpha-3 (является обязательным при частичном возврате);,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "description": "test refund",
    "amount": 1000,
    "currency": "EUR"
  },
  "customer": {
    "ip_address": "192.0.2.0"
  }
}

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

Для оповещений о результатах возвратов с применением метода MyBank используется типовой формат, описание которого представлено в разделе Работа с оповещениями.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 433772 для пользователя был выполнен частичный возврат в размере 5,00 EUR.

{
        "project_id": 433772,
        "payment": {
            "id": "TEST_PAYMENT_122468",
            "type": "purchase",
            "status": "partially refunded",
            "date": "2024-12-18T14:36:34+0000",
            "method": "MyBank",
            "sum": {
                "amount": 500,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_122468"
        },
        "customer": {
            "id": "1",
            "phone": "*************"
        },
        "operation": {
            "id": 3997000012221,
            "type": "refund",
            "status": "success",
            "date": "2024-12-18T14:36:34+0000",
            "created_date": "2024-12-18T14:36:30+0000",
            "request_id": "de99efb8e28702b165b5f9f117-00003998",
            "sum_initial": {
                "amount": 500,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 500,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21414,
                "payment_id": "1418092071",
                "auth_code": ""
            }
        },
        "signature": "rq3TC04YQt1WFgSociHhJyfvjIQsj7n67UQ=="
    }

В следующем примере оповещение свидетельствует об отклонённом возврате.

 {
    "project_id": 433772,
    "payment": {
        "id": "TEST_PAYMENT_122468",
        "type": "purchase",
        "status": "partially refunded",
        "date": "2024-12-18T14:36:34+0000",
        "method": "MyBank",
        "sum": {
            "amount": 500,
            "currency": "EUR"
        },
        "description": "TEST_PAYMENT_122468"
    },
    "customer": {
        "id": "1",
        "phone": "*************"
    },
    "operation": {
        "id": 3997000012956,
        "type": "refund",
        "status": "decline",
        "date": "2024-12-22T14:22:44+0000",
        "created_date": "2024-12-22T14:22:44+0000",
        "request_id": "b3de84c717d1ba574598a637f856a-00002267",
        "sum_initial": {
            "amount": 5000,
            "currency": "EUR"
        },
        "sum_converted": {
            "amount": 5000,
            "currency": "EUR"
        },
        "code": "3283",
        "message": "Refund amount more than init amount",
        "provider": {
            "id": 21414,
            "payment_id": "1418092071",
            "auth_code": ""
        }
    },
    "signature": "PWoXcLWZbWyySxLSpFq3TC04YQt1WFgSocteIUw=="
}

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

Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:

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

Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода MyBank доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard (Old Dashboard), в том числе с помощью аналитических панелей на вкладке Analytics.

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

• Dashboard (Old Dashboard) позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

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