Bizum

Введение

Bizum — метод, позволяющий проводить платежи в евро с использованием банковских счетов в Испании. Bizum является одним из наиболее популярных локальных платёжных методов в Испании. Он широко известен среди испанских пользователей, которые активно используют его для безналичных оплат и ценят за удобство и надёжность. Для этого метода в платёжной платформе Ecommpay поддерживаются разовые оплаты в одну и две стадии и возвраты.

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

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

Схема работы

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

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

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

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

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

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

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

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

При использовании Payment Page для метода Bizum доступны два варианта проведения оплат: в одну и две стадии. Конкретный вариант определяется для каждого вызова платёжной формы следующим образом:

• Если в параметрах вызова формы указан тип операции (незамедлительная оплата или блокировка для последующего списания), используется указанный вариант.
• Если в параметрах вызова формы не указан тип операции, используется базовый вариант в рамках заданного проекта. Этот вариант можно настроить через обращение к специалистам технической поддержки Ecommpay.

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

Для проведения оплаты в одну или две стадии через Payment Page с использованием метода Bizum со стороны веб-сервиса в общем случае необходимо отправить соответствующий запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять два оповещения: промежуточное о необходимости выполнения подтверждающих действий пользователем и итоговое о результате операции. При этом в случае с оплатой в две стадии позднее может быть необходимым подтвердить списание заблокированных средств (подробнее).

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

В случае с оплатой в две стадии схема блокировки средств через Payment Page с использованием метода Bizum идентична представленной схеме оплаты в одну стадию, с той разницей, что вместо незамедлительного списания средств инициируется и выполняется их предварительная блокировка.

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

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

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

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от Ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта (и допускающий использование только букв и цифр в кодировке UTF-8, без специальных символов и знаков пунктуации);
   • payment_currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Для указания варианта проведения оплаты, отличного от заданного по умолчанию для используемого проекта, необходимо указывать параметр operation_type со значением sale (для незамедлительного списания средств при оплате в одну стадию) (для оплаты в одну стадию) или auth (для предварительной блокировки средств при оплате в две стадии) (для оплаты в две стадии).
4. Дополнительно рекомендуется указывать номер телефона пользователя в параметре customer_phone (в международном формате, с кодом страны; например, номер +34 91 338 8830 следует указывать как +34913388830 или 34913388830). Если этот параметр отсутствует в запросе, в платёжной форме может отобразиться поле для ввода пользователем недостающего значения (подробнее — в разделе Дополнение информации о платежах).
5. Для предварительного выбора метода Bizum необходимо указывать в параметре force_payment_method код этого метода — bizum.
6. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
7. После указания всех целевых параметров необходимо составлять подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_phone": "+34913388830",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "customer_phone": "+34913388830",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат промежуточных оповещений

При проведении каждого платежа с использованием метода Bizum от платёжной платформы к веб-сервису направляется оповещение с информацией о переводе операции sale в промежуточное состояние awaiting customer action до выполнения необходимых действий пользователем. Формат таких промежуточных оповещений является типовым (подробнее). При получении каждого такого оповещения со стороны веб-сервиса необходимо проверить его корректность, отправить синхронный подтверждающий ответ (200 OK) и ожидать последующего оповещения с информацией о результате проведения платежа.

        "customer": {
            "id": "id213"
        },
        "decision": {
            "message": "Transaction has been checked by RCS"
        },
        "operation": {
            "id": 7280000015348,
            "type": "sale",
            "status": "awaiting customer action",
            "date": "2025-11-19T06:46:13+0000",
            "created_date": "2025-11-19T06:46:02+0000",
            "request_id": "83f70191f842cbb1-00007281",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "provider": {
                "id": 21624,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "n/UPMi4E+dqlU8bPP5dsoFyWPEufQ=="
    }
}

        "customer": {
            "id": "id213"
        },
        "decision": {
            "message": "Transaction has been checked by RCS"
        },
        "operation": {
            "id": 7280000015348,
            "type": "sale",
            "status": "awaiting customer action",
            "date": "2025-11-19T06:46:13+0000",
            "created_date": "2025-11-19T06:46:02+0000",
            "request_id": "83f70191f842cbb1-00007281",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "provider": {
                "id": 21624,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "n/UPMi4E+dqlU8bPP5dsoFyWPEufQ=="
    }
}

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

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

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

{
        "project_id": 442,
        "payment": {
            "id": "Bizum_SALE_42:05_IIx8U",
            "type": "purchase",
            "status": "success",
            "date": "2026-04-14T10:42:18+0000",
            "method": "Bizum",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 2882000012699,
            "type": "sale",
            "status": "success",
            "date": "2026-04-14T10:42:18+0000",
            "created_date": "2026-04-14T10:42:06+0000",
            "request_id": "f56c90e7c8d597fd77116313-00008328",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21460,
                "payment_id": "1747996932112",
                "auth_code": ""
            }
        },
        "signature": "6RUL34SFfqATQ3jKtzdoUfXMebAEajM5ktBziSsqaNHQQ14A=="
    }

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

 {
        "sum_request": {
            "amount": 150000,
            "currency": "EUR"
        },
        "request_id": "5f15df63d-00000651",
        "transaction": {
            "id": 655000012161,
            "date": "2026-04-14T10:42:30+0000",
            "type": "purchase"
        },
        "payment": {
            "method": "Bizum",
            "date": "2026-04-14T10:42:30+0000",
            "result_code": "20000",
            "result_message": "General decline",
            "status": "decline",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "id": "Bizum_SALE_cDR7O",
            "cascading_with_redirect": false,
            "is_cascading": false,
            "split_with_redirect": false,
            "method_id": 1824,
            "provider_id": 21460
        },
        "sum_real": {
            "amount": 150000,
            "currency": "EUR"
        },
        "rrn": "",
        "company": {
            "id": 1,
            "title": "QA Company"
        },
        "general": {
            "project_id": 442,
            "payment_id": "Bizum_cDR7O",
            "signature": "7rmkfAJsjl/kklkKMy/n1YuCiHZQwbYCfJd1vp0SjXJt7LQ=="
        },
        "description": "",
        "operations": [
            {
                "id": 655000012671,
                "type": "sale",
                "status": "decline",
                "date": "2026-04-14T10:42:30+0000",
                "processing_time": null,
                "request_id": "5f140c1cb3e54832a4edc7f3606420000651",
                "sum": {
                    "amount": 150000,
                    "currency": "EUR"
                },
                "code": "20000",
                "message": "General decline",
                "provider": {
                    "id": 21460,
                    "payment_id": "1747996944360"
                }
            }
        ]
    }

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

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

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

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

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

1. Отправить соответствующий запрос (на оплату или блокировку средств), содержащий требуемые параметры и подпись, на рабочий URL Ecommpay.
2. Принять промежуточное оповещение от платёжной платформы и уведомить пользователя о необходимости выполнить подтверждающие действия.
3. В случае с оплатой в две стадии, отправить запрос на списание заблокированных средств, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay.
4. Принять итоговое оповещение от платёжной платформы.

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

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

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

Формат запросов на проведение оплат в одну и две стадии

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

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к одной из следующих конечных точек:
   • /v2/payment/banks/bizum/sale для проведения оплаты в одну стадию, эта точка относится к группе /v2/payment/banks/{payment_method}/sale.
   • /v2/payment/banks/bizum/auth для выполнения предварительной блокировки средств при оплате в две стадии, эта точка относится к группе /v2/payment/banks/{payment_method}/auth
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от Ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта (и допускающий использование только букв и цифр в кодировке UTF-8, без специальных символов и знаков пунктуации);,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью к данным); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — буквенный код валюты платежа в формате ISO-4217 alpha-3;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
3. Дополнительно в параметре phone объекта customer рекомендуется указывать номер телефона пользователя (в международном формате, с кодом страны; например, номер +34 91 338 8830 следует указывать как +34913388830 или 34913388830). Если этот параметр отсутствует в запросе, он может запрашиваться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).
4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

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

{
  "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",
    "phone": "+34913388830"
  }
}

{
  "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",
    "phone": "+34913388830"
  }
}

Формат запросов на подтверждение оплат в две стадии

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "9jceterqweXZw7jew6owgghghGYv4U...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  }

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "9jceterqweXZw7jew6owgghghGYv4U...=="
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR"
  }

Формат промежуточных оповещений

При проведении каждого платежа с использованием метода Bizum от платёжной платформы к веб-сервису направляется оповещение с информацией о переводе операции sale в промежуточное состояние awaiting customer action до выполнения необходимых действий пользователем. Формат таких промежуточных оповещений является типовым (подробнее). При получении каждого такого оповещения со стороны веб-сервиса необходимо проверить его корректность, отправить синхронный подтверждающий ответ (200 OK) и ожидать последующего оповещения с информацией о результате проведения платежа.

        "customer": {
            "id": "id213"
        },
        "decision": {
            "message": "Transaction has been checked by RCS"
        },
        "operation": {
            "id": 7280000015348,
            "type": "sale",
            "status": "awaiting customer action",
            "date": "2025-11-19T06:46:13+0000",
            "created_date": "2025-11-19T06:46:02+0000",
            "request_id": "83f70191f842cbb1-00007281",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "provider": {
                "id": 21624,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "n/UPMi4E+dqlU8bPP5dsoFyWPEufQ=="
    }
}

        "customer": {
            "id": "id213"
        },
        "decision": {
            "message": "Transaction has been checked by RCS"
        },
        "operation": {
            "id": 7280000015348,
            "type": "sale",
            "status": "awaiting customer action",
            "date": "2025-11-19T06:46:13+0000",
            "created_date": "2025-11-19T06:46:02+0000",
            "request_id": "83f70191f842cbb1-00007281",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "code": "9999",
            "message": "Awaiting processing",
            "provider": {
                "id": 21624,
                "payment_id": "",
                "auth_code": ""
            }
        },
        "signature": "n/UPMi4E+dqlU8bPP5dsoFyWPEufQ=="
    }
}

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

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

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

{
        "project_id": 442,
        "payment": {
            "id": "Bizum_SALE_42:05_IIx8U",
            "type": "purchase",
            "status": "success",
            "date": "2026-04-14T10:42:18+0000",
            "method": "Bizum",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 2882000012699,
            "type": "sale",
            "status": "success",
            "date": "2026-04-14T10:42:18+0000",
            "created_date": "2026-04-14T10:42:06+0000",
            "request_id": "f56c90e7c8d597fd77116313-00008328",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21460,
                "payment_id": "1747996932112",
                "auth_code": ""
            }
        },
        "signature": "6RUL34SFfqATQ3jKtzdoUfXMebAEajM5ktBziSsqaNHQQ14A=="
    }

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

 {
        "sum_request": {
            "amount": 150000,
            "currency": "EUR"
        },
        "request_id": "5f15df63d-00000651",
        "transaction": {
            "id": 655000012161,
            "date": "2026-04-14T10:42:30+0000",
            "type": "purchase"
        },
        "payment": {
            "method": "Bizum",
            "date": "2026-04-14T10:42:30+0000",
            "result_code": "20000",
            "result_message": "General decline",
            "status": "decline",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "id": "Bizum_SALE_cDR7O",
            "cascading_with_redirect": false,
            "is_cascading": false,
            "split_with_redirect": false,
            "method_id": 1824,
            "provider_id": 21460
        },
        "sum_real": {
            "amount": 150000,
            "currency": "EUR"
        },
        "rrn": "",
        "company": {
            "id": 1,
            "title": "QA Company"
        },
        "general": {
            "project_id": 442,
            "payment_id": "Bizum_cDR7O",
            "signature": "7rmkfAJsjl/kklkKMy/n1YuCiHZQwbYCfJd1vp0SjXJt7LQ=="
        },
        "description": "",
        "operations": [
            {
                "id": 655000012671,
                "type": "sale",
                "status": "decline",
                "date": "2026-04-14T10:42:30+0000",
                "processing_time": null,
                "request_id": "5f140c1cb3e54832a4edc7f3606420000651",
                "sum": {
                    "amount": 150000,
                    "currency": "EUR"
                },
                "code": "20000",
                "message": "General decline",
                "provider": {
                    "id": 21460,
                    "payment_id": "1747996944360"
                }
            }
        ]
    }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

{
        "project_id": 442,
        "payment": {
            "id": "Bizum_SA_r5raf",
            "type": "purchase",
            "status": "refunded",
            "date": "2026-04-14T10:41:49+0000",
            "method": "Bizum",
            "sum": {
                "amount": 0,
                "currency": "EUR"
            },
            "description": ""
        },
        "operation": {
            "id": 1315000012748,
            "type": "refund",
            "status": "success",
            "date": "2026-04-14T10:41:49+0000",
            "created_date": "2026-04-14T10:41:37+0000",
            "request_id": "0e241237b73aee5fd263edcff230eb77e38-00001316",
            "sum_initial": {
                "amount": 40000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 40000,
                "currency": "EUR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 21460,
                "payment_id": "1747996908248",
                "auth_code": ""
            }
        },
        "signature": "n7SrAOilMAiKTSYjSWZs3IJrg61Z80oT6KX6hNd2A+nXXQ=="
    }

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

 {
        "project_id": 433772,
        "payment": {
            "id": "TEST_PAYMENT_832327",
            "type": "purchase",
            "status": "success",
            "date": "2026-04-14T06:44:10+0000",
            "method": "Bizum",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "TEST_PAYMENT_832327"
        },
        "customer": {
            "id": "1"
        },
        "errors": [
            {
                "code": "2701",
                "message": "Rules Failed Code",
                "description": "fatal: RULES_FAILED_CODE"
            },
            {
                "code": "3358",
                "message": "Operation amount is less than limit",
                "description": "Operation amount is less than limit"
            }
        ],
        "operation": {
            "id": 2764000012860,
            "type": "refund",
            "status": "decline",
            "date": "2026-04-14T06:44:10+0000",
            "created_date": "2026-04-14T06:44:09+0000",
            "request_id": "bf5881904060b767f36d20001711",
            "sum_initial": {
                "amount": 100,
                "currency": "MXN"
            },
            "sum_converted": {
                "amount": 18,
                "currency": "USD"
            },
            "code": "2701",
            "message": "Rules Failed Code",
            "provider": {
                "id": 21460,
                "payment_id": ""
            }
        },
        "signature": "zAmT6dAKwcgu07ZNvA2q+kt53WDPRIRv/yBak0GA=="
    }

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

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

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