Проведение оплат с частичными списаниями
Общая информация
При проведении оплат могут возникать ситуации, когда у пользователя недостаточно средств на счёте для оплаты всей требуемой суммы, но для мерчанта может быть приемлема и частичная сумма зачисления. Например, это может быть актуальным для пополнения пользовательского баланса в веб-сервисе не на полную абонентскую плату, но по крайней мере на её часть. Чтобы допускать такие оплаты и не отклонять их из-за недостатка средств на счетах пользователей, можно использовать функциональность частичного одобрения платежей со стороны эмитентов (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соответственно) указывается допустимость частичного списания, это указание игнорируется и при недостатке средств на счёте пользователя списание отклоняется. - После частичного одобрения актуальной считается сумма платежа, одобренная эмитентом.
Это учитывается при конвертации валют (если она применяется), а также в рамках последующих операций по платежу, включая различные действия при проведении двухстадийной оплаты (с уменьшением или увеличением суммы заблокированных средств и списанием или отменой блокировки, даже при их автоматическом инициировании).
Подключение и использование
Чтобы подключить возможность проведения оплат с частичными списаниями, со стороны мерчанта необходимо cогласовать с курирующим менеджером ecommpay её подключение для требуемых проектов и получить от специалистов ecommpay уведомление о подключении.
Чтобы использовать ранее подключённую возможность проведения оплат с частичными списаниями для конкретного платежа, со стороны веб-сервиса необходимо указать специализированный параметр 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, включая общую информацию о таких возвратах и описания форматов данных при работе с классическими карточными платежами.
- Работа с информацией о платежах — раздел со статьями о способах получения и обработки информации о платежах, проводимых в платформе.