Проведение оплат с частичным одобрением
статья о возможности проводить через Gate оплаты, в рамках которых эмитенты одобряют частичные списания от исходных сумм платежей
Общая информация
При проведении оплат могут возникать ситуации, когда у пользователя недостаточно средств на счёте для оплаты всей требуемой суммы, но для мерчанта может быть приемлема и частичная сумма зачисления. Например, это может быть актуальным для гибкого пополнения пользовательского баланса в веб-сервисе или для бронирования услуг, полная оплата которых может быть осуществлена в дальнейшем при их фактическом оказании. Чтобы допускать такие оплаты и не отклонять их из-за недостатка средств на счетах пользователей, можно использовать функциональность частичного одобрения платежей со стороны эмитентов (Partial Approval или Partial Authorization), которая применима в рамках отдельных платёжных систем.
В платёжной платформе Ecommpay возможность проведения оплат с частичным одобрением поддерживается для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa при работе через Gate API или основную редакцию Payment Page (подробнее). Эта возможность подключается по согласованию с курирующим менеджером Ecommpay в отношении требуемых проектов, после чего со стороны веб-сервиса мерчанта можно регулировать допустимость частичных одобрений в отношении каждого инициируемого платежа. Для этого в структуре запросов на проведение платежей предусмотрен специализированный параметр allow_partial_approval.
В платёжной платформе Ecommpay поддерживается возможность частичного одобрения оплат с прямым использованием карт платёжных систем Mastercard и Visa.
Конкретная сумма, которая может использоваться в рамках оплаты с возможностью частичного одобрения, каждый раз определяется на стороне эмитента используемой платёжной карты (с учётом актуального баланса средств на счёте и правил работы эмитента). Информация об этой сумме передаётся от сервиса эмитента к платёжной платформе
Ecommpay, где одобренная сумма учитывается как актуальная сумма платежа, а исходно указанная в запросе сумма становится неактуальной. При этом важно учитывать, что такое изменение может влиять на дальнейшие операции в рамках оплаты, как например действия со средствами, заблокированными в рамках двухстадийной оплаты, или возврат средств после оплаты. Так, если исходно указанная сумма оплаты составляла 100 EUR, а фактически одобренная и оплаченная сумма оказалась равной 90 EUR, то вернуть в рамках такой оплаты можно не более 90 EUR. В свою очередь, разница между исходной и одобренной суммами может быть оплачена (и при необходимости возвращена) лишь отдельно, в рамках другой оплаты.
Применение возможности частичных одобрений не влияет на типовые схемы проведения платежей в отношении последовательности взаимодействий между веб-сервисом и платёжной платформой. Вместе с тем, при использовании этой возможности важно учитывать изменения в форматах запросов и оповещений (подробнее далее) и расширять пользовательские сценарии:
- уведомлять о допустимости частичного одобрения суммы платежа или предоставлять возможность согласия с таким вариантом оплаты — перед каждой оплатой, для которой актуальна возможность частичного одобрения;
- уведомлять о фактически одобренной и оплаченной сумме — по итогам проведения каждой оплаты, в которой было выполнено частичное списание;
- предоставлять возможность доплаты до исходно требуемой суммы через дополнительный платёж (с возможностью использования другого платёжного инструмента) — когда это актуально;
- предоставлять возможность возврата оплаченной суммы — когда это актуально;
- вносить другие дополнения — когда это уместно в рамках оказываемых услуг и специфики веб-сервиса.
Также со стороны веб-сервиса важно контролировать применение частичных одобрений. Это можно делать через сопоставление исходно запрошенной и фактически одобренной суммы для каждой оплаты, допускающей списание неполной суммы.
С вопросами, касающимися порядка подключения возможности проведения оплат с частичным одобрением, можно обращаться к курирующему менеджеру Ecommpay, с техническими вопросами, касающимися аспектов применения этой возможности — к настоящей документации и специалистам технической поддержки Ecommpay.
Особенности и ограничения
При использовании возможности оплат с частичными одобрениями стоит учитывать следующие особенности и ограничения:
- Возможность подключается в отношении конкретных проектов взаимодействия с платформой и может быть доступной для конкретных оплат только при соблюдении ряда условий:
- Частичное одобрение допустимо для используемого проекта.
- Для проведения оплаты используется Gate API или основная редакция платёжной формы Payment Page.
- Платёжным методом выступают классические карточные платежи с прямым использованием карт.
- Используемая карта выпущена и обслуживается в рамках платёжной системы Mastercard или Visa.
- Эмитент используемой карты поддерживает оплаты с частичным одобрением.
Во всех иных случаях частичное одобрение не применимо и если на счёте пользователя недостаточно средств, то оплата отклоняется, даже если в запросе была указана допустимость частичного одобрения.
Notice: Стоит учитывать, что с учётом ограничений по методам частичное одобрение не может применяться при использовании таких карточных методов, как Click to Pay и Visa Instalments, а также при проведении платежей по платёжным ссылкам. - Возможность применима для разовых оплат в одну и две стадии, а также для экспресс-оплат при хранении сведений о них на стороне веб-сервиса (со значением
2у параметраstored_card_type; подробнее). При регистрации повторяемых оплат частичные одобрения могут быть применимы для исходных оплат, но в таких случаях изменение актуальной суммы исходной оплаты не распространяется на регистрируемые серии списаний.В случае, если в запросе на инициирование автооплаты или регулярной оплаты (со значением
4или6у параметраstored_card_typeсоответственно) указывается допустимость частичного одобрения, это указание игнорируется и при недостатке средств на счёте пользователя списание отклоняется. - После частичного одобрения актуальной считается сумма платежа, одобренная эмитентом.
Это учитывается при конвертации валют (если она применяется), а также в рамках последующих операций по платежу, включая различные действия после блокировки средств (с уменьшением или увеличением суммы заблокированных средств и списанием или отменой блокировки, даже при их автоматическом инициировании) и при возврате средств пользователю.
Подключение, тестирование и использование
Чтобы подключить возможность проведения оплат с частичными одобрениями, со стороны мерчанта необходимо:
- Согласовать подключение с курирующим менеджером Ecommpay подключение этой возможности и необходимость её тестирования.
- Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить корректность работы с использованием этой возможности и сообщить о готовности к запуску.
- Получить от специалистов Ecommpay уведомление о подключении возможности.
Чтобы протестировать проведение оплат с частичным одобрением, со стороны мерчанта следует провести как минимум одну оплату в рамках тестового проекта, с формированием запроса требуемого формата и с указанием тестовых данных. При этом должны соблюдаться следующие условия:
- При попытке оплаты на сумму более
120 EUR(в дробных единицах12000) с использованием тестовой карты5126160000356675или4010571676223548должно выполняться списание ровно на120 EUR. В таких случаях остальные параметры, включая имя держателя карты или проверочный код, могут иметь произвольные значения, но должны указываться в корректном формате (в частности, срок действия карты должен заканчиваться позднее даты платежа). - В других случаях оплаты должны проводиться на полную сумму или отклоняться, в соответствии с настроенными для проекта сценариями.
{
"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"
}
}
{
"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 в запросах на проведение таких платежей (подробнее далее).
Форматы запросов
При формировании запросов на проведение оплат с возможностью частичного одобрения необходимо учитывать следующее:
- Для инициирования таких оплат каждый раз должен использоваться POST-запрос к одной из следующих конечных точек:
- для разовых одностадийных оплат при передаче реквизитов карты в явном виде, а также для повторяемых экспресс-оплат — /v2/payment/card/sale;
- для разовых одностадийных оплат при передаче идентификатора вместо реквизитов карты — /v2/payment/card/sale/saved;
- для разовых одностадийных оплат при передаче токена вместо реквизитов карты — /v2/payment/card/sale/token;
- для разовых двухстадийных оплат при передаче реквизитов карты в явном виде — /v2/payment/card/auth,
- для разовых двухстадийных оплат при передаче идентификатора вместо реквизитов карты — /v2/payment/card/auth/saved.
- В каждом запросе должны использоваться обязательные для проведения конкретной оплаты объекты и параметры (подробнее — в описаниях форматов запросов на инициирование разовых одностадийных и двухстадийных оплат, а также повторяемых экспресс-оплат).
- В каждом запросе в составе объекта
paymentдолжен передаваться параметрallow_partial_approvalсо значениемtrue. При передаче в этом параметре значенияfalse, как и при отсутствии этого параметра, частичные одобрения недопустимы. - Дополнительно могут использоваться любые другие параметры из указанных в спецификации используемой конечной точки API.
{
"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"
}
}
{
"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"
}
}
Формат оповещений
Для итоговых оповещений об оплатах с частичным одобрением используется типовой формат, описание которого представлено в статье Работа с оповещениями. При этом в объектах payment и operation в параметрах sum, sum_initial и sum_converted указываются значения с учётом суммы, одобренной эмитентом, и эту сумму следует использовать для финансового учёта и сверок.
{
"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...=="
}
{
"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...=="
}
Дополнительные материалы
При работе с оплатами с частичным одобрением могут быть полезны следующие материалы:
- Разовые оплаты — статьи о порядке проведения через Gate разовых оплат с незамедлительными списаниями (в одну стадию) и со списаниями после предварительных блокировок средств (в две стадии).
- Повторяемые оплаты — статьи о порядке регистрации и проведения через Gate различных категорий оплат с сериями повторяемых списаний, а также о возможностях управления списаниями в рамках таких оплат.
- Возвраты средств после оплат — статья о порядке выполнения через Gate возвратов по проведённым ранее оплатам разных типов.
- Работа с информацией о платежах — статьи о том, как можно получать информацию о платежах, проводимых через платформу, чтобы организовывать необходимые процессы контроля, реагирования и анализа.