Проведение оплат с частичными списаниями
Общая информация
При проведении оплат могут возникать ситуации, когда у пользователя недостаточно средств на счёте для оплаты всей требуемой суммы, но для мерчанта может быть приемлема и частичная сумма зачисления. Например, это может быть актуальным для пополнения пользовательского баланса в веб-сервисе не на полную абонентскую плату, но по крайней мере на её часть. Чтобы допускать такие оплаты и не отклонять их из-за недостатка средств на счетах пользователей, можно использовать функциональность частичного одобрения платежей со стороны эмитентов (Partial Approval или Partial Authorization), которая применима в рамках отдельных платёжных систем.
В платёжной платформе ecommpay возможность проведения оплат с частичным одобрением поддерживается для классических карточных платежей с использованием карт платёжных систем Mastercard и Visa. Эта возможность подключается по согласованию с курирующим менеджером ecommpay в отношении требуемых проектов, после чего со стороны веб-сервиса мерчанта можно регулировать допустимость частичных списаний в отношении каждого инициируемого платежа. Для этого в структуре запросов на проведение платежей предусмотрен специализированный параметр allow_partial_approval.
В платёжной платформе ecommpay поддерживается возможность частичного одобрения оплат с прямым использованием карт платёжных систем Mastercard и Visa.
Конкретная сумма, которая может использоваться в рамках оплаты с возможностью частичного списания, каждый раз определяется на стороне эмитента используемой платёжной карты (с учётом актуального баланса средств на счёте). Информация об этой сумме передаётся от эмитента к платёжной платформе
ecommpay, где одобренная сумма учитывается как актуальная сумма платежа, а исходно указанная в запросе сумма игнорируется. При этом важно учитывать, что такое изменение может влиять на дальнейшие операции в рамках оплаты, как например действия со средствами, заблокированными в рамках двухстадийной оплаты, или возврат средств после оплаты. Так, после оплаты с исходно указанной суммой 100 EUR и фактически одобренной и оплаченной суммой 90 EUR в запросе на выполнение частичного возврата может указываться сумма лишь менее 90 EUR. В свою очередь, разница между исходной и одобренной суммами может быть оплачена (и при необходимости возвращена) лишь отдельно, в рамках другой оплаты.
Применение возможности частичных списаний не влияет на типовые схемы проведения платежей в отношении последовательности взаимодействий между веб-сервисом и платёжной платформой. Вместе с тем, при использовании этой возможности важно учитывать изменения в форматах запросов и оповещений (подробнее далее) и расширять пользовательские сценарии:
- уведомлять о допустимости частичного списания суммы платежа или предоставлять возможность согласия с таким вариантом оплаты — перед каждой оплатой, для которой актуальна возможность частичного одобрения;
- уведомлять о фактически одобренной и оплаченной сумме — по итогам проведения каждой оплаты, в которой было выполнено частичное списание;
- предоставлять возможность доплаты до исходно требуемой суммы через дополнительный платёж (с возможностью использования другого платёжного инструмента) — когда это актуально;
- предоставлять возможность возврата оплаченной суммы — когда это актуально;
- вносить другие дополнения — когда это уместно в рамках оказываемых услуг и специфики веб-сервиса.
С вопросами, касающимися порядка подключения возможности проведения оплат с частичным одобрением, можно обращаться к курирующему менеджеру ecommpay, с техническими вопросами, касающимися аспектов применения этой возможности — к настоящей документации и специалистам технической поддержки ecommpay.
Особенности и ограничения
При использовании возможности оплат с частичными списаниями стоит учитывать следующие особенности и ограничения:
- Возможность допустима для оплат с использованием карт платёжных систем Mastercard и Visa в тех случаях, когда эмитент используемой карты поддерживает частичные списания.
В случаях, когда возможность не поддерживается со стороны эмитента и на счёте пользователя недостаточно средств, оплаты отклоняются.
- Возможность должна быть подключена для используемого проекта.
В случае, если эта возможность не подключена и на счёте пользователя недостаточно средств, оплата отклоняется, даже если в запросе была указана допустимость частичного списания.
- Возможность применима для разовых оплат в одну и две стадии, а также для экспресс-оплат при хранении сведений о них на стороне веб-сервиса (со значением
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, включая общую информацию о таких возвратах и описания форматов данных при работе с классическими карточными платежами.
- Работа с информацией о платежах — раздел со статьями о способах получения информации, которая может быть актуальна для контроля проведения платежей и анализа результатов при работе с платёжной платформой.